A2A + VertexAiSessionService: part_metadata in event content rejected by Agent Engine Sessions appendEvent (400 INVALID_ARGUMENT) — regression in 2.2.0

[rynecheow]

Environment

• google-adk 2.2.0
• google-genai 2.8.0
• Vertex backend (GOOGLE_GENAI_USE_VERTEXAI=TRUE), durable sessions via VertexAiSessionService (Agent Engine)
• Agent exposed as an A2A server; the A2A client sends message parts that carry metadata

Symptom

Every turn fails while handling the A2A request:

400 INVALID_ARGUMENT. Invalid JSON payload received.
Unknown name "part_metadata" at 'event.content.parts[0]': Cannot find field.

Root cause

• a2a/converters/part_converter.convert_a2a_part_to_genai_part copies the inbound A2A part's metadata into genai.types.Part.part_metadata.
• The resulting event is persisted via VertexAiSessionService.append_event, which serializes part_metadata (snake_case) into the Sessions request; the Agent Engine Sessions API schema has no such field → 400, and the turn aborts.
• This is consistent with genai's own contract that part_metadata is "not supported in Vertex AI" — _Part_to_vertex raises on it for generateContent — but the session-append path does not strip it.

Expected

part_metadata should not reach Vertex / Agent Engine. Either don't populate it from A2A metadata when running on Vertex, or strip it before appendEvent serialization (mirroring _Part_to_vertex).

Regression

Works on google-adk 2.1.0; breaks after upgrading to 2.2.0.

[adk-bot]

GitHub Issue #6014 Analysis: A2A + VertexAiSessionService: part_metadata in event content rejected by Agent Engine Sessions appendEvent (400 INVALID_ARGUMENT) — regression in 2.2.0

Executive Summary

1. What is broken? When using durable sessions via VertexAiSessionService, appending an event that originated from an A2A server request fails with 400 INVALID_ARGUMENT (Unknown name "part_metadata" at 'event.content.parts[0]'). This happens because A2A converter maps inbound metadata to part_metadata on genai Parts, which then gets serialized under config['content'] during the standard append_event call. The Agent Engine Sessions backend API schema does not support part_metadata and rejects the request.
2. Is there a linked PR that fixes this issue? None
3. Recommendation: Should Fix (High Priority). This is a severe regression introduced in 2.2.0 that completely blocks and aborts every turn of any A2A agent utilizing durable Vertex AI Agent Engine sessions (VertexAiSessionService). The fix is extremely low-complexity and carries zero side effects.

Detailed Analysis

1. Root Cause Analysis ("What is broken?")

1. A2A Converters Map Metadata to part_metadata:
   In part_converter.py, when constructing Gemini representation parts, inbound A2A part metadata is mapped into part_metadata:

   text=part.text, thought=thought, part_metadata=part.metadata

2. Serialization Errors inside VertexAiSessionService:
   During event persistence, VertexAiSessionService.append_event in vertex_ai_session_service.py handles event.content serialization into the standard content config payload field:

   config = {}
   if event.content:
     config['content'] = event.content.model_dump(
         exclude_none=True, mode='json'
     )

   This converts event.content into a nested dictionary structure. Since part_metadata is populated on the part objects by the A2A converters, it gets serialized under config['content']['parts'][...] as "part_metadata".
3. Endpoint Rejection:
   The api_client.agent_engines.sessions.events.append call sends this serialized payload directly to the Vertex AI Agent Engine Sessions backend API. Because the API's standard Content schema expects standard OpenAPI/Gemini Part object fields and doesn't support the client-only part_metadata field, the backend throws a 400 INVALID_ARGUMENT exception, terminating the turn.

2. Existing Pull Requests ("Is there a linked PR that fixes this issue?")

• Linked PR: None
• PR URL: N/A
• Analysis: No active pull request has been submitted to resolve this specific issue.

3. Recommendation

• Recommendation: Should Fix (High Priority)
• Rationale:
  • Impact on User Experience: Severe regression. Any developer writing an A2A agent deployed on Vertex AI with durable sessions is completely blocked from processing conversation turns, experiencing fatal runtime errors.
  • Proposed Fix Implementation:
    In vertex_ai_session_service.py, modify serialization of config['content'] to clean and strip part_metadata from each part dictionary. This allows raw_event (which safely and cleanly preserves the exact, unfettered Python event object metadata, including part_metadata for A2A roundtripping) to function perfectly while ensuring the strict schema-validated general content field is sanitized of unrecognized properties.

    if event.content:
      content_dict = event.content.model_dump(
          exclude_none=True, mode='json'
      )
      if 'parts' in content_dict:
        for part in content_dict['parts']:
          part.pop('part_metadata', None)
      config['content'] = content_dict

  • Complexity & Risk: Minimal (zero risk). Stripping client-only properties from standard API-delivered schema blocks is highly standard. All full event information remains preserved in raw_event for reconstruction on read operations.

---

Summary of Work

• Extracted and parsed issue number 6014.
• Fetched and analyzed issue metadata via the API, matching it against the local workspace layout.
• Performed precision codebase tracing using exact patterns, identifying the failing location in vertex_ai_session_service.py and part_converter.py.
• Formulated an efficient, robust recommendation adhering strictly to the adk-issue-analyze and adk-style guidelines under read-only constraints.

[surajksharma07]

@rynecheow Worth trying: patch append_event() in vertex_ai_session_service.py so that after event.content.model_dump(exclude_none=True, mode='json'), you loop over content_dict['parts'] and call part.pop('part_metadata', None) on each before doing config['content'] = content_dict.
That keeps raw_event untouched (so A2A roundtripping still works) while stripping the client-only field from the schema-validated payload the Sessions API actually validates.

If that clears the 400 on your Vertex setup, please do a full end-to-end test covering the A2A roundtrip path before raising a PR — want to make sure nothing slips on the reconstruction side!