andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-08-10 08:21:54 +00:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Document UsageMetrics token field semantics for flows and crews.

Browse Source 
Clarify that total_tokens is prompt plus completion, breakdown fields are not additive, and Anthropic cache counters are folded into prompt_tokens.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
ViditOstwal
2026-08-06 20:21:18 +05:30
parent 63d4202432
commit a6161820d7
2 changed files with 20 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/edge/en/concepts/crews.mdx
View File

@@ -322,6 +322,8 @@ Caches can be employed to store the results of tools' execution, making the proc
After the crew execution, you can access the `usage_metrics` attribute to view the language model (LLM) usage metrics for all tasks executed by the crew. This provides insights into operational efficiency and areas for improvement.
`total_tokens` is the billed total (`prompt_tokens + completion_tokens`). Breakdown fields such as `cached_prompt_tokens` describe subsets already included in those totals — see [Flow Usage Metrics](/concepts/flows#flow-usage-metrics) for the full field semantics.
```python Code
# Access the crew's usage metrics
crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])

19
docs/edge/en/concepts/flows.mdx
View File

@@ -267,7 +267,24 @@ print(flow.usage_metrics)
execution.
</Note>
Each entry in the returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
### UsageMetrics field semantics
The returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) object uses a provider-neutral contract:
| Field | Meaning |
| --- | --- |
| `total_tokens` | Billed total: `prompt_tokens + completion_tokens` |
| `prompt_tokens` | Full input/prompt tokens billed for the request |
| `completion_tokens` | Output/completion tokens billed for the request |
| `cached_prompt_tokens` | Cache-read subset of prompt tokens (breakdown only) |
| `reasoning_tokens` | Reasoning/thinking subset where the provider reports it separately (breakdown only) |
| `successful_requests` | Number of LLM calls aggregated |
Breakdown fields such as `cached_prompt_tokens` and `reasoning_tokens` are **not** added on top of `total_tokens` — they describe portions already included in `prompt_tokens` or `completion_tokens`.
For Anthropic, cache read and cache write counters are folded into `prompt_tokens`, so cached workloads are fully reflected in `total_tokens`. OpenAI-style providers already include cached input inside `prompt_tokens`; CrewAI surfaces the cached portion separately for visibility.
Each entry in the returned `UsageMetrics` is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
## Flow State Management