/docs and /openapi.json endpoints fail with PydanticSchemaGenerationError in adk web #3956
Description
Please make sure you read the contribution guide and file the issues in the right place.
Contribution guide.
Describe the bug
When running adk web and accessing the Swagger docs at /docs or /openapi.json, the server returns a 500 Internal Server Error due to unserializable types in the API schema.
To Reproduce
- Create any agent
- Run adk web my_agent
- Access http://localhost:8000/docs or http://localhost:8000/openapi.json
Expected behavior
Swagger UI (Open API) loads and displays API documentation.
Actual Behavior
Server returns 500 Internal Server Error:
pydantic.errors.PydanticSchemaGenerationError: Unable to generate pydantic-core schema for <class 'mcp.client.session.ClientSession'>. Set arbitrary_types_allowed=True in the model_config to ignore this error or implement __get_pydantic_core_schema__ on your type to fully support it.
** Possible Root Cause**
The GenerateContentConfig model in google.genai.types contains a tools field with types that cannot be serialized to JSON Schema:
tools: Optional[list[ToolUnion]]
# where:
ToolUnion = Union[Tool, Callable[..., Any], mcp_types.Tool, McpClientSession]
mcp.client.session.ClientSession (aliased as McpClientSession) is a runtime-only type that Pydantic cannot generate a schema for.This affects the /run_eval endpoint which uses RunEvalRequest → EvalMetric → JudgeModelOptions → GenerateContentConfig.
Suggested Fix
Use SkipJsonSchema to exclude unserializable types from OpenAPI generation in google.genai.types:
from pydantic.json_schema import SkipJsonSchema
ToolUnion = Union[Tool, Callable[..., Any], mcp_types.Tool, SkipJsonSchema[McpClientSession]]
Or set json_schema_mode='validation' on affected models.
Workaround
Following work around worked for me
Monkey-patch Pydantic's schema generator before importing ADK:
from pydantic.json_schema import GenerateJsonSchema
from pydantic._internal._generate_schema import GenerateSchema
from pydantic_core import core_schema
# Patch 1: Handle invalid JSON schema types
def _patched_handle_invalid(self, schema, error_info):
return {'type': 'object', 'description': f'Unserializable type: {error_info}'}
GenerateJsonSchema.handle_invalid_for_json_schema = _patched_handle_invalid
# Patch 2: Handle unknown types during schema generation
def _patched_unknown_type_schema(self, obj):
return core_schema.any_schema()
GenerateSchema._unknown_type_schema = _patched_unknown_type_schema
# Then import and run ADK
from google.adk.cli.fast_api import get_fast_api_appScreenshots
If applicable, add screenshots to help explain your problem.
Desktop (please complete the following information):
- OS: Linux
- Python version(python -V): 3.12
- ADK version(pip show google-adk): 1.21.0
Model Information:
- Are you using LiteLLM: No
- Which model is being used: gemini-2.5-flash
Additional context
Add any other context about the problem here.