Centralize FlowTrigger and FlowMethodDecorator so start/listen/router and the boolean trigger helpers share one authoring contract. This preserves decorated method signatures for static checking while allowing route-label strings in nested FlowCondition data.
Export the shared typing helpers for static analyzers, use an explicit Protocol body, align condition validation with Sequence-backed condition data, and drop the stale call-arg ignore exposed by the signature-preserving decorators.
Update the flow guide to use or_(...) for multi-label listeners.
* feat: add conversational flows documentation and chat session support
- Introduced a new guide for building multi-turn chat applications using , detailing session management and message handling.
- Added class to facilitate chat interactions, including streaming support and event handling.
- Implemented for class-level defaults and improved input normalization for conversational turns.
- Enhanced event listeners to manage flow events and tracing more effectively, including support for nested crew executions.
- Added tests for conversational flow helpers and kickoff parameters to ensure functionality and reliability.
* linted
* feat: enhance flow event tracing and session management
- Updated TraceCollectionListener to handle nested flows without re-claiming parent session batches.
- Ensured that method execution events are always emitted for tracing, regardless of flow event suppression.
- Improved finalization logic for flow trace batches to respect session deferral flags.
- Added tests to verify that method execution events are emitted correctly when flow events are suppressed and that deferred session finalization is respected in nested flows.
* updated docs
* feat: introduce experimental conversational flow framework
- Added a new module for conversational flow, including classes for managing conversation state, messages, and events.
- Implemented and for structured intent handling and routing.
- Enhanced the class to support turn-oriented conversational applications with built-in routing and message handling.
- Updated to include new classes in the public API.
- Added tests to validate the functionality of the new conversational flow features.
* handled docs
* feat(flow): enhance conversational flow handling and tracing
- Introduced support for deferred multi-turn tracing to maintain continuous event sequences.
- Updated method to delegate to restored checkpoint flows, improving session management.
- Added tests to validate the new tracing behavior and ensure correct event handling in conversational flows.
* fix multimodal test
* better conversational
* adjusted prompt
* drop unused
* fix test
* refactor: rename to and update related documentation
This commit refactors the class to for clarity and consistency across the codebase. The documentation has been updated to reflect this change, ensuring that references to the new class are accurate. Additionally, the alias for legacy imports is maintained for backward compatibility. The changes enhance the overall structure and readability of the conversational flow implementation.
* fix test
* adding experimetnal indicators
* fix test and reloaded cassettes
* cleanup ConversationalFlow class
* addressing double finalization and fixed tests
* improve on emphemeral tracing and adddressing comments
* fix(docs/pt-BR): replace untranslated code block placeholders
Replace all `# (O código não é traduzido)` and `# código não traduzido`
placeholder comments in the PT-BR docs with the actual code from the
English source files.
Files fixed:
- docs/pt-BR/concepts/flows.mdx (~15 placeholders → real code)
- docs/pt-BR/guides/flows/mastering-flow-state.mdx (~17 placeholders → real code)
Code itself is kept in English per i18n conventions. Inline # comments
within code blocks have been translated to Portuguese.
* fix(docs/pt-BR): address CodeRabbit review comments
- flows.mdx: add missing load_dotenv() call after imports
- mastering-flow-state.mdx: fix PersistentCounterFlow second-run example
to pass inputs={"id": flow1.state.id} to kickoff(), matching the
documented resume pattern; update comment accordingly
## Summary
- Add a new docs page at `docs/en/guides/flows/inputs-id-deprecation.mdx` that explains the deprecation of `inputs.id` as a `@persist` hydration mechanism and walks users through migrating to `restoreFromStateId` (available in CrewAI **v1.14.5 and later**).
- Wire the page into `docs.json` next to `mastering-flow-state` in all 13 version blocks across all 4 languages (52 nav inserts).
- Add translations for `ar`, `ko`, `pt-BR`
* docs: add OSS upgrade & crew-to-flow migration guide
* docs: add upgrading-crewai guide and installation note
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs: consolidate upgrade & migration guide into single page
Merge the broader root-level upgrade-crewai.mdx into the canonical
en/guides/migration/upgrading-crewai.mdx so there is one comprehensive
upgrade & migration page covering: project venv vs global CLI, why
crewai install alone won't bump versions, breaking changes, and the
Crew-to-Flow migration. Removes the orphaned root-level file (which
was not referenced in docs.json nav).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs: add pt-BR, ar, ko translations of upgrade/migration guide
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs: reduce upgrade guide scope to package upgrade + breaking changes only
* docs: soften intro tone — releases ship features, not breaking changes
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix: resolve CodeRabbit review comments
- Add space between Arabic conjunction and `uv.lock` code span (ar)
- Add explicit {#memory-embedder-config} anchors to localized headings
so in-page links resolve correctly (ar, ko, pt-BR, en)
Co-authored-by: Lucas Gomide <lucaslg200@gmail.com>
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Lucas Gomide <lucaslg200@gmail.com>
Co-authored-by: Greyson LaLonde <greyson.r.lalonde@gmail.com>
## Summary
- Reverts `b0e2fda` ("fix(flow): add execution_id separate from state.id", COR-48): removes `Flow.execution_id` and points `current_flow_id` / `current_flow_request_id` back at `flow_id` (i.e. `state.id`). The separate per-run tracking id was no longer the right abstraction once `restore_from_state_id` reshapes how `state.id` is assigned;
- Adds an optional `restore_from_state_id` kwarg to `Flow.kickoff` / `Flow.kickoff_async` that hydrates state from a previously-persisted flow's latest snapshot
- Reassigns `state.id` to a fresh value (or `inputs["id"]` if pinned) so the new run's `@persist` writes don't extend the source's history
- Existing `inputs["id"]` resume, `@persist`, and `from_checkpoint` paths are unchanged
## Problem
`@persist` only supports *resume* today: `kickoff(inputs={"id": <uuid>})` hydrates state and continues writing under the same `flow_uuid`. There's no way to **fork** — hydrate from a snapshot but persist under a separate key, leaving the source's history intact. This PR adds that.
| | `state.id` after kickoff | `@persist` writes land under |
|---|---|---|
| `inputs["id"]` (resume) | supplied id | supplied id (extends history) |
| `restore_from_state_id` (fork) | fresh id, or `inputs["id"]` if pinned | new id (source preserved) |
## Behavior
| `inputs.id` | `restore_from_state_id` | Effect |
|---|---|---|
| — | — | Fresh kickoff |
| set | — | Existing resume |
| — | UUID | Fork — new `state.id`, hydrated from source |
| set | UUID | Fork into a pinned `state.id`, hydrated from source |
- Source not found → silent fallback (mirrors existing resume)
- Both `from_checkpoint` and `restore_from_state_id` set → `ValueError`
- `restore_from_state_id=None` → byte-identical to current main
## Design
Fork hydration runs before the existing `inputs` block in `kickoff_async`. On a hit, it calls the same `_restore_state` primitive used by resume, then overwrites `state.id` with a fresh UUID (or `inputs["id"]`). A `fork_succeeded` flag gates the existing `inputs["id"]` path so we don't double-load. `_completed_methods` / `_is_execution_resuming` are intentionally untouched — skip-completed-methods remains the territory of `apply_checkpoint` and `from_pending`.
## Test plan
- [ ] `pytest tests/test_flow_persistence.py` — 5 new tests (four-row matrix, not-found fallback, default no-op, conflict raise) + 6 existing as regression
- [ ] `pytest tests/test_flow.py` — broader flow suite
- [ ] Manual end-to-end against an HITL `@persist` flow
* feat(flow): add optional key param to @persist decorator
Allows users to specify which state attribute to use as the
persistence key instead of always defaulting to state.id.
Usage: @persist(key='conversation_id')
Falls back to state.id when key is not provided (no breaking change).
Raises ValueError if the specified key is missing or falsy on state.
* docs(flow): document @persist key parameter for custom persistence keys
* fix(flow): use explicit None check for persist key to avoid empty-string fallback
---------
Co-authored-by: iris-clawd <iris-clawd@anthropic.com>
Co-authored-by: iris-clawd <iris@crewai.com>
Co-authored-by: Lorenze Jay <63378463+lorenzejay@users.noreply.github.com>
* docs: add Build with AI page for coding agents and AI assistants
* docs: add Build with AI section to README
* docs: trim README Build with AI section to skills install only
* docs: add skills.sh reference link for npx install
* docs: add coding agent logos to Build with AI page
---------
Co-authored-by: Lorenze Jay <63378463+lorenzejay@users.noreply.github.com>
* docs(cli): document device-code login and config reset guidance; renumber sections
* docs(cli): fix duplicate numbering (renumber Login/API Keys/Configuration sections)
* docs: Fix webhook documentation to include meta dict in all webhook payloads
- Add note explaining that meta objects from kickoff requests are included in all webhook payloads
- Update webhook examples to show proper payload structure including meta field
- Fix webhook examples to match actual API implementation
- Apply changes to English, Korean, and Portuguese documentation
Resolves the documentation gap where meta dict passing to webhooks was not documented despite being implemented in the API.
* WIP: CrewAI docs theme, changelog, GEO, localization
* docs(cli): fix merge markers; ensure mode: "wide"; convert ASCII tables to Markdown (en/pt-BR/ko)
* docs: add group icons across locales; split Automation/Integrations; update tools overviews and links
* docs: add pt-br translations
Powered by a CrewAI Flow https://github.com/danielfsbarreto/docs_translator
* Update mcp/overview.mdx brazilian docs
Its en-US counterpart was updated after I did a pass,
so now it includes the new section about @CrewBase
