Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
docs(flow): document declarative conversational flows (#7035)
João Moura4dfd074fae84
diff --git a/docs/edge/ar/guides/flows/conversational-flows.mdx b/docs/edge/ar/guides/flows/conversational-flows.mdxindex 371de79be..e96814b82 100644--- a/docs/edge/ar/guides/flows/conversational-flows.mdx+++ b/docs/edge/ar/guides/flows/conversational-flows.mdx@@ -426,6 +426,70 @@ class SupportFlow(Flow[ConversationState]):يمكن لـ `ConversationConfig.visible_agent_outputs` رفع النتائج الخاصة لـ agents محددين إلى عامة عالمياً (`"all"` أو قائمة بالأسماء).+## تعريف تدفق محادثاتي بصيغة JSON/YAML++يمكن لـ [التدفق التعريفي](/edge/en/concepts/cli) أن يكون محادثاتيًا أيضًا. أضف كتلة `conversational` في المستوى الأعلى وعرّف مساراتك الخاصة كطرق تستمع (`listen`) إلى تسمية مسار:++```yaml+schema: crewai.flow/v1+name: SupportFlow++conversational:+ system_prompt: You are a terse support assistant.+ llm: gpt-4o-mini+ router:+ llm: gpt-4o-mini++methods:+ handle_order:+ description: Order status, shipping and delivery questions.+ listen: order+ do:+ call: agent+ with:+ role: Support specialist+ goal: Answer order questions accurately+ backstory: Knows the fulfilment pipeline.+ input: "${state.current_user_message}"+```++تعريف الكتلة هو الاشتراك نفسه — القيمة الافتراضية لـ `enabled` هي `true`. اضبطها على `enabled: false` للاحتفاظ بالإعدادات مع إيقاف المحادثة.++تُوفَّر لك ثلاثة أشياء:++| المُوفَّر | التفاصيل |+|----------|--------|+| الرسم البياني المدمج | تُضاف `route_conversation` و`converse_turn` و`end_conversation` و`answer_from_history_turn` تلقائيًا. عرّف طريقة بأحد هذه الأسماء لتجاوزها. |+| حالة المحادثة | تُستخدم `ConversationState` عندما لا تحتوي التعريفة على كتلة `state`. لإضافة حقول، وجّه `state` إلى نموذج Pydantic يرث من `ConversationState`. |+| كتالوج المسارات | يُبنى من الطرق التي تعلن تسمية `listen`. وصف كل طريقة (`description`) هو ما يقرأه نموذج التوجيه عند الاختيار بين المسارات. |++شغّله من Python بنفس واجهات الجولة المستخدمة مع تدفق محادثاتي معرّف بصنف:++```python+from crewai.flow import Flow++flow = Flow.from_declaration(path="flow.yaml")++try:+ flow.handle_turn("Where is my order?", session_id="session-1")+finally:+ flow.finalize_session_traces()+```++### تسمية المسارات++تتشارك تسميات المسارات وأسماء الطرق مساحة اسم واحدة للمشغّلات، لذا يجب ألا يحمل المعالج اسم المسار الذي يستمع إليه — يُرفض `create_video` الذي يستمع إلى `create_video` عند بناء التدفق. استخدم بادئة `handle_*`.++### ما لا يمكن للتعريفة التعبير عنه++| غير قابل للتعبير | استخدم بدلًا منه |+|-----------------|-------------|+| مثيل `LLM` حي أو `BaseLLM` مخصص | سلسلة معرّف النموذج، مثل `gpt-4o-mini` |+| `router.response_format` كصنف نموذج | احذفه؛ يولّد الإطار واحدًا. يُتجاهل المرجع أو المخطط مع تحذير |+| تجاوزات `route_turn()` / `can_answer_from_history()` | اكتب التدفق بلغة Python، أو وجّه `do` لطريقة إلى مرجع `call: code` |++لا يملك `crewai run` حلقة محادثة بعد: فهو يبلّغ أن التدفق محادثاتي ويخرج بدلًا من تنفيذ جولة واحدة. شغّل التدفق المحادثاتي التعريفي من Python عبر `handle_turn()` أو `stream_turn()` أو `chat()`.+## التتبع عبر الجولاتمع `defer_trace_finalization=True` (افتراضي في `ConversationalConfig`):diff --git a/docs/edge/en/guides/flows/conversational-flows.mdx b/docs/edge/en/guides/flows/conversational-flows.mdxindex b8fd7f43d..e42c4966b 100644--- a/docs/edge/en/guides/flows/conversational-flows.mdx+++ b/docs/edge/en/guides/flows/conversational-flows.mdx@@ -491,6 +491,70 @@ Inside a `@listen(label)` handler, choose:`ConversationConfig.visible_agent_outputs` can promote specific agents' private results to public globally (`"all"`, or a list of agent names).+## Declaring a conversational flow in JSON/YAML++A [declarative Flow](/edge/en/concepts/cli) can be conversational too. Add a top-level `conversational` block and declare your own routes as methods that `listen` to a route label:++```yaml+schema: crewai.flow/v1+name: SupportFlow++conversational:+ system_prompt: You are a terse support assistant.+ llm: gpt-4o-mini+ router:+ llm: gpt-4o-mini++methods:+ handle_order:+ description: Order status, shipping and delivery questions.+ listen: order+ do:+ call: agent+ with:+ role: Support specialist+ goal: Answer order questions accurately+ backstory: Knows the fulfilment pipeline.+ input: "${state.current_user_message}"+```++Declaring the block is the opt-in — `enabled` defaults to `true`. Set `enabled: false` to keep the configuration while turning chat off.++Three things are supplied for you:++| Supplied | Detail |+|----------|--------|+| The built-in graph | `route_conversation`, `converse_turn`, `end_conversation` and `answer_from_history_turn` are added automatically. Declare a method under one of those names to override it. |+| Conversation state | `ConversationState` is used when the declaration has no `state` block. To add fields, point `state` at a Pydantic model that extends `ConversationState`. |+| The route catalog | Built from the methods that declare a `listen` label. Each method's `description` is what the routing model reads when choosing between routes. |++Run it from Python with the same turn APIs as a class-based conversational Flow:++```python+from crewai.flow import Flow++flow = Flow.from_declaration(path="flow.yaml")++try:+ flow.handle_turn("Where is my order?", session_id="session-1")+finally:+ flow.finalize_session_traces()+```++### Naming routes++Route labels and method names share one trigger namespace, so a handler must not be named after the route it listens to — `create_video` listening to `create_video` is rejected when the flow is built. Use a `handle_*` prefix.++### What a declaration cannot express++| Not expressible | Use instead |+|-----------------|-------------|+| A live `LLM` instance or a custom `BaseLLM` | A model id string, such as `gpt-4o-mini` |+| `router.response_format` as a model class | Omit it; the framework synthesizes one. A ref or schema is ignored with a warning |+| `route_turn()` / `can_answer_from_history()` overrides | Author the Flow in Python, or point a method's `do` at a `call: code` ref |++`crewai run` has no chat loop yet: it reports that the flow is conversational and exits rather than running a single turn. Drive a declarative conversational flow from Python with `handle_turn()`, `stream_turn()` or `chat()`.+## Tracing across turnsWith `defer_trace_finalization=True` (default in `ConversationConfig`):diff --git a/docs/edge/ko/guides/flows/conversational-flows.mdx b/docs/edge/ko/guides/flows/conversational-flows.mdxindex 3a18cd1da..fd3a7c256 100644--- a/docs/edge/ko/guides/flows/conversational-flows.mdx+++ b/docs/edge/ko/guides/flows/conversational-flows.mdx@@ -427,6 +427,70 @@ LLM router를 우회해 프로그램적으로 라우트를 선택하려면 `rout`ConversationConfig.visible_agent_outputs`로 특정 에이전트의 private 결과를 전역적으로 public으로 승격할 수 있습니다 (`"all"` 또는 이름 리스트).+## JSON/YAML로 대화형 플로우 선언하기++[선언적 플로우](/edge/en/concepts/cli)도 대화형이 될 수 있습니다. 최상위 `conversational` 블록을 추가하고, 라우트 레이블을 `listen`하는 메서드로 직접 라우트를 선언하세요:++```yaml+schema: crewai.flow/v1+name: SupportFlow++conversational:+ system_prompt: You are a terse support assistant.+ llm: gpt-4o-mini+ router:+ llm: gpt-4o-mini++methods:+ handle_order:+ description: Order status, shipping and delivery questions.+ listen: order+ do:+ call: agent+ with:+ role: Support specialist+ goal: Answer order questions accurately+ backstory: Knows the fulfilment pipeline.+ input: "${state.current_user_message}"+```++블록을 선언하는 것 자체가 옵트인입니다 — `enabled`의 기본값은 `true`입니다. 설정은 유지하면서 채팅만 끄려면 `enabled: false`로 지정하세요.++세 가지가 자동으로 제공됩니다:++| 제공 항목 | 설명 |+|----------|--------|+| 내장 그래프 | `route_conversation`, `converse_turn`, `end_conversation`, `answer_from_history_turn`이 자동으로 추가됩니다. 같은 이름의 메서드를 선언하면 재정의됩니다. |+| 대화 상태 | 선언에 `state` 블록이 없으면 `ConversationState`가 사용됩니다. 필드를 추가하려면 `ConversationState`를 상속한 Pydantic 모델을 `state`에 지정하세요. |+| 라우트 카탈로그 | `listen` 레이블을 선언한 메서드들로부터 구성됩니다. 각 메서드의 `description`이 라우팅 모델이 라우트를 선택할 때 읽는 내용입니다. |++클래스 기반 대화형 플로우와 동일한 턴 API로 Python에서 실행합니다:++```python+from crewai.flow import Flow++flow = Flow.from_declaration(path="flow.yaml")++try:+ flow.handle_turn("Where is my order?", session_id="session-1")+finally:+ flow.finalize_session_traces()+```++### 라우트 이름 짓기++라우트 레이블과 메서드 이름은 하나의 트리거 네임스페이스를 공유하므로, 핸들러 이름이 자신이 listen하는 라우트와 같으면 안 됩니다 — `create_video`가 `create_video`를 listen하면 플로우 생성 시 거부됩니다. `handle_*` 접두사를 사용하세요.++### 선언으로 표현할 수 없는 것++| 표현 불가 | 대신 사용 |+|-----------------|-------------|+| 살아 있는 `LLM` 인스턴스나 커스텀 `BaseLLM` | `gpt-4o-mini` 같은 모델 ID 문자열 |+| 모델 클래스로서의 `router.response_format` | 생략하세요; 프레임워크가 생성합니다. ref나 스키마는 경고와 함께 무시됩니다 |+| `route_turn()` / `can_answer_from_history()` 재정의 | 플로우를 Python으로 작성하거나, 메서드의 `do`를 `call: code` ref로 지정하세요 |++`crewai run`에는 아직 채팅 루프가 없습니다: 단일 턴을 실행하는 대신 플로우가 대화형임을 알리고 종료합니다. 선언적 대화형 플로우는 Python에서 `handle_turn()`, `stream_turn()`, `chat()`으로 실행하세요.+## 턴 간 트레이싱`defer_trace_finalization=True` (`ConversationalConfig` 기본값):diff --git a/docs/edge/pt-BR/guides/flows/conversational-flows.mdx b/docs/edge/pt-BR/guides/flows/conversational-flows.mdxindex 10ffdcbd6..9012bbe6e 100644--- a/docs/edge/pt-BR/guides/flows/conversational-flows.mdx+++ b/docs/edge/pt-BR/guides/flows/conversational-flows.mdx@@ -428,6 +428,70 @@ Dentro de um handler `@listen(label)`, escolha:`ConversationConfig.visible_agent_outputs` pode promover globalmente os resultados privados de agentes específicos para públicos (`"all"` ou lista de nomes).+## Declarando um flow conversacional em JSON/YAML++Um [flow declarativo](/edge/en/concepts/cli) também pode ser conversacional. Adicione um bloco `conversational` no nível raiz e declare suas próprias rotas como métodos que escutam (`listen`) um rótulo de rota:++```yaml+schema: crewai.flow/v1+name: SupportFlow++conversational:+ system_prompt: You are a terse support assistant.+ llm: gpt-4o-mini+ router:+ llm: gpt-4o-mini++methods:+ handle_order:+ description: Order status, shipping and delivery questions.+ listen: order+ do:+ call: agent+ with:+ role: Support specialist+ goal: Answer order questions accurately+ backstory: Knows the fulfilment pipeline.+ input: "${state.current_user_message}"+```++Declarar o bloco já é o opt-in — `enabled` tem valor padrão `true`. Use `enabled: false` para manter a configuração e desligar o chat.++Três coisas são fornecidas para você:++| Fornecido | Detalhe |+|----------|--------|+| O grafo interno | `route_conversation`, `converse_turn`, `end_conversation` e `answer_from_history_turn` são adicionados automaticamente. Declare um método com um desses nomes para sobrescrevê-lo. |+| Estado da conversa | `ConversationState` é usado quando a declaração não tem bloco `state`. Para adicionar campos, aponte `state` para um modelo Pydantic que estenda `ConversationState`. |+| O catálogo de rotas | Construído a partir dos métodos que declaram um rótulo `listen`. O `description` de cada método é o que o modelo de roteamento lê ao escolher entre rotas. |++Execute a partir do Python com as mesmas APIs de turno de um Flow conversacional baseado em classe:++```python+from crewai.flow import Flow++flow = Flow.from_declaration(path="flow.yaml")++try:+ flow.handle_turn("Where is my order?", session_id="session-1")+finally:+ flow.finalize_session_traces()+```++### Nomeando rotas++Rótulos de rota e nomes de métodos compartilham um único namespace de gatilhos, então um handler não pode ter o nome da rota que escuta — `create_video` escutando `create_video` é rejeitado na construção do flow. Use o prefixo `handle_*`.++### O que uma declaração não consegue expressar++| Não expressável | Use no lugar |+|-----------------|-------------|+| Uma instância `LLM` viva ou um `BaseLLM` customizado | Uma string de id de modelo, como `gpt-4o-mini` |+| `router.response_format` como classe de modelo | Omita; o framework sintetiza uma. Um ref ou schema é ignorado com um aviso |+| Overrides de `route_turn()` / `can_answer_from_history()` | Escreva o Flow em Python, ou aponte o `do` de um método para um ref `call: code` |++O `crewai run` ainda não tem loop de chat: ele informa que o flow é conversacional e sai, em vez de rodar um único turno. Conduza um flow conversacional declarativo pelo Python com `handle_turn()`, `stream_turn()` ou `chat()`.+## Tracing entre turnosCom `defer_trace_finalization=True` (padrão em `ConversationalConfig`):diff --git a/lib/cli/src/crewai_cli/run_declarative_flow.py b/lib/cli/src/crewai_cli/run_declarative_flow.pyindex 927965f59..0b7cb8cd2 100644--- a/lib/cli/src/crewai_cli/run_declarative_flow.py+++ b/lib/cli/src/crewai_cli/run_declarative_flow.py@@ -72,6 +72,18 @@ def run_declarative_flow(definition: str | Path, inputs: str | None = None) -> Nprovided = parse_inputs_json(inputs) or {}flow = load_declarative_flow(definition)++ if _flow_is_conversational(flow):+ click.secho(+ " This flow declares `conversational`, and `crewai run` has no chat "+ "loop yet — it would run a single turn and exit.\n"+ " Drive it from Python for now: `flow.chat()` for a terminal REPL, "+ "or `flow.handle_turn(message, session_id=...)` per message.",+ fg="yellow",+ err=True,+ )+ raise SystemExit(1)+resolved_inputs = _resolve_flow_inputs(flow, provided)# The TUI is the interactive default. Headless contexts run directly on the@@ -156,6 +168,20 @@ def _run_declarative_flow_tui(return app._crew_result+def _flow_is_conversational(flow: Flow[Any]) -> bool:+ """True if the declaration turns on conversational mode.++ Fails closed: a flow we cannot inspect runs the normal single-kickoff path+ rather than being blocked from running at all.+ """+ try:+ conversational = flow._definition.conversational+ except AttributeError:+ logger.debug("Could not inspect flow for conversational mode", exc_info=True)+ return False+ return conversational is not None and conversational.enabled++def _flow_uses_human_feedback(flow: Flow[Any]) -> bool:"""True if any declarative method declares ``@human_feedback``.diff --git a/lib/cli/tests/test_run_declarative_flow.py b/lib/cli/tests/test_run_declarative_flow.pyindex 378156725..32df4be7a 100644--- a/lib/cli/tests/test_run_declarative_flow.py+++ b/lib/cli/tests/test_run_declarative_flow.py@@ -611,3 +611,48 @@ def test_flow_method_types_from_definition() -> None:}# No definition → empty map, no error.assert run_declarative_flow_module._flow_method_types(SimpleNamespace()) == {}+++CONVERSATIONAL_FLOW_YAML = """schema: crewai.flow/v1+name: SupportFlow+conversational:+ llm: gpt-4o-mini+methods:+ handle_order:+ description: Order status questions.+ listen: order+ do:+ call: expression+ expr: "'shipped'"+"""+++def test_run_declarative_flow_refuses_a_conversational_flow(+ tmp_path: Path, capsys: pytest.CaptureFixture[str]+) -> None:+ definition_path = tmp_path / "flow.yaml"+ definition_path.write_text(CONVERSATIONAL_FLOW_YAML, encoding="utf-8")++ with pytest.raises(SystemExit):+ run_declarative_flow_module.run_declarative_flow(str(definition_path))++ err = capsys.readouterr().err+ assert "has no chat loop yet" in err+ assert "flow.chat()" in err+++def test_run_declarative_flow_still_runs_a_disabled_conversational_flow(+ tmp_path: Path, capsys: pytest.CaptureFixture[str]+) -> None:+ definition_path = tmp_path / "flow.yaml"+ definition_path.write_text(+ CONVERSATIONAL_FLOW_YAML.replace(+ "conversational:\n llm: gpt-4o-mini",+ "conversational:\n enabled: false",+ ).replace(" listen: order\n", " start: true\n"),+ encoding="utf-8",+ )++ run_declarative_flow_module.run_declarative_flow(str(definition_path))++ assert capsys.readouterr().out == "shipped\n"diff --git a/lib/crewai/src/crewai/flow/skill.py b/lib/crewai/src/crewai/flow/skill.pyindex ad2862197..ca26113e8 100644--- a/lib/crewai/src/crewai/flow/skill.py+++ b/lib/crewai/src/crewai/flow/skill.py@@ -26,6 +26,8 @@ SKIP_BY_MODEL: dict[str, str] = {"FlowConfigDefinition": "config","FlowHumanFeedbackDefinition": "hitl","FlowPersistenceDefinition": "persistence",+ "FlowConversationalDefinition": "conversational",+ "FlowConversationalRouterDefinition": "conversational",}FIELD_TYPE_OVERRIDES: dict[tuple[str, str], str] = {@@ -138,6 +140,8 @@ MODEL_TITLES = {"FlowConfigDefinition": "Config","FlowPersistenceDefinition": "Persistence","FlowHumanFeedbackDefinition": "Human Feedback",+ "FlowConversationalDefinition": "Conversational",+ "FlowConversationalRouterDefinition": "Conversational Router",}@@ -280,6 +284,35 @@ MODEL_SPECS: tuple[ModelSpec, ...] = ("Human Feedback","methods.<name>.human_feedback",),+ ModelSpec(+ "FlowConversationalDefinition",+ "Conversational",+ "conversational",+ descriptions={+ "enabled": "Whether conversational mode is active. Declaring the conversational block is the opt-in, so leave this out unless you are turning chat off with `false`.",+ "llm": "Model id used by the built-in `converse` handler, and the router's fallback model.",+ "system_prompt": "System message for the built-in `converse` handler. Omit for the framework default; use an empty string for none.",+ "default_intents": "Outcome labels classified before routing. Requires `intent_llm`.",+ "answer_from_history_llm": "Setting this enables the optional `answer_from_history` route, which answers from the transcript without invoking a route handler.",+ "visible_agent_outputs": "Agent names whose recorded results are promoted to user-visible assistant messages, or `all`.",+ "builtin_routes": "Route labels the framework handles itself. Do not add your own routes here; declare them as a method `listen` label.",+ "internal_routes": "Route labels the framework handles that are excluded from the router's catalog.",+ },+ examples=True,+ ),+ ModelSpec(+ "FlowConversationalRouterDefinition",+ "Conversational Router",+ "conversational.router",+ descriptions={+ "prompt": "Domain framing for the routing decision: persona, policy, voice. Do not list routes here; the catalog is built automatically.",+ "routes": "Route labels the router may choose. Omit to infer them from the methods that declare a `listen` label.",+ "route_descriptions": "Per-route text for the router's catalog. A method's `description` is used when a route has no entry here.",+ "default_intent": "Route used when no routing model is configured or the call fails.",+ "fallback_intent": "Route used when the model returns a label that is not in the catalog.",+ "response_format": "Leave this out in a declaration. A declaration cannot carry a model class, so it is ignored with a warning and the framework synthesizes one.",+ },+ ),)_SPECS_BY_NAME: dict[str, ModelSpec] = {spec.name: spec for spec in MODEL_SPECS}diff --git a/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2 b/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2index 987c252e2..5b270107d 100644--- a/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2+++ b/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2@@ -148,6 +148,10 @@ Dynamic value rules:- Do not set `config.stream: true` unless the caller is expected to consume a streaming result. For normal generated flows and CLI smoke tests, omit it.{% if include_conversational %}- Do not put conversational settings under `state`, `config`, or a method. Use top-level `conversational` only when the user asks for a chat or conversation flow.+- Do not declare `route_conversation`, `converse_turn`, `end_conversation`, or `answer_from_history_turn` unless you are deliberately replacing one. Declaring the `conversational` block adds them for you, and a method you declare under one of those names overrides the built-in.+- Do not name a route handler the same as the route it listens to. Route labels and method names share one trigger namespace, so `create_video` listening to `create_video` is rejected. Use `handle_create_video`.+- Do not declare `state` for a chat flow unless it needs extra fields. The conversational state shape is supplied by default, and a custom state must extend it.+- Do describe every custom route, either with the handler's `description` or an entry in `conversational.router.route_descriptions`. That text is what the routing model reads to choose between routes; a route with neither is offered to it unlabelled.{% endif %}{% if include_each_action %}- Do not use `each` without at least one named step.diff --git a/lib/crewai/tests/test_flow_definition.py b/lib/crewai/tests/test_flow_definition.pyindex 8a714676d..13a5c7cca 100644--- a/lib/crewai/tests/test_flow_definition.py+++ b/lib/crewai/tests/test_flow_definition.py@@ -5,6 +5,7 @@ import importlibimport inspectimport loggingfrom pathlib import Path+import refrom typing import Annotated, Literalimport pytest@@ -1479,6 +1480,40 @@ def test_skill_documents_flow_wiring():assert example["code"] in skill+def test_skill_renders_both_conversational_sections():+ """Both models must render; the router shares no section with its parent.++ Non-union sections render only their first model, so grouping them would+ drop the router and leave the link to it without a target.+ """+ skill = flow_definition.FlowDefinition.skill()++ assert "### Conversational (`conversational`)" in skill+ assert "### Conversational Router (`conversational.router`)" in skill++ link = "[Conversational Router (`conversational.router`)]"+ assert link in skill+ anchor = re.search(re.escape(link) + r"\((#[^)]+)\)", skill).group(1)+ assert anchor == "#conversational-router-conversationalrouter"+++def test_skill_documents_every_conversational_field():+ skill = flow_definition.FlowDefinition.skill()+ section = skill[skill.index("### Conversational (`conversational`)") :]++ for field in flow_definition.FlowConversationalDefinition.model_fields:+ assert f"`{field}`" in section, field+ for field in flow_definition.FlowConversationalRouterDefinition.model_fields:+ assert f"`{field}`" in section, field+++def test_skill_conversational_skip_suppresses_both_sections():+ skill = flow_definition.FlowDefinition.skill(skips=["conversational"])++ assert "### Conversational" not in skill+ assert "conversational-router" not in skill++def test_skill_can_render_json_examples():skill = flow_definition.FlowDefinition.skill(examples_format="json")