fix(anthropic): include cache tokens in totals

[Linxiushen]

Summary

• include Anthropic cache reads and cache writes in normalized input and total token counts
• preserve cache read and cache creation counters as separate usage dimensions
• cover both provider extraction and the final UsageMetrics summary

Closes #6788

Testing

• targeted Anthropic token usage tests: 3 passed
• Ruff check: passed
• Ruff format check: passed
• Mypy on the changed provider: passed

AI assistance

Developed with AI assistance and reviewed and tested by the contributor. External contributors cannot apply labels in this repository, so I have requested the required llm-generated label in a comment below.

[Linxiushen]

AI assistance disclosure: this contribution was developed with AI assistance and personally reviewed and tested. GitHub denied my attempt to add the required llm-generated label because external contributors do not have AddLabelsToLabelable permission. Maintainers, please apply the llm-generated label.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3dc25cde-0556-4693-9d8e-c7a93a616fb3

📥 Commits

Reviewing files that changed from the base of the PR and between 5f25218 and a9a70d0.

📒 Files selected for processing (1)

• docs/edge/en/concepts/crews.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/edge/en/concepts/crews.mdx

---

📝 Walkthrough

Walkthrough

The native Anthropic token extractor now includes cache-read and cache-creation tokens in input_tokens and total_tokens. Tests verify aggregate totals and separate cache metrics through llm.call. Documentation defines the updated calculation.

Changes

Anthropic token usage

Layer / File(s)	Summary
Aggregate cache tokens and validate usage totals lib/crewai/src/crewai/llms/providers/anthropic/completion.py, lib/crewai/tests/llms/anthropic/test_anthropic.py, docs/edge/en/concepts/crews.mdx	The extractor adds cache-read and cache-creation tokens to input and total token counts. Tests mock nullable cache fields and verify prompt, completion, total, cached-prompt, and cache-creation values. Documentation describes the updated totals.

Suggested reviewers: lorenzejay

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: including cache tokens in token totals for the Anthropic provider.
Description check	✅ Passed	The description is related to the changeset. It explains the fix for including cache tokens, testing performed, and references issue #6788.
Linked Issues check	✅ Passed	The PR satisfies the linked issue #6788. It includes cache-read and cache-creation tokens in input and total token counts, preserves them as separate metrics, and updates regression tests.
Out of Scope Changes check	✅ Passed	All changes align with the linked issue scope: updates to Anthropic token extraction, test updates, and documentation of token calculation behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

lib/crewai/tests/llms/anthropic/test_anthropic.py (1)

1667-1668: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Exercise the public Anthropic call path in this test.

The test invokes _extract_anthropic_token_usage and _track_token_usage_internal directly. It therefore bypasses the provider path that must extract and record cache-inclusive usage. Patch llm._client.messages.create, call llm.call("Hello"), and assert the resulting UsageMetrics.

As per coding guidelines, tests under **/tests/**/*.py must focus on behavior rather than implementation details.

Suggested test adjustment

-    llm._track_token_usage_internal(usage)
+    with patch.object(
+        llm._client.messages, "create", return_value=mock_response
+    ):
+        assert llm.call("Hello") == "test response"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/crewai/tests/llms/anthropic/test_anthropic.py` around lines 1667 - 1668,
Update the test around _track_token_usage_internal to exercise the public
Anthropic path instead of calling internal extraction or tracking helpers
directly: patch llm._client.messages.create with a suitable response, invoke
llm.call("Hello"), and assert the resulting UsageMetrics includes the expected
cache-inclusive usage.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@lib/crewai/tests/llms/anthropic/test_anthropic.py`:
- Around line 1667-1668: Update the test around _track_token_usage_internal to
exercise the public Anthropic path instead of calling internal extraction or
tracking helpers directly: patch llm._client.messages.create with a suitable
response, invoke llm.call("Hello"), and assert the resulting UsageMetrics
includes the expected cache-inclusive usage.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7d277841-dc2b-44ab-8e13-69f1ecd45f5e

📥 Commits

Reviewing files that changed from the base of the PR and between b10c4ff and b8c3385.

📒 Files selected for processing (2)

• lib/crewai/src/crewai/llms/providers/anthropic/completion.py
• lib/crewai/tests/llms/anthropic/test_anthropic.py

[Linxiushen]

Addressed the review suggestion in eaddeb5: the cache-token regression now mocks the Anthropic client, calls the public llm.call() path, and asserts the resulting UsageMetrics. Event emission is isolated so the test remains deterministic under the suite's --block-network setting. Focused result: 2 passed.

[Vidit-Ostwal]

Hey @Linxiushen, I think it would be better to add a doc sharing how exactly we are calculating the total tokens, Just a one liner would be fine at this moment.
Lmk if you wanna work on this, can assign to you.

[Linxiushen]

Added the requested one-line calculation note in 5f25218. It documents that Anthropic normalized input includes uncached, cache-read, and cache-creation input tokens, and clarifies that the two cache metrics are separate breakdowns rather than values to add to total_tokens again.

[Vidit-Ostwal]

I don't think so that it's just a case for anthropic, I think it general way we have decided for each provider, can you check and update ?

[Linxiushen]

Checked the shared normalization path and updated the note in a9a70d0. It now states the provider-independent rule: total_tokens = prompt_tokens + completion_tokens, while cache/reasoning fields are breakdowns already represented in those totals and must not be added again. Anthropic remains as an example of provider-specific normalization (uncached + cache-read + cache-creation input), rather than being presented as the general rule itself.