mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-09-23 19:30:45 +00:00
4b9b8bcbb9
* feat(telemetry): record what kind of exception ended a flow Flow failures are visible but undiagnosable. Live data shows roughly 17% of flows ending in outcome=failed, and 72% of AgentExecutor failures completing in under 200ms - far too fast to be an LLM call - but nothing records what the failure actually is, so there is no way to tell a real defect from a user pressing Ctrl-C. Record the exception's class name as error_type on Flow Completed and Flow Method Failed. The class name only: str(error) is never read, because it routinely carries prompts, model output, file paths and credentials. The isidentifier() check is the allowlist that enforces it - any message text reaching that argument carries a space or punctuation and is dropped - and it lives inside Telemetry rather than at the call site so a future caller cannot bypass it. Method names and flow state remain unrecorded. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * docs(frontend): point the frontend guides at their edge paths The frontend guides added in #6686 exist only under edge - they are not in any frozen version snapshot - but their 80 internal links use the bare /en/guides/frontend/... form, which resolves against the released versions where those pages do not exist. mint broken-links fails on every one of them, which blocks every open PR, not only the one that added them. Use the /edge/en/... form the repo already uses for other edge-only pages (concepts/streaming, learn/execution-boundary-hooks). Anchors are preserved. No page content changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
107 lines
5.6 KiB
Plaintext
107 lines
5.6 KiB
Plaintext
---
|
|
title: Conversational Flows
|
|
description: Serve native, session-aware CrewAI Flows over AG-UI with managed conversation state and full frontend parity.
|
|
icon: comments
|
|
mode: "wide"
|
|
---
|
|
|
|
## Three execution shapes, one bridge
|
|
|
|
Behind the AG-UI bridge, a CrewAI backend can take one of three shapes. Knowing which one you are serving decides how you author the backend, not how you build the frontend.
|
|
|
|
| Shape | What it is | How it is entered |
|
|
| --- | --- | --- |
|
|
| **Regular Flows** | Author-controlled `@start`/`@listen`/`@router` graphs. The default used throughout these guides. | `kickoff` / `astream` |
|
|
| **Conversational Flows** | Native, session-aware, turn-based Flows with managed conversation state. | `stream_turn(message, session_id=...)` |
|
|
| **Crews** | Closed autonomous task/agent loops. Basic chat only, a separate compatibility path. | Not the focus here. |
|
|
|
|
Conversational Flows are a newer CrewAI capability, and an important thing to be clear about up front: **they are Flows, not Crews.** They now run at full regular-Flow feature parity. This page introduces them and shows how they fit the rest of the frontend guides.
|
|
|
|
<Note>
|
|
Reach for a Conversational Flow when you want native multi-turn conversation with CrewAI managing session state and history for you, rather than wiring turn and state handling into a regular Flow yourself. If you are new here, start with the [Frontend Overview](/edge/en/guides/frontend/overview) for the base server, runtime, and provider setup.
|
|
</Note>
|
|
|
|
## Register a Conversational Flow
|
|
|
|
You register a Conversational Flow through the same endpoint helper as any other Flow, with one extra argument: `conversational=True`.
|
|
|
|
```python
|
|
# server.py
|
|
from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
|
|
|
|
add_crewai_flow_fastapi_endpoint(
|
|
app,
|
|
flow,
|
|
"/conversation",
|
|
conversational=True,
|
|
)
|
|
```
|
|
|
|
Two requirements must hold for this to work:
|
|
|
|
- The Flow instance declares `conversational = True`.
|
|
- The Flow exposes CrewAI's public, callable `stream_turn(message, session_id=...)`.
|
|
|
|
Detection is capability-based, not version-gated: the bridge checks that the Flow actually offers turn-based conversation, rather than keying off a version number.
|
|
|
|
<Warning>
|
|
If those requirements are not met, the request fails loudly with a `RUN_ERROR` (code `AGUI_CREWAI_CONVERSATIONAL_FLOW_UNSUPPORTED`). It never silently falls back to regular kickoff semantics, so you always know exactly which path you are on.
|
|
</Warning>
|
|
|
|
Authoring the Flow itself, including how you implement `stream_turn`, belongs to CrewAI's Conversational Flows documentation. This page stays at the registration and integration boundary.
|
|
|
|
## Session and state
|
|
|
|
Conversational Flows manage session state and history for you across turns. You do not re-thread history manually.
|
|
|
|
- The AG-UI `threadId` **is** the CrewAI conversation `session_id`. The same thread is the same conversation.
|
|
- Before each turn the bridge hydrates the Flow's state and conversation history, then calls `stream_turn`. CrewAI restores the stored session state, and a per-request overlay reapplies the incoming AG-UI state and history so the browser's latest edits win over stale storage.
|
|
|
|
The result: from the backend author's side, each turn arrives already carrying the conversation's state, and CrewAI persists what you write for the next turn.
|
|
|
|
## Frontend parity
|
|
|
|
This is the point to hold onto: **Conversational Flows run through the same event pipeline as regular Flows, so the frontend code is identical.**
|
|
|
|
There is no Conversational-Flow-specific frontend API. Every feature in these guides works exactly the same way with a Conversational Flow as it does with a regular Flow, using the same hooks and components:
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/edge/en/guides/frontend/tool-based-generative-ui">
|
|
Map agent tool calls to your React components.
|
|
</Card>
|
|
<Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
|
|
Render the Flow's live state as it works.
|
|
</Card>
|
|
<Card title="Shared State" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
|
|
Keep agent state and app UI in two-way sync.
|
|
</Card>
|
|
<Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
|
|
Pause the agent for user approval or input mid-turn.
|
|
</Card>
|
|
<Card title="Predictive State" icon="gauge-high" href="/edge/en/guides/frontend/predictive-state-updates">
|
|
Stream in-progress tool arguments into state.
|
|
</Card>
|
|
<Card title="Reasoning" icon="brain" href="/edge/en/guides/frontend/reasoning">
|
|
Show the model's thinking in the chat.
|
|
</Card>
|
|
<Card title="A2UI" icon="table-cells" href="/edge/en/guides/frontend/a2ui">
|
|
Render agent-authored UI from a component catalog.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
The only difference is on the backend: how you author the Flow (turn-based `stream_turn` with managed session state) and the `conversational=True` registration. Once the endpoint is up, everything you already know about building the frontend applies unchanged.
|
|
|
|
## Related
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Frontend Overview" icon="browser" href="/edge/en/guides/frontend/overview">
|
|
Wire a Crew or Flow to a Next.js frontend end to end.
|
|
</Card>
|
|
<Card title="Generative UI" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
|
|
Render tool calls and agent state as custom components.
|
|
</Card>
|
|
<Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
|
|
Gate agent actions behind user approval.
|
|
</Card>
|
|
</CardGroup>
|