* feat: aggregate LLM token usage at the flow level
Introduces `flow.usage_metrics`, a snapshot of every LLMCallCompletedEvent
emitted under the flow's `current_flow_id` for the duration of one kickoff
(or resume) call. Aggregation happens on the singleton event bus so it
covers crews, direct `LLM.call`s, and nested listener calls — solving the
mismatch where the SDK reported only the last crew's usage while the
Enterprise UI showed the correct full total.
Co-authored-by: Cursor <cursoragent@cursor.com>
* refactor: centralize provider key normalization in UsageMetrics
Add UsageMetrics.from_provider_dict to normalize raw LLM usage dicts
across providers (LiteLLM, native Anthropic, native Gemini, OpenAI
nested cached). BaseLLM._track_token_usage_internal and the flow-level
aggregator now share this single source of truth, so `flow.usage_metrics`
agrees with per-LLM totals on every provider — including the native
Anthropic path that emits `input_tokens`/`output_tokens` instead of
`prompt_tokens`/`completion_tokens`.
* fix: flush event bus before reading aggregated usage_metrics
`crewai_event_bus.emit` dispatches LLMCallCompletedEvent handlers on a
ThreadPoolExecutor (fire-and-forget), so a flow whose last LLM call
completes right before kickoff_async/resume_async returns can detach
the usage listener while that handler is still queued, leaving its
tokens off `flow.usage_metrics`. Match `Crew.kickoff()` and call
`crewai_event_bus.flush()` in both finally blocks so every handler
drains before the listener is detached.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
* docs: udpate docs to reflect new state of OpenTelemetry collector
* docs: add OTel collector and Datadog screenshots
These images are referenced by the capture_telemetry_logs guides but were
missing from the tree, which broke the link checker across all locales.
* docs: address PR review on OTel collector guide
- Clarify that OpenTelemetry Traces and Logs are separate integrations
sharing the same fields (resolves Traces/Logs wording inconsistency)
- List regional Datadog OTLP hosts (US1/US3/US5/EU1/AP1) so users outside
US5 can copy the right domain
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
* docs: add Databricks integration guide to enterprise integrations
Add documentation for connecting CrewAI agents to Databricks via the
Databricks managed MCP servers. Highlights Genie, Databricks SQL, Unity
Catalog Functions, and Vector Search, each configured as a separate MCP
connection, and covers OAuth/PAT setup. Includes ko, pt-BR, and ar
translations and registers the page in all docs.json navigation blocks.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix: use locale-specific slugs for Databricks nav entries
Add databricks integration entries to pt-BR, ko, and ar nav blocks
using locale-specific prefixes instead of only having en/ entries.
Co-authored-by: Luzk <2128595+Luzk@users.noreply.github.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Iris <iris@crewai.com>
Co-authored-by: Luzk <2128595+Luzk@users.noreply.github.com>
Co-authored-by: Greyson LaLonde <greyson.r.lalonde@gmail.com>
Co-authored-by: Lucas Gomide <lucaslg200@gmail.com>
* docs: add Snowflake integration guide to enterprise integrations
Add documentation for connecting CrewAI agents to Snowflake via the
Snowflake-managed MCP server. Highlights Cortex Analyst, Cortex Search,
and SQL execution, and covers OAuth/PAT setup. Registers the page in
all docs.json navigation blocks.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: add Snowflake integration page for ko, ar, pt-BR
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Iris Clawd <iris@crewai.com>
- Adds an <Info> "ACP (Beta) Docs Navigation" block at the top of every
Agent Control Plane page so readers can jump between Overview,
Monitoring, and Rules without scrolling to the bottom-of-page Related
cards.
* docs: document one-time admin package install step
The previous revision described a manual "install in Salesforce first,
then connect from AMP" flow that nobody actually follows, and linked to
a private repo customers can't access.
* docs: point Integrations link at crewai_plus/unified_tools
* docs: split Agent Control Plane into Overview/Monitoring/Rules and localize
Mirror the secrets-manager folder convention for ACP: one folder per
locale with overview, monitoring, and rules pages. Replaces the two
flat agent-control-plane.mdx / agent-control-plane-rules.mdx files
with a 3-page layout, adds full translations for pt-BR, ko, and ar,
and rewires docs.json to register the new paths under each locale's
Manage group across the same 4 versions where ACP already lived.
* docs: flag Agent Control Plane as Beta in overview pages
Add a Beta callout right after the lead screenshot on the ACP
overview page across en, pt-BR, ko, and ar, matching the convention
used by Secrets Manager.
## Overview
Prettier-inserted bare `{" "}` lines between sibling `<Step>` elements caused Mintlify's `<Steps>` to crash with "Cannot read properties of undefined (reading 'stepNumber')", leaving the page body blank.
### Affected pages (en/ar/ko/pt-BR):
- enterprise/guides/enable-crew-studio
- learn/llm-selection-guide
* 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
* Add Tavily Research and get Research
- Added tavily research with docs to crew AI
- Added tavily get research with docs to crew AI
* Update `tavily-python` installation instructions and adjust version constraints
- Changed installation command from `pip install` to `uv add` for `tavily-python` in multiple documentation files.
- Updated version constraint for `tavily-python` in `pyproject.toml` from `>=0.7.14` to `~=0.7.14`.
- Modified the `exclude-newer` date in `uv.lock` to `2026-04-23T07:00:00Z`.
* Add Tavily Research Tool documentation in multiple languages
- Introduced `TavilyResearchTool` documentation in English, Arabic, Korean, and Portuguese.
- Updated `docs.json` to include paths for the new documentation files.
- The `TavilyResearchTool` allows CrewAI agents to perform multi-step research tasks and generate cited reports using the Tavily Research API.
* Fix Tavily research CI failures
* added getResearchTool docs
- Added docs for getResearchTool
---------
Co-authored-by: lorenzejay <lorenzejaytech@gmail.com>
Co-authored-by: Evan Rimer <evan.rimer@tavily.com>
Co-authored-by: Lorenze Jay <63378463+lorenzejay@users.noreply.github.com>
## 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`
* fix(docs): restore missing code block in pt-BR first-flow guide
The pt-BR translation of the 'Build Your First Flow' guide had a
placeholder comment '# [CÓDIGO NÃO TRADUZIDO, MANTER COMO ESTÁ]'
instead of the actual Python code in Step 5. This restores the full
main.py code block from the English source, matching the original
since code should not be translated.
* Translate code comments to pt-BR in first-flow guide
Code comments in the tutorial should be in Portuguese for the pt-BR
audience, since they are part of the guide's educational content.
* 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(crewai-tools): add highlights to ExaSearchTool, rename from EXASearchTool
- Add a highlights init param so agents can get token-efficient excerpts instead of full pages
- Rename EXASearchTool to ExaSearchTool; keep EXASearchTool as a deprecated alias so existing imports keep working
- Update the docs and example to use highlights as the recommended option
- Add a small note that says Exa is the fastest and most accurate web search API
- Add tests for the new highlights param and the deprecation alias
* fix(crewai-tools): import order and module-level Exa for tests
- Reorder std-lib imports so ruff is happy with force-sort-within-sections.
- Import Exa at module level (with a fallback) so the existing test mocks resolve.
The lazy install prompt still works if exa_py is missing.
- Allow content and summary to be a dict, matching highlights.
- Trim test file to the cases this PR introduces (highlights param and the
EXASearchTool deprecation alias). Existing init-shape tests stay.
Co-Authored-By: ishan <ishan@exa.ai>
* chore(crewai-tools): drop self-explanatory comment on schema alias
Co-Authored-By: ishan <ishan@exa.ai>
* docs(crewai-tools): default highlights to True, drop summary from examples
Co-Authored-By: ishan <ishan@exa.ai>
* docs(crewai-tools): simplify highlights examples to highlights=True
Co-Authored-By: ishan <ishan@exa.ai>
* feat(crewai-tools): add x-exa-integration header for usage tracking
Co-Authored-By: ishan <ishan@exa.ai>
* docs(crewai-tools): add Exa MCP section and resources links
Co-Authored-By: ishan <ishan@exa.ai>
---------
Co-authored-by: ishan <ishan@exa.ai>
Co-authored-by: Greyson LaLonde <greyson.r.lalonde@gmail.com>
Co-authored-by: Lorenze Jay <63378463+lorenzejay@users.noreply.github.com>
