Deprecate Usage in favour of RequestUsage and RunUsage (#2378)

Co-authored-by: Alex Hall <[email protected]>

Author: samuelcolvin

docs/agents.md

@@ -302,9 +302,7 @@ async def main():
         CallToolsNode(
             model_response=ModelResponse(
                 parts=[TextPart(content='The capital of France is Paris.')],
-                usage=Usage(
-                    requests=1, request_tokens=56, response_tokens=7, total_tokens=63
-                ),
+                usage=RequestUsage(input_tokens=56, output_tokens=7),
                 model_name='gpt-4o',
                 timestamp=datetime.datetime(...),
             )
@@ -367,12 +365,7 @@ async def main():
             CallToolsNode(
                 model_response=ModelResponse(
                     parts=[TextPart(content='The capital of France is Paris.')],
-                    usage=Usage(
-                        requests=1,
-                        request_tokens=56,
-                        response_tokens=7,
-                        total_tokens=63,
-                    ),
+                    usage=RequestUsage(input_tokens=56, output_tokens=7),
                     model_name='gpt-4o',
                     timestamp=datetime.datetime(...),
                 )
@@ -391,7 +384,7 @@ _(This example is complete, it can be run "as is" — you'll need to add `asynci
 
 #### Accessing usage and final output
 
-You can retrieve usage statistics (tokens, requests, etc.) at any time from the [`AgentRun`][pydantic_ai.agent.AgentRun] object via `agent_run.usage()`. This method returns a [`Usage`][pydantic_ai.usage.Usage] object containing the usage data.
+You can retrieve usage statistics (tokens, requests, etc.) at any time from the [`AgentRun`][pydantic_ai.agent.AgentRun] object via `agent_run.usage()`. This method returns a [`RunUsage`][pydantic_ai.usage.RunUsage] object containing the usage data.
 
 Once the run finishes, `agent_run.result` becomes a [`AgentRunResult`][pydantic_ai.agent.AgentRunResult] object containing the final output (and related metadata).
 
@@ -570,7 +563,7 @@ result_sync = agent.run_sync(
 print(result_sync.output)
 #> Rome
 print(result_sync.usage())
-#> Usage(requests=1, request_tokens=62, response_tokens=1, total_tokens=63)
+#> RunUsage(input_tokens=62, output_tokens=1, requests=1)
 
 try:
     result_sync = agent.run_sync(
@@ -579,7 +572,7 @@ try:
     )
 except UsageLimitExceeded as e:
     print(e)
-    #> Exceeded the response_tokens_limit of 10 (response_tokens=32)
+    #> Exceeded the output_tokens_limit of 10 (output_tokens=32)
 ```
 
 Restricting the number of requests can be useful in preventing infinite loops or excessive tool calling:
@@ -1018,9 +1011,7 @@ with capture_run_messages() as messages:  # (2)!
                         tool_call_id='pyd_ai_tool_call_id',
                     )
                 ],
-                usage=Usage(
-                    requests=1, request_tokens=62, response_tokens=4, total_tokens=66
-                ),
+                usage=RequestUsage(input_tokens=62, output_tokens=4),
                 model_name='gpt-4o',
                 timestamp=datetime.datetime(...),
             ),
@@ -1042,9 +1033,7 @@ with capture_run_messages() as messages:  # (2)!
                         tool_call_id='pyd_ai_tool_call_id',
                     )
                 ],
-                usage=Usage(
-                    requests=1, request_tokens=72, response_tokens=8, total_tokens=80
-                ),
+                usage=RequestUsage(input_tokens=72, output_tokens=8),
                 model_name='gpt-4o',
                 timestamp=datetime.datetime(...),
             ),

docs/direct.md

@@ -28,7 +28,7 @@ model_response = model_request_sync(
 print(model_response.parts[0].content)
 #> The capital of France is Paris.
 print(model_response.usage)
-#> Usage(requests=1, request_tokens=56, response_tokens=7, total_tokens=63)
+#> RequestUsage(input_tokens=56, output_tokens=7)
 ```
 
 _(This example is complete, it can be run "as is")_
@@ -83,7 +83,7 @@ async def main():
                 tool_call_id='pyd_ai_2e0e396768a14fe482df90a29a78dc7b',
             )
         ],
-        usage=Usage(requests=1, request_tokens=55, response_tokens=7, total_tokens=62),
+        usage=RequestUsage(input_tokens=55, output_tokens=7),
         model_name='gpt-4.1-nano',
         timestamp=datetime.datetime(...),
     )

docs/message-history.md

@@ -58,7 +58,7 @@ print(result.all_messages())
                 content='Did you hear about the toothpaste scandal? They called it Colgate.'
             )
         ],
-        usage=Usage(requests=1, request_tokens=60, response_tokens=12, total_tokens=72),
+        usage=RequestUsage(input_tokens=60, output_tokens=12),
         model_name='gpt-4o',
         timestamp=datetime.datetime(...),
     ),
@@ -126,7 +126,7 @@ async def main():
                         content='Did you hear about the toothpaste scandal? They called it Colgate.'
                     )
                 ],
-                usage=Usage(request_tokens=50, response_tokens=12, total_tokens=62),
+                usage=RequestUsage(input_tokens=50, output_tokens=12),
                 model_name='gpt-4o',
                 timestamp=datetime.datetime(...),
             ),
@@ -180,7 +180,7 @@ print(result2.all_messages())
                 content='Did you hear about the toothpaste scandal? They called it Colgate.'
             )
         ],
-        usage=Usage(requests=1, request_tokens=60, response_tokens=12, total_tokens=72),
+        usage=RequestUsage(input_tokens=60, output_tokens=12),
         model_name='gpt-4o',
         timestamp=datetime.datetime(...),
     ),
@@ -198,7 +198,7 @@ print(result2.all_messages())
                 content='This is an excellent joke invented by Samuel Colvin, it needs no explanation.'
             )
         ],
-        usage=Usage(requests=1, request_tokens=61, response_tokens=26, total_tokens=87),
+        usage=RequestUsage(input_tokens=61, output_tokens=26),
         model_name='gpt-4o',
         timestamp=datetime.datetime(...),
     ),
@@ -299,7 +299,7 @@ print(result2.all_messages())
                 content='Did you hear about the toothpaste scandal? They called it Colgate.'
             )
         ],
-        usage=Usage(requests=1, request_tokens=60, response_tokens=12, total_tokens=72),
+        usage=RequestUsage(input_tokens=60, output_tokens=12),
         model_name='gpt-4o',
         timestamp=datetime.datetime(...),
     ),
@@ -317,7 +317,7 @@ print(result2.all_messages())
                 content='This is an excellent joke invented by Samuel Colvin, it needs no explanation.'
             )
         ],
-        usage=Usage(requests=1, request_tokens=61, response_tokens=26, total_tokens=87),
+        usage=RequestUsage(input_tokens=61, output_tokens=26),
         model_name='gemini-1.5-pro',
         timestamp=datetime.datetime(...),
     ),

docs/models/index.md

@@ -117,7 +117,7 @@ print(response.all_messages())
         model_name='claude-3-5-sonnet-latest',
         timestamp=datetime.datetime(...),
         kind='response',
-        vendor_id=None,
+        provider_request_id=None,
     ),
 ]
 """

docs/models/openai.md

@@ -275,7 +275,7 @@ result = agent.run_sync('Where were the olympics held in 2012?')
 print(result.output)
 #> city='London' country='United Kingdom'
 print(result.usage())
-#> Usage(requests=1, request_tokens=57, response_tokens=8, total_tokens=65)
+#> RunUsage(input_tokens=57, output_tokens=8, requests=1)
 ```
 
 #### Example using a remote server
@@ -304,7 +304,7 @@ result = agent.run_sync('Where were the olympics held in 2012?')
 print(result.output)
 #> city='London' country='United Kingdom'
 print(result.usage())
-#> Usage(requests=1, request_tokens=57, response_tokens=8, total_tokens=65)
+#> RunUsage(input_tokens=57, output_tokens=8, requests=1)
 ```
 
 1. The name of the model running on the remote server

docs/multi-agent-applications.md

@@ -53,7 +53,7 @@ result = joke_selection_agent.run_sync(
 print(result.output)
 #> Did you hear about the toothpaste scandal? They called it Colgate.
 print(result.usage())
-#> Usage(requests=3, request_tokens=204, response_tokens=24, total_tokens=228)
+#> RunUsage(input_tokens=204, output_tokens=24, requests=3)
 ```
 
 1. The "parent" or controlling agent.
@@ -144,7 +144,7 @@ async def main():
         print(result.output)
         #> Did you hear about the toothpaste scandal? They called it Colgate.
         print(result.usage())  # (6)!
-        #> Usage(requests=4, request_tokens=309, response_tokens=32, total_tokens=341)
+        #> RunUsage(input_tokens=309, output_tokens=32, requests=4)
 ```
 
 1. Define a dataclass to hold the client and API key dependencies.
@@ -188,7 +188,7 @@ from rich.prompt import Prompt
 
 from pydantic_ai import Agent, RunContext
 from pydantic_ai.messages import ModelMessage
-from pydantic_ai.usage import Usage, UsageLimits
+from pydantic_ai.usage import RunUsage, UsageLimits
 
 
 class FlightDetails(BaseModel):
@@ -221,7 +221,7 @@ async def flight_search(
 usage_limits = UsageLimits(request_limit=15)  # (3)!
 
 
-async def find_flight(usage: Usage) -> Union[FlightDetails, None]:  # (4)!
+async def find_flight(usage: RunUsage) -> Union[FlightDetails, None]:  # (4)!
     message_history: Union[list[ModelMessage], None] = None
     for _ in range(3):
         prompt = Prompt.ask(
@@ -259,7 +259,7 @@ seat_preference_agent = Agent[None, Union[SeatPreference, Failed]](  # (5)!
 )
 
 
-async def find_seat(usage: Usage) -> SeatPreference:  # (6)!
+async def find_seat(usage: RunUsage) -> SeatPreference:  # (6)!
     message_history: Union[list[ModelMessage], None] = None
     while True:
         answer = Prompt.ask('What seat would you like?')
@@ -278,7 +278,7 @@ async def find_seat(usage: Usage) -> SeatPreference:  # (6)!
 
 
 async def main():  # (7)!
-    usage: Usage = Usage()
+    usage: RunUsage = RunUsage()
 
     opt_flight_details = await find_flight(usage)
     if opt_flight_details is not None:

docs/output.md

@@ -1,6 +1,6 @@
 "Output" refers to the final value returned from [running an agent](agents.md#running-agents). This can be either plain text, [structured data](#structured-output), or the result of a [function](#output-functions) called with arguments provided by the model.
 
-The output is wrapped in [`AgentRunResult`][pydantic_ai.agent.AgentRunResult] or [`StreamedRunResult`][pydantic_ai.result.StreamedRunResult] so that you can access other data, like [usage][pydantic_ai.usage.Usage] of the run and [message history](message-history.md#accessing-messages-from-results).
+The output is wrapped in [`AgentRunResult`][pydantic_ai.agent.AgentRunResult] or [`StreamedRunResult`][pydantic_ai.result.StreamedRunResult] so that you can access other data, like [usage][pydantic_ai.usage.RunUsage] of the run and [message history](message-history.md#accessing-messages-from-results).
 
 Both `AgentRunResult` and `StreamedRunResult` are generic in the data they wrap, so typing information about the data returned by the agent is preserved.
 
@@ -24,7 +24,7 @@ result = agent.run_sync('Where were the olympics held in 2012?')
 print(result.output)
 #> city='London' country='United Kingdom'
 print(result.usage())
-#> Usage(requests=1, request_tokens=57, response_tokens=8, total_tokens=65)
+#> RunUsage(input_tokens=57, output_tokens=8, requests=1)
 ```
 
 _(This example is complete, it can be run "as is")_

docs/testing.md

@@ -97,7 +97,7 @@ from pydantic_ai.messages import (
     UserPromptPart,
     ModelRequest,
 )
-from pydantic_ai.usage import Usage
+from pydantic_ai.usage import RequestUsage
 
 from fake_database import DatabaseConn
 from weather_app import run_weather_forecast, weather_agent
@@ -141,12 +141,9 @@ async def test_forecast():
                     tool_call_id=IsStr(),
                 )
             ],
-            usage=Usage(
-                requests=1,
-                request_tokens=71,
-                response_tokens=7,
-                total_tokens=78,
-                details=None,
+            usage=RequestUsage(
+                input_tokens=71,
+                output_tokens=7,
             ),
             model_name='test',
             timestamp=IsNow(tz=timezone.utc),
@@ -167,12 +164,9 @@ async def test_forecast():
                     content='{"weather_forecast":"Sunny with a chance of rain"}',
                 )
             ],
-            usage=Usage(
-                requests=1,
-                request_tokens=77,
-                response_tokens=16,
-                total_tokens=93,
-                details=None,
+            usage=RequestUsage(
+                input_tokens=77,
+                output_tokens=16,
             ),
             model_name='test',
             timestamp=IsNow(tz=timezone.utc),

docs/tools.md

@@ -95,7 +95,7 @@ print(dice_result.all_messages())
                 tool_name='roll_dice', args={}, tool_call_id='pyd_ai_tool_call_id'
             )
         ],
-        usage=Usage(requests=1, request_tokens=90, response_tokens=2, total_tokens=92),
+        usage=RequestUsage(input_tokens=90, output_tokens=2),
         model_name='gemini-1.5-flash',
         timestamp=datetime.datetime(...),
     ),
@@ -115,7 +115,7 @@ print(dice_result.all_messages())
                 tool_name='get_player_name', args={}, tool_call_id='pyd_ai_tool_call_id'
             )
         ],
-        usage=Usage(requests=1, request_tokens=91, response_tokens=4, total_tokens=95),
+        usage=RequestUsage(input_tokens=91, output_tokens=4),
         model_name='gemini-1.5-flash',
         timestamp=datetime.datetime(...),
     ),
@@ -135,9 +135,7 @@ print(dice_result.all_messages())
                 content="Congratulations Anne, you guessed correctly! You're a winner!"
             )
         ],
-        usage=Usage(
-            requests=1, request_tokens=92, response_tokens=12, total_tokens=104
-        ),
+        usage=RequestUsage(input_tokens=92, output_tokens=12),
         model_name='gemini-1.5-flash',
         timestamp=datetime.datetime(...),
     ),

examples/pydantic_ai_examples/flight_booking.py

@@ -13,7 +13,7 @@
 
 from pydantic_ai import Agent, ModelRetry, RunContext
 from pydantic_ai.messages import ModelMessage
-from pydantic_ai.usage import Usage, UsageLimits
+from pydantic_ai.usage import RunUsage, UsageLimits
 
 # 'if-token-present' means nothing will be sent (and the example will work) if you don't have logfire configured
 logfire.configure(send_to_logfire='if-token-present')
@@ -182,7 +182,7 @@ async def main():
         req_date=datetime.date(2025, 1, 10),
     )
     message_history: list[ModelMessage] | None = None
-    usage: Usage = Usage()
+    usage: RunUsage = RunUsage()
     # run the agent until a satisfactory flight is found
     while True:
         result = await search_agent.run(
@@ -213,7 +213,7 @@ async def main():
                 )
 
 
-async def find_seat(usage: Usage) -> SeatPreference:
+async def find_seat(usage: RunUsage) -> SeatPreference:
     message_history: list[ModelMessage] | None = None
     while True:
         answer = Prompt.ask('What seat would you like?')