500 Unknown Error in AdkApp.async_create_session in Agent Engine when using AgentServerMode.EXPERIMENTAL

[xu3cylee]

When using AgentServerMode.EXPERIMENTAL (Live API) with an agent deployed via the AdkApp template on Vertex AI Agent Engine, calls to async_create_session fail with a consistent 500 UNKNOWN error

The root cause appears to be a serialization mismatch: the Agent Engine service expects JSON Input, but the template returns a Pydantic Session object which the server cannot process.

Environment details

• OS type and version: Linux (GCE, debian-12-bookworm-v20250311)
• Python version: 3.11.2
• pip version: 23.0.1
• google-cloud-aiplatform version: 1.141.0
• google-adk version: 1.27.1

Steps to reproduce

1. Modify and Run below code sample

Code example

import asyncio
PROJECT_ID = "PROJECT_ID"    
LOCATION = "us-central1"       
STAGING_BUCKET = "gs://test"   
USER_ID = "test"

import sys
import google.adk
import vertexai

print(f"Python version: {sys.version}")
print(f"google-adk version: {google.adk.__version__}")
print(f"vertexai version: {vertexai.__version__}")

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.adk.tools.retrieval.vertex_ai_rag_retrieval import VertexAiRagRetrieval
from google.genai import types

root_agent = Agent(
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    name="root_agent",
    instruction="test",
    tools=[],
)


from vertexai.agent_engines.templates.adk import AdkApp
adk_app = AdkApp(agent=root_agent)
adk_app.set_up()

from vertexai._genai.types import AgentEngineConfig
from vertexai._genai.types import AgentServerMode
config = AgentEngineConfig(
    display_name = "test-agent",
    description = "",
    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]",
    ],
    staging_bucket = STAGING_BUCKET,
    agent_server_mode = AgentServerMode.EXPERIMENTAL
)

import vertexai
vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
remote_agent = client.agent_engines.create(agent=adk_app, config=config)

async def main():
    resource_id = remote_agent.api_resource.name
    remote_session = await remote_agent.async_create_session(user_id=USER_ID)

if __name__ == "__main__":
    asyncio.run(main())

Stack trace

ServerError: 500 UNKNOWN. {'error': {'code': 500, 'message': 'Unknown Error.', 'status': 'UNKNOWN'}}

Workaround

A workaround was found by manually converting the Pydantic Session object into a JSON-serializable dictionary before returning it from the agent method:

class MyAdkApp(AdkApp):
    async def async_create_session(self, **kwargs):
        session = await super().async_create_session(**kwargs)
        # Manually serialize to a JSON dictionary
        return session.model_dump(mode="json")

Update vertexai/agent_engines/templates/adk.py to ensure that async_create_session return JSON-serializable dictionaries instead of raw ADK/Pydantic objects. This can be achieved by calling .model_dump(mode="json") or .dict() on the returned values.