Augment UsageDetails with cached / reasoning token counts #7122
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Cached tokens are currently reported by Anthropic, Gemini, OpenAI, and AWS. Reasoning tokens are currently reported by OpenAI and Gemini.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds first-class support for cached and reasoning token counts to the UsageDetails API by promoting them from AdditionalCounts to dedicated properties. These token counts are commonly reported by major AI providers including Anthropic, Gemini, OpenAI, and AWS, making this promotion valuable for API consistency and cost tracking.
Key Changes
- Added
CachedInputTokenCountandReasoningTokenCountnullable long properties toUsageDetailsclass - Updated OpenAI client implementations to populate these properties directly from provider token usage details
- Migrated existing AdditionalCounts entries for cached/reasoning tokens to the new dedicated properties in OpenAI integrations
- Added comprehensive test coverage for the new properties including serialization, addition operations, and null handling
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/Libraries/Microsoft.Extensions.AI.Abstractions/UsageDetails.cs | Added CachedInputTokenCount and ReasoningTokenCount properties with XML documentation, updated Add() method to sum them, and added debugger display support |
| src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.json | Added API baseline entries marking both new properties as "Stable" |
| src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs | Updated FromOpenAIUsage() to populate new properties from InputTokenDetails.CachedTokenCount and OutputTokenDetails.ReasoningTokenCount, removed these entries from AdditionalCounts |
| src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIResponsesChatClient.cs | Updated ToUsageDetails() to map InputTokenDetails.CachedTokenCount and OutputTokenDetails.ReasoningTokenCount to new properties |
| test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/UsageDetailsTests.cs | New comprehensive test file covering constructor defaults, property roundtrips, Add() behavior with various combinations including nulls, and JSON serialization |
| test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Contents/UsageContentTests.cs | Updated serialization test to include CachedInputTokenCount and ReasoningTokenCount |
| test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/OpenAIChatClientTests.cs | Updated multiple test methods to assert new properties are correctly populated and removed corresponding AdditionalCounts assertions |
| test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/OpenAIResponseClientTests.cs | Updated ResponseWithUsageDetails_ParsesTokenCounts test to verify new properties and assert AdditionalCounts is null when only cached/reasoning tokens are present |
verdie-g
reviewed
Dec 10, 2025
verdie-g
reviewed
Dec 10, 2025
ericstj
approved these changes
Dec 12, 2025
stephentoub
added a commit
to ericstj/extensions
that referenced
this pull request
Dec 12, 2025
Cached tokens are currently reported by Anthropic, Gemini, OpenAI, and AWS. Reasoning tokens are currently reported by OpenAI and Gemini.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Cached tokens are currently reported by Anthropic, Gemini, OpenAI, and AWS. Reasoning tokens are currently reported by OpenAI and Gemini.
Closes #7101
Microsoft Reviewers: Open in CodeFlow