fix(a2a): suppress part_metadata in Vertex AI mode

convert_a2a_part_to_genai_part unconditionally mapped A2A metadata onto
genai_types.Part.part_metadata. The google-genai SDK only accepts that field in
Gemini Developer API mode and raises a client-side ValueError in Vertex AI /
Enterprise mode, breaking A2A sub-agent tool calls and multi-turn loops.

Resolve the variant via get_google_llm_variant() and drop part_metadata for all
part branches when the backend is VERTEX_AI. Native fields (thought,
thought_signature) are unaffected.

PiperOrigin-RevId: 933687953

Author: google-genai-bot

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

@@ -28,6 +28,8 @@
 from a2a import types as a2a_types
 from google.genai import types as genai_types
 
+from ...utils.variant_utils import get_google_llm_variant
+from ...utils.variant_utils import GoogleLLMVariant
 from ..experimental import a2a_experimental
 from .utils import _get_adk_metadata_key
 
@@ -58,13 +60,23 @@ def convert_a2a_part_to_genai_part(
     a2a_part: a2a_types.Part,
 ) -> Optional[genai_types.Part]:
   """Convert an A2A Part to a Google GenAI Part."""
+
+  # part_metadata is only accepted by the Gemini Developer API. In Vertex AI /
+  # Enterprise mode it must be omitted to avoid a client-side ValueError.
+  def _part_metadata(metadata):
+    if get_google_llm_variant() == GoogleLLMVariant.VERTEX_AI:
+      return None
+    return metadata
+
   part = a2a_part.root
   if isinstance(part, a2a_types.TextPart):
     thought = None
     if part.metadata:
       thought = part.metadata.get(_get_adk_metadata_key('thought'))
     return genai_types.Part(
-        text=part.text, thought=thought, part_metadata=part.metadata
+        text=part.text,
+        thought=thought,
+        part_metadata=_part_metadata(part.metadata),
     )
 
   if isinstance(part, a2a_types.FilePart):
@@ -75,7 +87,7 @@ def convert_a2a_part_to_genai_part(
               mime_type=part.file.mime_type,
               display_name=part.file.name,
           ),
-          part_metadata=part.metadata,
+          part_metadata=_part_metadata(part.metadata),
       )
 
     elif isinstance(part.file, a2a_types.FileWithBytes):
@@ -85,7 +97,7 @@ def convert_a2a_part_to_genai_part(
               mime_type=part.file.mime_type,
               display_name=part.file.name,
           ),
-          part_metadata=part.metadata,
+          part_metadata=_part_metadata(part.metadata),
       )
     else:
       logger.warning(
@@ -129,7 +141,7 @@ def convert_a2a_part_to_genai_part(
                 part.data, by_alias=True
             ),
             thought_signature=thought_signature,
-            part_metadata=part.metadata,
+            part_metadata=_part_metadata(part.metadata),
         )
       if (
           part.metadata[_get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)]
@@ -139,7 +151,7 @@ def convert_a2a_part_to_genai_part(
             function_response=genai_types.FunctionResponse.model_validate(
                 part.data, by_alias=True
             ),
-            part_metadata=part.metadata,
+            part_metadata=_part_metadata(part.metadata),
         )
       if (
           part.metadata[_get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)]
@@ -149,7 +161,7 @@ def convert_a2a_part_to_genai_part(
             code_execution_result=genai_types.CodeExecutionResult.model_validate(
                 part.data, by_alias=True
             ),
-            part_metadata=part.metadata,
+            part_metadata=_part_metadata(part.metadata),
         )
       if (
           part.metadata[_get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)]
@@ -159,7 +171,7 @@ def convert_a2a_part_to_genai_part(
             executable_code=genai_types.ExecutableCode.model_validate(
                 part.data, by_alias=True
             ),
-            part_metadata=part.metadata,
+            part_metadata=_part_metadata(part.metadata),
         )
     return genai_types.Part(
         inline_data=genai_types.Blob(
@@ -170,7 +182,7 @@ def convert_a2a_part_to_genai_part(
             + A2A_DATA_PART_END_TAG,
             mime_type=A2A_DATA_PART_TEXT_MIME_TYPE,
         ),
-        part_metadata=part.metadata,
+        part_metadata=_part_metadata(part.metadata),
     )
 
   logger.warning(

tests/unittests/a2a/converters/test_part_converter.py

@@ -29,6 +29,7 @@
 from google.adk.a2a.converters.part_converter import convert_a2a_part_to_genai_part
 from google.adk.a2a.converters.part_converter import convert_genai_part_to_a2a_part
 from google.adk.a2a.converters.utils import _get_adk_metadata_key
+from google.adk.utils.variant_utils import GoogleLLMVariant
 from google.genai import types as genai_types
 import pytest
 
@@ -264,6 +265,138 @@ class UnsupportedPartType:
     mock_logger.warning.assert_called_once()
 
 
+class TestConvertA2aPartToGenaiPartApiVariant:
+  """Tests for part_metadata suppression based on api_variant (Vertex AI)."""
+
+  def _text_part_with_metadata(self):
+    return a2a_types.Part(
+        root=a2a_types.TextPart(
+            text="hello",
+            metadata={
+                _get_adk_metadata_key("thought"): True,
+                "custom": "value",
+            },
+        )
+    )
+
+  def test_text_part_metadata_suppressed_in_vertex_mode(self):
+    """In Vertex AI mode, part_metadata must be None to avoid SDK ValueError."""
+    a2a_part = self._text_part_with_metadata()
+
+    with patch(
+        "google.adk.a2a.converters.part_converter.get_google_llm_variant",
+        return_value=GoogleLLMVariant.VERTEX_AI,
+    ):
+      result = convert_a2a_part_to_genai_part(a2a_part)
+
+    assert result is not None
+    assert result.part_metadata is None
+    # Native fields are still populated from the metadata.
+    assert result.text == "hello"
+    assert result.thought is True
+
+  def test_text_part_metadata_preserved_in_gemini_api_mode(self):
+    """In Gemini Developer API mode, part_metadata is preserved."""
+    a2a_part = self._text_part_with_metadata()
+
+    with patch(
+        "google.adk.a2a.converters.part_converter.get_google_llm_variant",
+        return_value=GoogleLLMVariant.GEMINI_API,
+    ):
+      result = convert_a2a_part_to_genai_part(a2a_part)
+
+    assert result is not None
+    assert result.part_metadata == {
+        _get_adk_metadata_key("thought"): True,
+        "custom": "value",
+    }
+
+  def test_function_call_metadata_suppressed_in_vertex_mode(self):
+    """Function call data parts also suppress part_metadata in Vertex mode."""
+    a2a_part = a2a_types.Part(
+        root=a2a_types.DataPart(
+            data={"name": "my_func", "args": {"x": 1}},
+            metadata={
+                _get_adk_metadata_key(
+                    A2A_DATA_PART_METADATA_TYPE_KEY
+                ): A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL,
+                "custom": "value",
+            },
+        )
+    )
+
+    with patch(
+        "google.adk.a2a.converters.part_converter.get_google_llm_variant",
+        return_value=GoogleLLMVariant.VERTEX_AI,
+    ):
+      result = convert_a2a_part_to_genai_part(a2a_part)
+
+    assert result is not None
+    assert result.function_call is not None
+    assert result.part_metadata is None
+
+  def test_function_response_metadata_suppressed_in_vertex_mode(self):
+    """Function response data parts suppress part_metadata in Vertex mode."""
+    a2a_part = a2a_types.Part(
+        root=a2a_types.DataPart(
+            data={"name": "my_func", "response": {"ok": True}},
+            metadata={
+                _get_adk_metadata_key(
+                    A2A_DATA_PART_METADATA_TYPE_KEY
+                ): A2A_DATA_PART_METADATA_TYPE_FUNCTION_RESPONSE,
+                "custom": "value",
+            },
+        )
+    )
+
+    with patch(
+        "google.adk.a2a.converters.part_converter.get_google_llm_variant",
+        return_value=GoogleLLMVariant.VERTEX_AI,
+    ):
+      result = convert_a2a_part_to_genai_part(a2a_part)
+
+    assert result is not None
+    assert result.function_response is not None
+    assert result.part_metadata is None
+
+  def test_file_with_uri_metadata_suppressed_in_vertex_mode(self):
+    """File parts suppress part_metadata in Vertex mode."""
+    a2a_part = a2a_types.Part(
+        root=a2a_types.FilePart(
+            file=a2a_types.FileWithUri(
+                uri="gs://bucket/file.txt",
+                mime_type="text/plain",
+                name="my_file.txt",
+            ),
+            metadata={"custom": "value"},
+        )
+    )
+
+    with patch(
+        "google.adk.a2a.converters.part_converter.get_google_llm_variant",
+        return_value=GoogleLLMVariant.VERTEX_AI,
+    ):
+      result = convert_a2a_part_to_genai_part(a2a_part)
+
+    assert result is not None
+    assert result.file_data is not None
+    assert result.part_metadata is None
+
+  def test_api_variant_resolved_from_env(self):
+    """The api variant is resolved via get_google_llm_variant."""
+    a2a_part = self._text_part_with_metadata()
+
+    with patch(
+        "google.adk.a2a.converters.part_converter.get_google_llm_variant",
+        return_value=GoogleLLMVariant.VERTEX_AI,
+    ) as mock_get_variant:
+      result = convert_a2a_part_to_genai_part(a2a_part)
+
+    mock_get_variant.assert_called_once()
+    assert result is not None
+    assert result.part_metadata is None
+
+
 class TestConvertGenaiPartToA2aPart:
   """Test cases for convert_genai_part_to_a2a_part function."""