Deprecate Usage in favour of RequestUsage and RunUsage

[samuelcolvin]

Closes #2352

• Deprecates pydantic_ai.usage.Usage. AgentRunResult.usage() now returns a RunUsage while ModelResponse.usage is a RequestUsage. The two classes are very similar, but prices should only be calculated using a RequestUsage. The classes also differ slightly from the old Usage:
  • Renamed request_tokens to input_tokens and response_tokens to output_tokens with deprecation warnings. Similar renames apply to the UsageLimits constructor.
  • None of the fields can be None, they all default to 0 except for details which defaults to {}.
• Changes to ModelResponse:
  • Renamed vendor_details to provider_details and vendor_id to provider_request_id in ModelResponse with deprecation warnings.
  • Originally in this PR but reverted for now:
    • Added ModelResponse.price() method to calculate the actual cost of a single request using https://github.com/pydantic/genai-prices.
    • Added ModelResponse.provider_name field

[hyperlint-ai]

PR Change Summary

Introduced a new Usage interface to enhance compatibility with the genai-prices library.

• Updated the Usage interface to replace 'request_tokens' and 'response_tokens' with 'input_tokens' and 'output_tokens'.
• Modified multiple documentation files to reflect the new Usage structure.
• Ensured consistency across examples and usage outputs in the documentation.

Modified Files

• docs/agents.md
• docs/direct.md
• docs/message-history.md
• docs/models/index.md
• docs/models/openai.md
• docs/multi-agent-applications.md
• docs/output.md
• docs/testing.md
• docs/tools.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[github-actions]

Docs Preview

commit:	8368c11
Preview URL:	https://41806b2d-pydantic-ai-previews.pydantic.workers.dev

[Copilot]

Pull Request Overview

This PR deprecates the old Usage class and introduces two new classes: RequestUsage and RunUsage. The main purpose is to work with the genai-prices library by providing more precise usage tracking. It also renames several token-related fields for consistency.

• Deprecates pydantic_ai.usage.Usage in favor of RequestUsage (for individual model requests) and RunUsage (for complete agent runs)
• Renames token fields from request_tokens/response_tokens to input_tokens/output_tokens with deprecation warnings
• Updates ModelResponse to use provider_details and provider_request_id instead of vendor_details and vendor_id

Reviewed Changes

Copilot reviewed 65 out of 66 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_usage_limits.py	Updates tests to use new RequestUsage and RunUsage classes, including tests for deprecated field warnings
tests/test_toolsets.py	Simple import update from Usage to RunUsage
tests/test_tools.py	Updates import and usage expectations from Usage to RequestUsage
tests/test_streaming.py	Updates imports and test assertions to use new usage classes
tests/test_mcp.py	Updates usage assertions and model response field names throughout MCP tests
tests/test_history_processor.py	Updates usage expectations in history processor tests
tests/test_direct.py	Updates direct model request tests to use RequestUsage
tests/test_agent.py	Comprehensive updates across agent tests for new usage classes and field names
tests/test_a2a.py	Simple usage class update in agent-to-agent tests
tests/models/test_openai_responses.py	Updates OpenAI model response tests with new usage classes and field names
tests/models/test_openai.py	Extensive updates to OpenAI model tests for new usage tracking
tests/models/test_model_test.py	Updates test model usage expectations
tests/models/test_model_function.py	Updates function model tests with new usage classes
tests/models/test_mistral.py	Updates Mistral model tests with new usage tracking and field names
tests/models/test_mcp_sampling.py	Removes usage assertions in MCP sampling tests
tests/models/test_instrumented.py	Updates instrumented model tests to use RequestUsage
tests/models/test_huggingface.py	Updates HuggingFace model tests with new usage classes
tests/models/test_groq.py	Updates Groq model tests with new usage tracking

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Kludex]

Why it doesn't inherit the protocol?

[alexmojaki]

Pyright complains with things like error: "input_tokens" incorrectly overrides property of same name in class "AbstractUsage"

[Kludex]

Shouldn't we use property here as well to match it?

[Kludex]

I understand we don't want to delay things, but it seems weird to not use the abstract class.

[alexmojaki]

even genai-prices is like this with the concrete Usage class.

these attributes are writable, so we'd need a getter and setter for each, and __init__ and __eq__. dataclasses are too helpful here.

[Kludex]

If not even the one in genai-prices use it, what's the point? Is it even type safe if you use AbstractUsage?

[alexmojaki]

functions like calc_price in genai-prices expect this protocol, and having the relevant attributes means the protocol is satisfied automatically, so e.g. RequestUsage is accepted by those functions.