feat: report cached token counts for Anthropic and OpenAI models

Populate usage_metadata.cached_content_token_count from provider usage
so cache reads stop being reported as misses (matches LiteLlm).

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 933261404

Author: GWeale

src/google/adk/labs/openai/_openai_llm.py

@@ -298,6 +298,13 @@ def _function_declaration_to_openai_tool(
   }
 
 
+def _extract_cached_token_count(usage: Any) -> int | None:
+  """Returns OpenAI prompt_tokens_details.cached_tokens, if present."""
+  details = getattr(usage, "prompt_tokens_details", None)
+  cached = getattr(details, "cached_tokens", None)
+  return cached if isinstance(cached, int) else None
+
+
 def _response_to_llm_response(response: ChatCompletion) -> LlmResponse:
   """Parses an OpenAI response into an LlmResponse."""
   choice = response.choices[0]
@@ -331,6 +338,9 @@ def _response_to_llm_response(response: ChatCompletion) -> LlmResponse:
           prompt_token_count=response.usage.prompt_tokens,
           candidates_token_count=response.usage.completion_tokens,
           total_token_count=response.usage.total_tokens,
+          cached_content_token_count=_extract_cached_token_count(
+              response.usage
+          ),
       ),
   )
 

src/google/adk/models/anthropic_llm.py

@@ -380,6 +380,12 @@ def content_block_to_part(
   )
 
 
+def _extract_cached_token_count(usage: Any) -> int | None:
+  """Returns Anthropic cache-read tokens, the analog of cached_content tokens."""
+  cached = getattr(usage, "cache_read_input_tokens", None)
+  return cached if isinstance(cached, int) else None
+
+
 def message_to_generate_content_response(
     message: anthropic_types.Message,
 ) -> LlmResponse:
@@ -402,6 +408,7 @@ def message_to_generate_content_response(
           total_token_count=(
               message.usage.input_tokens + message.usage.output_tokens
           ),
+          cached_content_token_count=_extract_cached_token_count(message.usage),
       ),
       # TODO: Deal with these later.
       # finish_reason=to_google_genai_finish_reason(message.stop_reason),
@@ -612,11 +619,13 @@ async def _generate_content_streaming(
     redacted_thinking_blocks: dict[int, str] = {}
     input_tokens = 0
     output_tokens = 0
+    cached_input_tokens: int | None = None
 
     async for event in raw_stream:
       if event.type == "message_start":
         input_tokens = event.message.usage.input_tokens
         output_tokens = event.message.usage.output_tokens
+        cached_input_tokens = _extract_cached_token_count(event.message.usage)
 
       elif event.type == "content_block_start":
         block = event.content_block
@@ -708,6 +717,7 @@ async def _generate_content_streaming(
             prompt_token_count=input_tokens,
             candidates_token_count=output_tokens,
             total_token_count=input_tokens + output_tokens,
+            cached_content_token_count=cached_input_tokens,
         ),
         partial=False,
     )

tests/unittests/labs/openai/test_openai_llm.py

@@ -349,3 +349,120 @@ async def mock_create(*args, **kwargs):
       assert content[0]["text"] == "Analyze this"
       assert content[1]["type"] == "image_url"
       assert content[1]["image_url"]["url"].startswith("data:image/png;base64,")
+
+
+def _completion_with_cached_tokens(cached_tokens):
+  """Builds a mock ChatCompletion whose usage carries prompt_tokens_details."""
+  mock_response = mock.MagicMock()
+  mock_choice = mock.MagicMock()
+  mock_message = mock.MagicMock()
+  mock_message.content = "Hello there!"
+  mock_message.tool_calls = None
+  mock_choice.message = mock_message
+  mock_response.choices = [mock_choice]
+  mock_response.usage.prompt_tokens = 100
+  mock_response.usage.completion_tokens = 5
+  mock_response.usage.total_tokens = 105
+  if cached_tokens is None:
+    mock_response.usage.prompt_tokens_details = None
+  else:
+    mock_response.usage.prompt_tokens_details.cached_tokens = cached_tokens
+  return mock_response
+
+
+@pytest.mark.asyncio
+async def test_generate_content_async_reports_cached_tokens():
+  """prompt_tokens_details.cached_tokens populates cached_content_token_count."""
+  with mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test_key"}):
+    openai_llm = OpenAILlm(model="gpt-4o")
+    llm_request = LlmRequest(
+        model="gpt-4o",
+        contents=[Content(role="user", parts=[Part.from_text(text="Hello")])],
+    )
+
+    mock_response = _completion_with_cached_tokens(64)
+
+    async def mock_create(*args, **kwargs):
+      return mock_response
+
+    with mock.patch(
+        "google.adk.labs.openai._openai_llm.AsyncOpenAI"
+    ) as mock_client_class:
+      mock_client = mock.MagicMock()
+      mock_client_class.return_value = mock_client
+      mock_client.chat.completions.create = mock_create
+
+      responses = [
+          resp
+          async for resp in openai_llm.generate_content_async(
+              llm_request, stream=False
+          )
+      ]
+
+      assert len(responses) == 1
+      assert responses[0].usage_metadata.cached_content_token_count == 64
+      assert responses[0].usage_metadata.prompt_token_count == 100
+
+
+@pytest.mark.asyncio
+async def test_generate_content_async_zero_cached_tokens():
+  """No cache hit (cached_tokens=0) reports 0, not a regression."""
+  with mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test_key"}):
+    openai_llm = OpenAILlm(model="gpt-4o")
+    llm_request = LlmRequest(
+        model="gpt-4o",
+        contents=[Content(role="user", parts=[Part.from_text(text="Hello")])],
+    )
+
+    mock_response = _completion_with_cached_tokens(0)
+
+    async def mock_create(*args, **kwargs):
+      return mock_response
+
+    with mock.patch(
+        "google.adk.labs.openai._openai_llm.AsyncOpenAI"
+    ) as mock_client_class:
+      mock_client = mock.MagicMock()
+      mock_client_class.return_value = mock_client
+      mock_client.chat.completions.create = mock_create
+
+      responses = [
+          resp
+          async for resp in openai_llm.generate_content_async(
+              llm_request, stream=False
+          )
+      ]
+
+      assert responses[0].usage_metadata.cached_content_token_count == 0
+
+
+@pytest.mark.asyncio
+async def test_generate_content_async_absent_prompt_tokens_details():
+  """Missing prompt_tokens_details maps to None (no cached count reported)."""
+  with mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test_key"}):
+    openai_llm = OpenAILlm(model="gpt-4o")
+    llm_request = LlmRequest(
+        model="gpt-4o",
+        contents=[Content(role="user", parts=[Part.from_text(text="Hello")])],
+    )
+
+    mock_response = _completion_with_cached_tokens(None)
+
+    async def mock_create(*args, **kwargs):
+      return mock_response
+
+    with mock.patch(
+        "google.adk.labs.openai._openai_llm.AsyncOpenAI"
+    ) as mock_client_class:
+      mock_client = mock.MagicMock()
+      mock_client_class.return_value = mock_client
+      mock_client.chat.completions.create = mock_create
+
+      responses = [
+          resp
+          async for resp in openai_llm.generate_content_async(
+              llm_request, stream=False
+          )
+      ]
+
+      assert responses[0].usage_metadata.cached_content_token_count is None

tests/unittests/models/test_anthropic_llm.py

@@ -1633,6 +1633,64 @@ def test_message_to_generate_content_response_with_thinking():
   assert text_part.thought is not True
 
 
+def test_message_to_generate_content_response_reports_cache_read_tokens():
+  """cache_read_input_tokens maps to usage_metadata.cached_content_token_count."""
+  from google.adk.models.anthropic_llm import message_to_generate_content_response
+
+  message = anthropic_types.Message(
+      id="msg_cache_read",
+      content=[
+          anthropic_types.TextBlock(text="hi", type="text", citations=None)
+      ],
+      model="claude-sonnet-4-20250514",
+      role="assistant",
+      stop_reason="end_turn",
+      stop_sequence=None,
+      type="message",
+      usage=anthropic_types.Usage(
+          input_tokens=100,
+          output_tokens=20,
+          cache_creation_input_tokens=0,
+          cache_read_input_tokens=75,
+          server_tool_use=None,
+          service_tier=None,
+      ),
+  )
+
+  response = message_to_generate_content_response(message)
+
+  assert response.usage_metadata.cached_content_token_count == 75
+
+
+def test_message_to_generate_content_response_no_cache_read_tokens():
+  """Absent cache_read_input_tokens yields cached_content_token_count=None."""
+  from google.adk.models.anthropic_llm import message_to_generate_content_response
+
+  message = anthropic_types.Message(
+      id="msg_no_cache",
+      content=[
+          anthropic_types.TextBlock(text="hi", type="text", citations=None)
+      ],
+      model="claude-sonnet-4-20250514",
+      role="assistant",
+      stop_reason="end_turn",
+      stop_sequence=None,
+      type="message",
+      usage=anthropic_types.Usage(
+          input_tokens=100,
+          output_tokens=20,
+          cache_creation_input_tokens=0,
+          cache_read_input_tokens=None,
+          server_tool_use=None,
+          service_tier=None,
+      ),
+  )
+
+  response = message_to_generate_content_response(message)
+
+  assert response.usage_metadata.cached_content_token_count is None
+
+
 def test_part_to_message_block_thinking_roundtrip():
   """Part with thought=True and signature creates ThinkingBlockParam."""
   part = Part(