fix: preserve metadata in A2A artifact updates

The A2A converter pipeline exhibited an architectural asymmetry regarding how event-level metadata is processed over the network. While the outbound converter (`from_adk_event.py`) correctly packs auxiliary metadata fields (`grounding_metadata`, `custom_metadata`, `usage_metadata`, and `error_code`) into the A2A artifact metadata layer, the inbound converter (`to_adk_event.py`) only reconstructed event actions natively, silently discarding the rest.

This change resolves the asymmetry by properly extracting these remaining metadata fields during `convert_a2a_artifact_update_to_event()`. A new resilient extractor (`_extract_genai_metadata`) is introduced to parse and strictly validate these structures (such as `GroundingMetadata` and `GenerateContentResponseUsageMetadata`) natively into their corresponding `google.genai` Pydantic models. We ensure backward compatibility and protect against malformed payloads by relying on graceful fallback defaults (`None`) when encountering incompatible raw payloads.

This ensures complete topological parity for A2A metadata serialization without impacting downstream ADK components unequipped to handle new fields.

PiperOrigin-RevId: 952055514

Author: google-genai-bot

src/google/adk/a2a/converters/to_adk_event.py

@@ -191,6 +191,11 @@ def _create_event(
     long_running_function_ids: Optional[set[str]] = None,
     partial: bool = False,
     content_role: str = "model",
+    grounding_metadata: Any = None,
+    custom_metadata: Any = None,
+    usage_metadata: Any = None,
+    error_code: Any = None,
+    citation_metadata: Any = None,
 ) -> Optional[Event]:
   """Creates an ADK event from parts and metadata."""
   event_actions = actions or EventActions()
@@ -220,6 +225,11 @@ def _create_event(
           else None
       ),
       partial=partial,
+      grounding_metadata=grounding_metadata,
+      custom_metadata=custom_metadata,
+      usage_metadata=usage_metadata,
+      error_code=error_code,
+      citation_metadata=citation_metadata,
   )
 
   return event
@@ -241,6 +251,28 @@ def _parse_adk_metadata_value(value: Any) -> Any:
     return value
 
 
+def _extract_genai_metadata(
+    metadata_dict: dict[str, Any], key: str, model_class: Any
+) -> Any:
+  raw = metadata_dict.get(_get_adk_metadata_key(key))
+  if raw is None:
+    return None
+  parsed = _parse_adk_metadata_value(raw)
+  if not isinstance(parsed, dict) and model_class:
+    return None
+  if not model_class:
+    return parsed
+  try:
+    return model_class.model_validate(parsed)
+  except ValidationError as error:
+    logger.warning(
+        "Ignoring invalid ADK %s metadata: %d validation errors",
+        key,
+        error.error_count(),
+    )
+    return None
+
+
 def _extract_event_actions(metadata: Any) -> EventActions:
   """Extracts ADK event actions from A2A metadata.
 
@@ -576,12 +608,28 @@ def convert_a2a_artifact_update_to_event(
     output_parts, _ = _convert_a2a_parts_to_adk_parts(
         a2a_artifact_update.artifact.parts, part_converter
     )
+    metadata_dict = _compat.meta_to_dict(a2a_artifact_update.artifact.metadata)
     return _create_event(
         output_parts,
         invocation_context,
         author,
         _extract_event_actions(a2a_artifact_update.artifact.metadata),
         partial=not a2a_artifact_update.last_chunk,
+        grounding_metadata=_extract_genai_metadata(
+            metadata_dict, "grounding_metadata", genai_types.GroundingMetadata
+        ),
+        custom_metadata=_extract_genai_metadata(
+            metadata_dict, "custom_metadata", None
+        ),
+        usage_metadata=_extract_genai_metadata(
+            metadata_dict,
+            "usage_metadata",
+            genai_types.GenerateContentResponseUsageMetadata,
+        ),
+        error_code=_extract_genai_metadata(metadata_dict, "error_code", None),
+        citation_metadata=_extract_genai_metadata(
+            metadata_dict, "citation_metadata", genai_types.CitationMetadata
+        ),
     )
   except Exception as e:
     logger.error("Failed to convert A2A artifact update to event: %s", e)

tests/unittests/a2a/converters/test_to_adk.py

@@ -22,10 +22,12 @@
 from a2a.types import Task
 from a2a.types import TaskArtifactUpdateEvent
 from google.adk.a2a import _compat
+from google.adk.a2a.converters.from_adk_event import convert_event_to_a2a_events
 from google.adk.a2a.converters.part_converter import A2A_DATA_PART_END_TAG
 from google.adk.a2a.converters.part_converter import A2A_DATA_PART_METADATA_IS_LONG_RUNNING_KEY
 from google.adk.a2a.converters.part_converter import A2A_DATA_PART_START_TAG
 from google.adk.a2a.converters.part_converter import A2A_DATA_PART_TEXT_MIME_TYPE
+from google.adk.a2a.converters.to_adk_event import _extract_genai_metadata
 from google.adk.a2a.converters.to_adk_event import convert_a2a_artifact_update_to_event
 from google.adk.a2a.converters.to_adk_event import convert_a2a_message_to_event
 from google.adk.a2a.converters.to_adk_event import convert_a2a_status_update_to_event
@@ -34,6 +36,7 @@
 from google.adk.a2a.converters.to_adk_event import MOCK_FUNCTION_CALL_FOR_REQUIRED_USER_INPUT
 from google.adk.a2a.converters.utils import _get_adk_metadata_key
 from google.adk.agents.invocation_context import InvocationContext
+from google.adk.events import Event
 from google.genai import types as genai_types
 import pytest
 
@@ -680,3 +683,74 @@ def test_convert_a2a_message_to_event_agent_role(self) -> None:
     )
 
     assert event.content.role == "model"
+
+
+class TestExtractGenaiMetadata:
+
+  def test_grounding_metadata_round_trip(self) -> None:
+    """Tests that grounding metadata can be successfully extracted."""
+    event = Event(
+        author="agent",
+        grounding_metadata=genai_types.GroundingMetadata(
+            search_entry_point=genai_types.SearchEntryPoint(
+                rendered_content="test"
+            )
+        ),
+        content=genai_types.Content(
+            role="model", parts=[genai_types.Part(text="hi")]
+        ),
+    )
+    a2a_events = convert_event_to_a2a_events(
+        event, {}, task_id="t", context_id="c"
+    )
+    artifact_update = next(
+        e for e in a2a_events if isinstance(e, TaskArtifactUpdateEvent)
+    )
+    back = convert_a2a_artifact_update_to_event(artifact_update, "agent")
+    assert back is not None
+    assert back.grounding_metadata is not None
+    assert back.grounding_metadata.search_entry_point.rendered_content == "test"
+
+  def test_extract_genai_metadata_valid(self) -> None:
+    metadata_dict = {
+        _get_adk_metadata_key(
+            "grounding_metadata"
+        ): '{"search_entry_point": {"rendered_content": "test"}}'
+    }
+    result = _extract_genai_metadata(
+        metadata_dict, "grounding_metadata", genai_types.GroundingMetadata
+    )
+    assert isinstance(result, genai_types.GroundingMetadata)
+    assert result.search_entry_point.rendered_content == "test"
+
+  def test_extract_genai_metadata_invalid_validation_error(self) -> None:
+    # A malformed dictionary that causes a ValidationError (e.g. wrong type for search_entry_point)
+    metadata_dict = {
+        _get_adk_metadata_key(
+            "grounding_metadata"
+        ): '{"search_entry_point": ["not_a_dict"]}'
+    }
+    result = _extract_genai_metadata(
+        metadata_dict, "grounding_metadata", genai_types.GroundingMetadata
+    )
+    assert result is None
+
+  def test_extract_genai_metadata_missing(self) -> None:
+    result = _extract_genai_metadata(
+        {"other_key": "val"},
+        "grounding_metadata",
+        genai_types.GroundingMetadata,
+    )
+    assert result is None
+
+  def test_extract_genai_metadata_not_dict_but_class_provided(self) -> None:
+    # Should safely return None when JSON parsed to non-dict, but model validates expected dict/kwargs
+    metadata_dict = {
+        _get_adk_metadata_key("usage_metadata"): '["not", "a", "dict"]'
+    }
+    result = _extract_genai_metadata(
+        metadata_dict,
+        "usage_metadata",
+        genai_types.GenerateContentResponseUsageMetadata,
+    )
+    assert result is None