fix(usage): Normalize None token detail objects on Usage initialization

Extends #2034 to handle providers that return None for entire
input_tokens_details and output_tokens_details objects (not just the
fields within them). This affects non-streaming responses.

Related to #1179 (which fixed the streaming case).

Some providers like llama-stack return null for these optional fields
in their JSON responses. The OpenAI SDK maps these to None in Python.
Previously, passing None to the Usage constructor would fail Pydantic
validation before __post_init__ could normalize them.

This PR uses Pydantic's BeforeValidator to normalize None values at
the field level, before Pydantic's type validation runs.

Signed-off-by: Adrian Cole <[email protected]>

Author: codefromthecrypt

src/agents/models/openai_chatcompletions.py

@@ -102,18 +102,8 @@ async def get_response(
                     input_tokens=response.usage.prompt_tokens,
                     output_tokens=response.usage.completion_tokens,
                     total_tokens=response.usage.total_tokens,
-                    input_tokens_details=InputTokensDetails(
-                        cached_tokens=getattr(
-                            response.usage.prompt_tokens_details, "cached_tokens", 0
-                        )
-                        or 0,
-                    ),
-                    output_tokens_details=OutputTokensDetails(
-                        reasoning_tokens=getattr(
-                            response.usage.completion_tokens_details, "reasoning_tokens", 0
-                        )
-                        or 0,
-                    ),
+                    input_tokens_details=response.usage.prompt_tokens_details,
+                    output_tokens_details=response.usage.completion_tokens_details,
                 )
                 if response.usage
                 else Usage()

src/agents/usage.py

@@ -1,9 +1,21 @@
 from dataclasses import field
+from typing import Annotated, Any
 
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
+from pydantic import BeforeValidator
 from pydantic.dataclasses import dataclass
 
 
+def _normalize_input_tokens_details(v: Any) -> InputTokensDetails:
+    """Normalize None to default InputTokensDetails for providers that omit this field."""
+    return v if v is not None else InputTokensDetails(cached_tokens=0)
+
+
+def _normalize_output_tokens_details(v: Any) -> OutputTokensDetails:
+    """Normalize None to default OutputTokensDetails for providers that omit this field."""
+    return v if v is not None else OutputTokensDetails(reasoning_tokens=0)
+
+
 @dataclass
 class RequestUsage:
     """Usage details for a single API request."""
@@ -32,16 +44,16 @@ class Usage:
     input_tokens: int = 0
     """Total input tokens sent, across all requests."""
 
-    input_tokens_details: InputTokensDetails = field(
-        default_factory=lambda: InputTokensDetails(cached_tokens=0)
-    )
+    input_tokens_details: Annotated[
+        InputTokensDetails, BeforeValidator(_normalize_input_tokens_details)
+    ] = field(default_factory=lambda: InputTokensDetails(cached_tokens=0))
     """Details about the input tokens, matching responses API usage details."""
     output_tokens: int = 0
     """Total output tokens received, across all requests."""
 
-    output_tokens_details: OutputTokensDetails = field(
-        default_factory=lambda: OutputTokensDetails(reasoning_tokens=0)
-    )
+    output_tokens_details: Annotated[
+        OutputTokensDetails, BeforeValidator(_normalize_output_tokens_details)
+    ] = field(default_factory=lambda: OutputTokensDetails(reasoning_tokens=0))
     """Details about the output tokens, matching responses API usage details."""
 
     total_tokens: int = 0

tests/test_usage.py

@@ -270,7 +270,24 @@ def test_anthropic_cost_calculation_scenario():
 
 
 def test_usage_normalizes_none_token_details():
-    # Some providers don't populate optional fields, resulting in None values
+    # Some providers don't populate optional token detail fields
+    # (cached_tokens, reasoning_tokens), and the OpenAI SDK's generated
+    # code can bypass Pydantic validation (e.g., via model_construct),
+    # allowing None values. We normalize these to 0 to prevent TypeErrors.
+
+    # Test entire objects being None (BeforeValidator)
+    usage = Usage(
+        requests=1,
+        input_tokens=100,
+        input_tokens_details=None,
+        output_tokens=50,
+        output_tokens_details=None,
+        total_tokens=150,
+    )
+    assert usage.input_tokens_details.cached_tokens == 0
+    assert usage.output_tokens_details.reasoning_tokens == 0
+
+    # Test fields within objects being None (__post_init__)
     input_details = InputTokensDetails(cached_tokens=0)
     input_details.__dict__["cached_tokens"] = None