fix: preserve cache_metadata and usage_metadata in VertexAiSessionService event round-trip

VertexAiSessionService was dropping cache_metadata and usage_metadata
fields during Event serialization/deserialization. This caused
ContextCacheRequestProcessor to never find previous cache metadata,
creating a new cache on every LLM call instead of reusing existing ones.

The fix adds cache_metadata and usage_metadata to the event_metadata
dict during append_event (write path) and restores them in
_from_api_event (read path), matching the behavior of other session
service implementations.

Fixes #4698

Author: weiguangli-io

src/google/adk/sessions/vertex_ai_session_service.py

@@ -33,6 +33,8 @@
 from . import _session_util
 from ..events.event import Event
 from ..events.event_actions import EventActions
+from ..events.event_actions import EventCompaction
+from ..models.cache_metadata import CacheMetadata
 from ..utils.vertex_ai_utils import get_express_mode_api_key
 from .base_session_service import BaseSessionService
 from .base_session_service import GetSessionConfig
@@ -287,6 +289,14 @@ async def append_event(self, session: Session, event: Event) -> Event:
             else None
         ),
     }
+    if event.usage_metadata:
+      metadata_dict['usage_metadata'] = event.usage_metadata.model_dump(
+          exclude_none=True, mode='json'
+      )
+    if event.cache_metadata:
+      metadata_dict['cache_metadata'] = event.cache_metadata.model_dump(
+          exclude_none=True, mode='json'
+      )
     if event.grounding_metadata:
       metadata_dict['grounding_metadata'] = event.grounding_metadata.model_dump(
           exclude_none=True, mode='json'
@@ -374,6 +384,14 @@ def _from_api_event(api_event_obj: vertexai.types.SessionEvent) -> Event:
         getattr(event_metadata, 'grounding_metadata', None),
         types.GroundingMetadata,
     )
+    usage_metadata = _session_util.decode_model(
+        getattr(event_metadata, 'usage_metadata', None),
+        types.GenerateContentResponseUsageMetadata,
+    )
+    cache_metadata = _session_util.decode_model(
+        getattr(event_metadata, 'cache_metadata', None),
+        CacheMetadata,
+    )
   else:
     long_running_tool_ids = None
     partial = None
@@ -382,6 +400,8 @@ def _from_api_event(api_event_obj: vertexai.types.SessionEvent) -> Event:
     branch = None
     custom_metadata = None
     grounding_metadata = None
+    usage_metadata = None
+    cache_metadata = None
 
   return Event(
       id=api_event_obj.name.split('/')[-1],
@@ -400,5 +420,7 @@ def _from_api_event(api_event_obj: vertexai.types.SessionEvent) -> Event:
       branch=branch,
       custom_metadata=custom_metadata,
       grounding_metadata=grounding_metadata,
+      usage_metadata=usage_metadata,
+      cache_metadata=cache_metadata,
       long_running_tool_ids=long_running_tool_ids,
   )

tests/unittests/sessions/test_vertex_ai_session_service.py

@@ -27,6 +27,8 @@
 from google.adk.auth.auth_tool import AuthConfig
 from google.adk.events.event import Event
 from google.adk.events.event_actions import EventActions
+from google.adk.events.event_actions import EventCompaction
+from google.adk.models.cache_metadata import CacheMetadata
 from google.adk.sessions.base_session_service import GetSessionConfig
 from google.adk.sessions.session import Session
 from google.adk.sessions.vertex_ai_session_service import VertexAiSessionService
@@ -248,6 +250,8 @@ def _convert_to_object(data):
           'artifact_delta',
           'custom_metadata',
           'requested_auth_configs',
+          'cache_metadata',
+          'usage_metadata',
       ]:
         kwargs[key] = value
       else:
@@ -826,3 +830,147 @@ async def test_append_event():
   assert len(retrieved_session.events) == 2
   event_to_append.id = retrieved_session.events[1].id
   assert retrieved_session.events[1] == event_to_append
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures('mock_get_api_client')
+async def test_append_event_with_compaction():
+  """Compaction data round-trips through append_event and get_session."""
+  session_service = mock_vertex_ai_session_service()
+  session = await session_service.get_session(
+      app_name='123', user_id='user', session_id='1'
+  )
+  assert session is not None
+
+  compaction = EventCompaction(
+      start_timestamp=1000.0,
+      end_timestamp=2000.0,
+      compacted_content=genai_types.Content(
+          parts=[genai_types.Part(text='compacted summary')]
+      ),
+  )
+  event_to_append = Event(
+      invocation_id='compaction_invocation',
+      author='model',
+      timestamp=1734005534.0,
+      actions=EventActions(compaction=compaction),
+  )
+
+  await session_service.append_event(session, event_to_append)
+
+  retrieved_session = await session_service.get_session(
+      app_name='123', user_id='user', session_id='1'
+  )
+  assert retrieved_session is not None
+
+  appended_event = retrieved_session.events[-1]
+  assert appended_event.actions.compaction is not None
+  assert appended_event.actions.compaction.start_timestamp == 1000.0
+  assert appended_event.actions.compaction.end_timestamp == 2000.0
+  assert appended_event.actions.compaction.compacted_content.parts[0].text == (
+      'compacted summary'
+  )
+  # custom_metadata should remain None when only compaction was stored
+  assert appended_event.custom_metadata is None
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures('mock_get_api_client')
+async def test_append_event_with_compaction_and_custom_metadata():
+  """Both compaction and user custom_metadata survive the round-trip."""
+  session_service = mock_vertex_ai_session_service()
+  session = await session_service.get_session(
+      app_name='123', user_id='user', session_id='1'
+  )
+  assert session is not None
+
+  compaction = EventCompaction(
+      start_timestamp=100.0,
+      end_timestamp=200.0,
+      compacted_content=genai_types.Content(
+          parts=[genai_types.Part(text='summary')]
+      ),
+  )
+  event_to_append = Event(
+      invocation_id='compaction_and_meta_invocation',
+      author='model',
+      timestamp=1734005535.0,
+      actions=EventActions(compaction=compaction),
+      custom_metadata={'user_key': 'user_value'},
+  )
+
+  await session_service.append_event(session, event_to_append)
+
+  retrieved_session = await session_service.get_session(
+      app_name='123', user_id='user', session_id='1'
+  )
+  assert retrieved_session is not None
+
+  appended_event = retrieved_session.events[-1]
+  # Compaction is restored
+  assert appended_event.actions.compaction is not None
+  assert appended_event.actions.compaction.start_timestamp == 100.0
+  assert appended_event.actions.compaction.end_timestamp == 200.0
+  # User custom_metadata is preserved without the internal _compaction key
+  assert appended_event.custom_metadata == {'user_key': 'user_value'}
+  assert '_compaction' not in (appended_event.custom_metadata or {})
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures('mock_get_api_client')
+async def test_append_event_with_cache_and_usage_metadata():
+  """cache_metadata and usage_metadata round-trip through append and get."""
+  session_service = mock_vertex_ai_session_service()
+  session = await session_service.get_session(
+      app_name='123', user_id='user', session_id='1'
+  )
+  assert session is not None
+
+  cache_meta = CacheMetadata(
+      cache_name='projects/123/locations/us-central1/cachedContents/456',
+      expire_time=9999999999.0,
+      fingerprint='abc123hash',
+      invocations_used=3,
+      contents_count=10,
+      created_at=1700000000.0,
+  )
+  usage_meta = genai_types.GenerateContentResponseUsageMetadata(
+      prompt_token_count=100,
+      candidates_token_count=50,
+      total_token_count=150,
+      cached_content_token_count=80,
+  )
+  event_to_append = Event(
+      invocation_id='cache_test_invocation',
+      author='model',
+      timestamp=1734005536.0,
+      content=genai_types.Content(
+          parts=[genai_types.Part(text='cached response')]
+      ),
+      cache_metadata=cache_meta,
+      usage_metadata=usage_meta,
+  )
+
+  await session_service.append_event(session, event_to_append)
+
+  retrieved_session = await session_service.get_session(
+      app_name='123', user_id='user', session_id='1'
+  )
+  assert retrieved_session is not None
+
+  appended_event = retrieved_session.events[-1]
+  # cache_metadata is preserved
+  assert appended_event.cache_metadata is not None
+  assert appended_event.cache_metadata.cache_name == (
+      'projects/123/locations/us-central1/cachedContents/456'
+  )
+  assert appended_event.cache_metadata.fingerprint == 'abc123hash'
+  assert appended_event.cache_metadata.invocations_used == 3
+  assert appended_event.cache_metadata.contents_count == 10
+  assert appended_event.cache_metadata.created_at == 1700000000.0
+  # usage_metadata is preserved
+  assert appended_event.usage_metadata is not None
+  assert appended_event.usage_metadata.prompt_token_count == 100
+  assert appended_event.usage_metadata.candidates_token_count == 50
+  assert appended_event.usage_metadata.total_token_count == 150
+  assert appended_event.usage_metadata.cached_content_token_count == 80