Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Fix Anthropic cache token usage underreporting (#6844)
Vidit Ostwal988f060c9335
diff --git a/docs/edge/ar/concepts/crews.mdx b/docs/edge/ar/concepts/crews.mdxindex 05f643c90..178129690 100644--- a/docs/edge/ar/concepts/crews.mdx+++ b/docs/edge/ar/concepts/crews.mdx@@ -172,6 +172,8 @@ class YourCrewName:بعد تنفيذ الطاقم، يمكنك الوصول إلى خاصية `usage_metrics` لعرض مقاييس استخدام نموذج اللغة (LLM) لجميع المهام المنفذة.+`total_tokens` هو الإجمالي المفوتر (`prompt_tokens + completion_tokens`). حقول التفصيل مثل `cached_prompt_tokens` و`cache_creation_tokens` تصف أجزاءً مُدرجة بالفعل ضمن تلك الإجماليات ولا تُضاف مرة أخرى إلى `total_tokens`. راجع قسم **UsageMetrics field semantics** في توثيق مفهوم Flows للحصول على العقد الكامل.+```python Codecrew = Crew(agents=[agent1, agent2], tasks=[task1, task2])crew.kickoff()diff --git a/docs/edge/ar/concepts/flows.mdx b/docs/edge/ar/concepts/flows.mdxindex 62d34b335..45d54114d 100644--- a/docs/edge/ar/concepts/flows.mdx+++ b/docs/edge/ar/concepts/flows.mdx@@ -266,6 +266,24 @@ print(flow.usage_metrics)كلما احتجت إلى الإجمالي **الكامل** للتوكنات لتنفيذ التدفق.</Note>+### دلالات حقول UsageMetrics++يستخدم كائن [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد عقدًا محايدًا للمزود:++| الحقل | المعنى |+| --- | --- |+| `total_tokens` | الإجمالي المفوتر: `prompt_tokens + completion_tokens` |+| `prompt_tokens` | إجمالي رموز الإدخال/المطالبة المفوترة للطلب |+| `completion_tokens` | رموز الإخراج/الإكمال المفوترة للطلب |+| `cached_prompt_tokens` | جزء قراءة الذاكرة المؤقتة من رموز المطالبة (تفصيل فقط) |+| `cache_creation_tokens` | جزء كتابة الذاكرة المؤقتة من رموز المطالبة (تفصيل فقط، Anthropic) |+| `reasoning_tokens` | جزء التفكير/الاستدلال حيث يبلّغ المزود عنه بشكل منفصل (تفصيل فقط) |+| `successful_requests` | عدد استدعاءات LLM المُجمّعة |++حقول التفصيل مثل `cached_prompt_tokens` و`cache_creation_tokens` و`reasoning_tokens` **لا تُضاف** فوق `total_tokens` — بل تصف أجزاءً مُدرجة بالفعل ضمن `prompt_tokens` أو `completion_tokens`.++بالنسبة إلى Anthropic، تُدمج عدادات قراءة وكتابة الذاكرة المؤقتة ضمن `prompt_tokens`، لذا تنعكس أعباء العمل المخزنة مؤقتًا بالكامل في `total_tokens`. يُدرج مزودو OpenAI الرموز المخزنة مؤقتًا بالفعل داخل `prompt_tokens`؛ يعرض CrewAI الجزء المخزن مؤقتًا بشكل منفصل للوضوح.+كل حقل في [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد هو مجموع جميع استدعاءات نموذج اللغة التي حدثت خلال استدعاء واحد لـ `flow.kickoff()`. تتم إعادة تعيين العدادات عند الاستدعاء التالي لـ `kickoff()` (وفي كل تكرار من `kickoff_for_each`)، لذلك لن تتكرر العدّات عبر التشغيلات المتتالية. يمكن قراءة هذه الخاصية بأمان في أي وقت بعد اكتمال `kickoff()`؛ قراءتها أثناء التنفيذ تُرجع المجموع الجزئي المتراكم حتى تلك اللحظة.## إدارة حالة التدفقdiff --git a/docs/edge/ar/concepts/llms.mdx b/docs/edge/ar/concepts/llms.mdxindex a0ec6a26d..a2b3d9653 100644--- a/docs/edge/ar/concepts/llms.mdx+++ b/docs/edge/ar/concepts/llms.mdx@@ -392,6 +392,22 @@ mode: "wide"- تتبع استخدام الرموز- محادثات استخدام أدوات متعددة الأدوار+ **استخدام الرموز والتخزين المؤقت للمطالبة:**++ يُبلّغ Anthropic عن الإدخال المفوتر في عدادات منفصلة — `input_tokens` (غير المخزن مؤقتًا)، و`cache_read_input_tokens`، و`cache_creation_input_tokens`. يدمج CrewAI الثلاثة ضمن `prompt_tokens` (و`input_tokens` الأصلي في استجابات المزود) بحيث يعكس `total_tokens` الاستخدام المفوتر الكامل على أعباء العمل المخزنة مؤقتًا.++ يسجّل `cached_prompt_tokens` جزء قراءة الذاكرة المؤقتة كتفصيل فقط؛ وهو مُدرج بالفعل ضمن `prompt_tokens` ولا يجب إضافته مرة أخرى إلى `total_tokens`. يسجّل `cache_creation_tokens` عمليات الكتابة في الذاكرة المؤقتة بنفس الطريقة.++ ```python Code+ usage = llm.get_token_usage_summary()+ # total_tokens == prompt_tokens + completion_tokens+ # prompt_tokens includes cache read + cache write for Anthropic+ ```++ راجع قسم **UsageMetrics field semantics** في توثيق مفهوم Flows+ للحصول على العقد المحايد للمزود المستخدم في `crew.usage_metrics`+ و`flow.usage_metrics`.+**ملاحظات مهمة:**- `max_tokens` معامل **مطلوب** لجميع نماذج Anthropic- يستخدم Claude `stop_sequences` بدلاً من `stop`diff --git a/docs/edge/en/concepts/crews.mdx b/docs/edge/en/concepts/crews.mdxindex 2c43b63c7..2e4f21032 100644--- a/docs/edge/en/concepts/crews.mdx+++ b/docs/edge/en/concepts/crews.mdx@@ -322,6 +322,8 @@ Caches can be employed to store the results of tools' execution, making the procAfter 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` and `cache_creation_tokens` describe subsets already included in those totals and are not added on top of `total_tokens`. See the **UsageMetrics field semantics** section in the Flows concept documentation for the full contract.+```python Code# Access the crew's usage metricscrew = Crew(agents=[agent1, agent2], tasks=[task1, task2])diff --git a/docs/edge/en/concepts/flows.mdx b/docs/edge/en/concepts/flows.mdxindex 647512545..f4f0a95ff 100644--- a/docs/edge/en/concepts/flows.mdx+++ b/docs/edge/en/concepts/flows.mdx@@ -267,7 +267,27 @@ 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) |+| `cache_creation_tokens` | Cache-write subset of prompt tokens (breakdown only, Anthropic) |+| `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`, `cache_creation_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 Managementdiff --git a/docs/edge/en/concepts/llms.mdx b/docs/edge/en/concepts/llms.mdxindex 3c4470644..02fb97314 100644--- a/docs/edge/en/concepts/llms.mdx+++ b/docs/edge/en/concepts/llms.mdx@@ -418,6 +418,27 @@ In this section, you'll find detailed examples that help you select, configure,- Token usage tracking- Multi-turn tool use conversations+ **Token usage and prompt caching:**++ Anthropic reports billed input in separate counters — `input_tokens` (uncached),+ `cache_read_input_tokens`, and `cache_creation_input_tokens`. CrewAI folds all+ three into `prompt_tokens` (and native `input_tokens` in provider responses) so+ `total_tokens` reflects full billed usage on cached workloads.++ `cached_prompt_tokens` records the cache-read portion as a breakdown only; it is+ already included in `prompt_tokens` and must not be added again to+ `total_tokens`. `cache_creation_tokens` records cache writes the same way.++ ```python Code+ usage = llm.get_token_usage_summary()+ # total_tokens == prompt_tokens + completion_tokens+ # prompt_tokens includes cache read + cache write for Anthropic+ ```++ See the **UsageMetrics field semantics** section in the Flows concept+ documentation for the provider-neutral contract used by `crew.usage_metrics`+ and `flow.usage_metrics`.+**Important Notes:**- `max_tokens` is a **required** parameter for all Anthropic models- Claude uses `stop_sequences` instead of `stop`diff --git a/docs/edge/ko/concepts/crews.mdx b/docs/edge/ko/concepts/crews.mdxindex e4cfadc1c..d62f76243 100644--- a/docs/edge/ko/concepts/crews.mdx+++ b/docs/edge/ko/concepts/crews.mdx@@ -324,6 +324,8 @@ crew는 메모리(단기, 장기 및 엔티티 메모리)를 활용하여 시간crew 실행 후, `usage_metrics` 속성에 접근하여 crew가 실행한 모든 작업에 대한 언어 모델(LLM) 사용 메트릭을 확인할 수 있습니다. 이를 통해 운영 효율성과 개선이 필요한 영역에 대한 인사이트를 얻을 수 있습니다.+`total_tokens`는 청구된 총합(`prompt_tokens + completion_tokens`)입니다. `cached_prompt_tokens` 및 `cache_creation_tokens`와 같은 breakdown 필드는 이미 해당 총합에 포함된 부분 집합을 설명하며 `total_tokens` 위에 다시 더하지 않습니다. 전체 계약은 Flows 개념 문서의 **UsageMetrics field semantics** 섹션을 참조하세요.+```python Code# Access the crew's usage metricscrew = Crew(agents=[agent1, agent2], tasks=[task1, task2])diff --git a/docs/edge/ko/concepts/flows.mdx b/docs/edge/ko/concepts/flows.mdxindex e168b7e3f..5c2e21d5a 100644--- a/docs/edge/ko/concepts/flows.mdx+++ b/docs/edge/ko/concepts/flows.mdx@@ -261,6 +261,24 @@ print(flow.usage_metrics)**전체** 토큰 집계가 필요할 때는 항상 `flow.usage_metrics`를 사용하십시오.</Note>+### UsageMetrics 필드 의미++반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) 객체는 제공자 중립 계약을 사용합니다:++| 필드 | 의미 |+| --- | --- |+| `total_tokens` | 청구된 총합: `prompt_tokens + completion_tokens` |+| `prompt_tokens` | 요청에 대해 청구된 전체 입력/프롬프트 토큰 |+| `completion_tokens` | 요청에 대해 청구된 출력/완료 토큰 |+| `cached_prompt_tokens` | 프롬프트 토큰 중 캐시 읽기 부분 집합 (breakdown 전용) |+| `cache_creation_tokens` | 프롬프트 토큰 중 캐시 쓰기 부분 집합 (breakdown 전용, Anthropic) |+| `reasoning_tokens` | 제공자가 별도로 보고하는 추론/사고 부분 집합 (breakdown 전용) |+| `successful_requests` | 집계된 LLM 호출 수 |++`cached_prompt_tokens`, `cache_creation_tokens`, `reasoning_tokens`와 같은 breakdown 필드는 `total_tokens` **위에 추가되지 않습니다** — 이미 `prompt_tokens` 또는 `completion_tokens`에 포함된 부분을 설명합니다.++Anthropic의 경우 캐시 읽기 및 쓰기 카운터가 `prompt_tokens`에 포함되므로, 캐시된 워크로드가 `total_tokens`에 완전히 반영됩니다. OpenAI 스타일 제공자는 캐시된 입력을 이미 `prompt_tokens`에 포함합니다. CrewAI는 가시성을 위해 캐시된 부분을 별도로 표시합니다.+반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py)의 각 항목은 단일 `flow.kickoff()` 실행 동안 발생한 모든 LLM 호출의 합계입니다. 다음 `kickoff()` 호출(및 `kickoff_for_each`의 각 반복)에서 카운터가 초기화되므로 연속 실행이 이중으로 집계되지 않습니다. 이 속성은 `kickoff()` 완료 후 언제든지 안전하게 읽을 수 있으며, 실행 중에 읽으면 그 시점까지 누적된 부분 합계를 반환합니다.## 플로우 상태 관리diff --git a/docs/edge/ko/concepts/llms.mdx b/docs/edge/ko/concepts/llms.mdxindex 0945c6d50..760377ac1 100644--- a/docs/edge/ko/concepts/llms.mdx+++ b/docs/edge/ko/concepts/llms.mdx@@ -270,6 +270,21 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양)```+ **토큰 사용량 및 프롬프트 캐싱:**++ Anthropic은 청구된 입력을 별도 카운터로 보고합니다 — `input_tokens`(캐시되지 않은 입력), `cache_read_input_tokens`, `cache_creation_input_tokens`. CrewAI는 세 값을 모두 `prompt_tokens`(및 제공자 응답의 네이티브 `input_tokens`)에 포함시켜 캐시된 워크로드에서 `total_tokens`가 전체 청구 사용량을 반영하도록 합니다.++ `cached_prompt_tokens`는 캐시 읽기 부분을 breakdown으로만 기록합니다. 이미 `prompt_tokens`에 포함되어 있으므로 `total_tokens`에 다시 더하면 안 됩니다. `cache_creation_tokens`도 캐시 쓰기를 같은 방식으로 기록합니다.++ ```python Code+ usage = llm.get_token_usage_summary()+ # total_tokens == prompt_tokens + completion_tokens+ # prompt_tokens includes cache read + cache write for Anthropic+ ```++ `crew.usage_metrics` 및 `flow.usage_metrics`에 사용되는 제공자 중립 계약은+ Flows 개념 문서의 **UsageMetrics field semantics** 섹션을 참조하세요.+현재 모델 ID와 기능은 Anthropic의 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 확인하고, 프로덕션에서 모델을 고정하기 전에 [모델 지원 중단 표](https://platform.claude.com/docs/en/about-claude/model-deprecations)를 검토하세요.</Accordion>diff --git a/docs/edge/pt-BR/concepts/crews.mdx b/docs/edge/pt-BR/concepts/crews.mdxindex bb8298cde..a8317e525 100644--- a/docs/edge/pt-BR/concepts/crews.mdx+++ b/docs/edge/pt-BR/concepts/crews.mdx@@ -322,6 +322,8 @@ Caches podem ser utilizados para armazenar resultados de execuções de ferramenApós a execução da crew, você pode acessar o atributo `usage_metrics` para visualizar as métricas de uso do modelo de linguagem (LLM) para todas as tasks executadas pela crew. Isso fornece insights sobre eficiência operacional e oportunidades de melhoria.+`total_tokens` é o total faturado (`prompt_tokens + completion_tokens`). Campos de breakdown como `cached_prompt_tokens` e `cache_creation_tokens` descrevem subconjuntos já incluídos nesses totais e não são somados novamente a `total_tokens`. Consulte a seção **UsageMetrics field semantics** na documentação do conceito Flows para o contrato completo.+```python Code# Acessar as métricas de uso da crewcrew = Crew(agents=[agent1, agent2], tasks=[task1, task2])diff --git a/docs/edge/pt-BR/concepts/flows.mdx b/docs/edge/pt-BR/concepts/flows.mdxindex 8879edca8..d70bb9774 100644--- a/docs/edge/pt-BR/concepts/flows.mdx+++ b/docs/edge/pt-BR/concepts/flows.mdx@@ -260,6 +260,24 @@ print(flow.usage_metrics)rollup **completo** de tokens da execução do Flow.</Note>+### Semântica dos campos UsageMetrics++O objeto [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado usa um contrato neutro em relação ao provedor:++| Campo | Significado |+| --- | --- |+| `total_tokens` | Total faturado: `prompt_tokens + completion_tokens` |+| `prompt_tokens` | Total de tokens de entrada/prompt faturados para a requisição |+| `completion_tokens` | Tokens de saída/conclusão faturados para a requisição |+| `cached_prompt_tokens` | Subconjunto de leitura de cache dos tokens de prompt (apenas breakdown) |+| `cache_creation_tokens` | Subconjunto de escrita de cache dos tokens de prompt (apenas breakdown, Anthropic) |+| `reasoning_tokens` | Subconjunto de raciocínio/pensamento quando o provedor reporta separadamente (apenas breakdown) |+| `successful_requests` | Número de chamadas LLM agregadas |++Campos de breakdown como `cached_prompt_tokens`, `cache_creation_tokens` e `reasoning_tokens` **não** são somados sobre `total_tokens` — eles descrevem porções já incluídas em `prompt_tokens` ou `completion_tokens`.++Para Anthropic, os contadores de leitura e escrita de cache são incorporados em `prompt_tokens`, de modo que workloads em cache são totalmente refletidos em `total_tokens`. Provedores no estilo OpenAI já incluem a entrada em cache dentro de `prompt_tokens`; o CrewAI expõe a porção em cache separadamente para visibilidade.+Cada campo do [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado representa a soma de todas as chamadas de LLM feitas em uma única invocação de `flow.kickoff()`. Os contadores são resetados a cada novo `kickoff()` (e em cada iteração de `kickoff_for_each`), de modo que execuções sucessivas não duplicam o total. A propriedade é segura para ser lida em qualquer momento após o `kickoff()`; lê-la durante a execução retorna o total parcial acumulado até aquele instante.## Gerenciamento de Estado em Flowsdiff --git a/docs/edge/pt-BR/concepts/llms.mdx b/docs/edge/pt-BR/concepts/llms.mdxindex efc12ed82..c4cf18ecf 100644--- a/docs/edge/pt-BR/concepts/llms.mdx+++ b/docs/edge/pt-BR/concepts/llms.mdx@@ -270,6 +270,22 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co)```+ **Uso de tokens e prompt caching:**++ A Anthropic reporta a entrada faturada em contadores separados — `input_tokens` (não em cache), `cache_read_input_tokens` e `cache_creation_input_tokens`. O CrewAI incorpora os três em `prompt_tokens` (e no `input_tokens` nativo nas respostas do provedor) para que `total_tokens` reflita o uso faturado completo em workloads em cache.++ `cached_prompt_tokens` registra a porção de leitura de cache apenas como breakdown; ela já está incluída em `prompt_tokens` e não deve ser somada novamente a `total_tokens`. `cache_creation_tokens` registra escritas de cache da mesma forma.++ ```python Code+ usage = llm.get_token_usage_summary()+ # total_tokens == prompt_tokens + completion_tokens+ # prompt_tokens includes cache read + cache write for Anthropic+ ```++ Consulte a seção **UsageMetrics field semantics** na documentação do+ conceito Flows para o contrato neutro em relação ao provedor usado por+ `crew.usage_metrics` e `flow.usage_metrics`.+Consulte a [visão geral dos modelos](https://platform.claude.com/docs/en/about-claude/models/overview) da Anthropic para obter IDs e capacidades atuais e revise a [tabela de descontinuação](https://platform.claude.com/docs/en/about-claude/model-deprecations) antes de fixar um modelo em produção.</Accordion>diff --git a/lib/crewai/src/crewai/llms/providers/anthropic/completion.py b/lib/crewai/src/crewai/llms/providers/anthropic/completion.pyindex 7deecbf60..cdeef692a 100644--- a/lib/crewai/src/crewai/llms/providers/anthropic/completion.py+++ b/lib/crewai/src/crewai/llms/providers/anthropic/completion.py@@ -12,6 +12,7 @@ from crewai.llms.base_llm import BaseLLM, JsonResponseFormat, llm_call_contextfrom crewai.llms.hooks.base import BaseInterceptorfrom crewai.llms.hooks.transport import AsyncHTTPTransport, HTTPTransportfrom crewai.llms.providers.utils.common import safe_tool_conversion+from crewai.types.usage_metrics import _coerce_intfrom crewai.utilities.agent_utils import is_context_length_exceededfrom crewai.utilities.exceptions.context_window_exceeding_exception import (LLMContextLengthExceededError,@@ -1965,12 +1966,15 @@ class AnthropicCompletion(BaseLLM):"""Extract token usage and response metadata from Anthropic response."""if hasattr(response, "usage") and response.usage:usage = response.usage- input_tokens = getattr(usage, "input_tokens", 0)- output_tokens = getattr(usage, "output_tokens", 0)- cache_read_tokens = getattr(usage, "cache_read_input_tokens", 0) or 0- cache_creation_tokens = (- getattr(usage, "cache_creation_input_tokens", 0) or 0+ input_tokens = _coerce_int(getattr(usage, "input_tokens", 0))+ output_tokens = _coerce_int(getattr(usage, "output_tokens", 0))+ cache_read_tokens = _coerce_int(+ getattr(usage, "cache_read_input_tokens", 0))+ cache_creation_tokens = _coerce_int(+ getattr(usage, "cache_creation_input_tokens", 0)+ )+ input_tokens = input_tokens + cache_read_tokens + cache_creation_tokensresult: dict[str, Any] = {"input_tokens": input_tokens,"output_tokens": output_tokens,diff --git a/lib/crewai/src/crewai/types/usage_metrics.py b/lib/crewai/src/crewai/types/usage_metrics.pyindex 891795d8a..7d58a47b3 100644--- a/lib/crewai/src/crewai/types/usage_metrics.py+++ b/lib/crewai/src/crewai/types/usage_metrics.py@@ -108,6 +108,37 @@ class UsageMetrics(BaseModel):),)+ @staticmethod+ def _has_unreconciled_anthropic_cache_keys(usage_data: dict[str, Any]) -> bool:+ """Detect raw Anthropic usage that still splits cache from ``input_tokens``.++ The native ``AnthropicCompletion`` provider folds cache read/creation+ counters into ``input_tokens`` before usage reaches this normalizer.+ LiteLLM and flow-level event aggregation can still deliver the raw+ Anthropic API shape, where ``input_tokens`` is only the uncached+ portion and cache counters arrive as separate keys. Without+ reconciling here, ``prompt_tokens`` and ``total_tokens`` undercount+ billed usage on cached Anthropic workloads.+ """+ return "input_tokens" in usage_data and (+ "cache_read_input_tokens" in usage_data+ or "cache_creation_input_tokens" in usage_data+ )++ @staticmethod+ def _resolve_billed_prompt_tokens(usage_data: dict[str, Any]) -> int:+ """Return the full billed prompt/input token count for a usage dict."""+ if UsageMetrics._has_unreconciled_anthropic_cache_keys(usage_data):+ return (+ _coerce_int(usage_data.get("input_tokens"))+ + _coerce_int(usage_data.get("cache_read_input_tokens"))+ + _coerce_int(usage_data.get("cache_creation_input_tokens"))+ )++ return _first_int(+ usage_data, "prompt_tokens", "prompt_token_count", "input_tokens"+ )+@classmethoddef from_provider_dict(cls, usage_data: dict[str, Any] | None) -> Self | None:"""Normalize a provider's raw usage dict into a ``UsageMetrics``.@@ -125,9 +156,7 @@ class UsageMetrics(BaseModel):if not usage_data:return None- prompt_tokens = _first_int(- usage_data, "prompt_tokens", "prompt_token_count", "input_tokens"- )+ prompt_tokens = cls._resolve_billed_prompt_tokens(usage_data)completion_tokens = _first_int(usage_data,"completion_tokens",@@ -145,12 +174,16 @@ class UsageMetrics(BaseModel):if isinstance(details, dict):cached_prompt_tokens = _coerce_int(details.get("cached_tokens"))+ cache_creation_tokens = _coerce_int(+ usage_data.get("cache_creation_tokens")+ ) or _coerce_int(usage_data.get("cache_creation_input_tokens"))+return cls(total_tokens=prompt_tokens + completion_tokens,prompt_tokens=prompt_tokens,completion_tokens=completion_tokens,cached_prompt_tokens=cached_prompt_tokens,reasoning_tokens=_coerce_int(usage_data.get("reasoning_tokens")),- cache_creation_tokens=_coerce_int(usage_data.get("cache_creation_tokens")),+ cache_creation_tokens=cache_creation_tokens,successful_requests=1,)diff --git a/lib/crewai/tests/events/test_llm_usage_event.py b/lib/crewai/tests/events/test_llm_usage_event.pyindex d0b29c863..0a8ffc69f 100644--- a/lib/crewai/tests/events/test_llm_usage_event.py+++ b/lib/crewai/tests/events/test_llm_usage_event.py@@ -297,3 +297,128 @@ class TestUsageMetricsNewFields:dumped = metrics.model_dump()assert dumped["reasoning_tokens"] == 10assert dumped["cache_creation_tokens"] == 5+++class TestFromProviderDictAnthropicCacheTokens:+ def test_cache_read_tokens_included_in_prompt_and_total(self):+ from crewai.types.usage_metrics import UsageMetrics++ metrics = UsageMetrics.from_provider_dict(+ {+ "input_tokens": 3,+ "output_tokens": 44,+ "cache_read_input_tokens": 2061,+ }+ )++ assert metrics is not None+ assert metrics.prompt_tokens == 2064+ assert metrics.completion_tokens == 44+ assert metrics.total_tokens == 2108+ assert metrics.cached_prompt_tokens == 2061++ def test_cache_creation_tokens_included_in_prompt_and_total(self):+ from crewai.types.usage_metrics import UsageMetrics++ metrics = UsageMetrics.from_provider_dict(+ {+ "input_tokens": 100,+ "output_tokens": 50,+ "cache_creation_input_tokens": 20,+ }+ )++ assert metrics is not None+ assert metrics.prompt_tokens == 120+ assert metrics.total_tokens == 170+ assert metrics.cache_creation_tokens == 20++ def test_cache_read_and_creation_tokens_both_included(self):+ from crewai.types.usage_metrics import UsageMetrics++ metrics = UsageMetrics.from_provider_dict(+ {+ "input_tokens": 100,+ "output_tokens": 50,+ "cache_read_input_tokens": 30,+ "cache_creation_input_tokens": 20,+ }+ )++ assert metrics is not None+ assert metrics.prompt_tokens == 150+ assert metrics.total_tokens == 200+ assert metrics.cached_prompt_tokens == 30+ assert metrics.cache_creation_tokens == 20++ def test_missing_cache_fields_preserve_non_cached_totals(self):+ from crewai.types.usage_metrics import UsageMetrics++ metrics = UsageMetrics.from_provider_dict(+ {"input_tokens": 100, "output_tokens": 50}+ )++ assert metrics is not None+ assert metrics.prompt_tokens == 100+ assert metrics.total_tokens == 150+ assert metrics.cached_prompt_tokens == 0+ assert metrics.cache_creation_tokens == 0++ def test_reconciled_native_dict_is_not_double_counted(self):+ from crewai.types.usage_metrics import UsageMetrics++ metrics = UsageMetrics.from_provider_dict(+ {+ "input_tokens": 150,+ "output_tokens": 50,+ "cached_prompt_tokens": 30,+ "cache_creation_tokens": 20,+ }+ )++ assert metrics is not None+ assert metrics.prompt_tokens == 150+ assert metrics.total_tokens == 200+ assert metrics.cache_creation_tokens == 20++ def test_openai_cached_prompt_tokens_are_not_added_twice(self):+ from crewai.types.usage_metrics import UsageMetrics++ metrics = UsageMetrics.from_provider_dict(+ {+ "prompt_tokens": 100,+ "completion_tokens": 50,+ "prompt_tokens_details": {"cached_tokens": 30},+ }+ )++ assert metrics is not None+ assert metrics.prompt_tokens == 100+ assert metrics.total_tokens == 150+ assert metrics.cached_prompt_tokens == 30++ def test_cumulative_usage_via_add_usage_metrics(self):+ from crewai.types.usage_metrics import UsageMetrics++ first = UsageMetrics.from_provider_dict(+ {+ "input_tokens": 100,+ "output_tokens": 50,+ "cache_read_input_tokens": 30,+ }+ )+ second = UsageMetrics.from_provider_dict(+ {+ "input_tokens": 40,+ "output_tokens": 20,+ }+ )++ assert first is not None and second is not None+ first.add_usage_metrics(second)++ assert first.prompt_tokens == 170+ assert first.completion_tokens == 70+ assert first.total_tokens == 240+ assert first.cached_prompt_tokens == 30+ assert first.successful_requests == 2diff --git a/lib/crewai/tests/llms/anthropic/test_anthropic.py b/lib/crewai/tests/llms/anthropic/test_anthropic.pyindex fd21d3b8a..375246bb4 100644--- a/lib/crewai/tests/llms/anthropic/test_anthropic.py+++ b/lib/crewai/tests/llms/anthropic/test_anthropic.py@@ -549,7 +549,12 @@ def test_anthropic_token_usage_tracking():with patch.object(llm._client.messages, 'create') as mock_create:mock_response = MagicMock()mock_response.content = [MagicMock(text="test response")]- mock_response.usage = MagicMock(input_tokens=50, output_tokens=25)+ mock_response.usage = MagicMock(+ input_tokens=50,+ output_tokens=25,+ cache_read_input_tokens=0,+ cache_creation_input_tokens=0,+ )mock_create.return_value = mock_responseresult = llm.call("Hello")@@ -1653,9 +1658,9 @@ def test_anthropic_cache_creation_tokens_extraction():mock_response.model = Noneusage = llm._extract_anthropic_token_usage(mock_response)- assert usage["input_tokens"] == 100+ assert usage["input_tokens"] == 150assert usage["output_tokens"] == 50- assert usage["total_tokens"] == 150+ assert usage["total_tokens"] == 200assert usage["cached_prompt_tokens"] == 30assert usage["cache_creation_tokens"] == 20