Swagger documentation fails to load in google-adk v1.16 due to FastAPI version conflict

[natansalvadorligabo]

Describe the bug
When installing google-adk v1.16, the Swagger documentation page (accessed via adk web /docs) does not appear. Instead, the following error is displayed:

Failed to load API definition. Errors Hide Fetch error Internal Server Error /openapi.json

I resolved the issue by downgrading FastAPI to version 0.115.0.

To Reproduce

1. Install google-adk v1.16
2. Run adk web
3. Open the Swagger documentation page
4. Observe the error above

Expected behavior
The Swagger documentation page should load normally after running adk web.

Screenshots
http://127.0.0.1:8000/docs

Desktop:

• OS: Windows 11
• Python version (python -V): 3.13/3.14
• ADK version (pip show google-adk): 1.16

Model Information:

• Which model is being used: gemini-2.5-flash

Additional context
Downgrading FastAPI to 0.115.0 restored the documentation route.

[lifnaja]

@natansalvadorligabo I downgraded FastAPI to version 0.118.3 because the newer version introduces support for both Pydantic v1 and v2, which can sometimes cause issues when generating API documentation.

https://github.com/fastapi/fastapi/releases/tag/0.119.0

[natansalvadorligabo]

@lifnaja Thanks for recommending the latest, most compatible version of FastAPI. I tested it and it also fixed the issue with the Swagger documentation.

[leebaro]

I have a same problem.

python : 3.13
adk : 1.16.0 and 1.17.0

I downgraded FAST API version to 0.118.3, but the problem persists.

  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 1109, in default_schema
    json_schema = self.generate_inner(schema['schema'])
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 563, in generate_inner
    json_schema = current_handler(schema)
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/_internal/_schema_generation_shared.py", line 37, in __call__
    return self.handler(core_schema)
           ~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 495, in handler_func
    json_schema = generate_for_schema_type(schema_or_field)
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 1179, in nullable_schema
    inner_json_schema = self.generate_inner(schema['schema'])
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 563, in generate_inner
    json_schema = current_handler(schema)
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/_internal/_schema_generation_shared.py", line 37, in __call__
    return self.handler(core_schema)
           ~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 495, in handler_func
    json_schema = generate_for_schema_type(schema_or_field)
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 855, in is_instance_schema
    return self.handle_invalid_for_json_schema(schema, f'core_schema.IsInstanceSchema ({schema["cls"]})')
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/frodo/Documents/project/app/agents/data_science/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 2318, in handle_invalid_for_json_schema
    raise PydanticInvalidForJsonSchema(f'Cannot generate a JsonSchema for {error_info}')
pydantic.errors.PydanticInvalidForJsonSchema: Cannot generate a JsonSchema for core_schema.IsInstanceSchema (<class 'httpx.Client'>)

For further information visit https://errors.pydantic.dev/2.11/u/invalid-for-json-schema

[ryanthomas8]

These set of dependencies are compatible for the Swagger documentation page

dependencies = [
    "google-cloud-aiplatform[adk,agent-engines]>=1.93.0",
    "fastapi==0.118.3",
    "pydantic==2.10.6",
    "python-dotenv>=1.0.1",
    "google-genai>=1.16.1",
    "google-adk>=1.0.0",
]

[AlfredoJF]

There's a dependency issues with pydantic==2.10.6 with mcp 1.19.0 requires pydantic<3.0.0,>=2.11.0

[erickleal-azos]

Same problem here. Even with fastapi 0.118.3 or 0.115.0 .
The error is always the same
pydantic.errors.PydanticSchemaGenerationError: Unable to generate pydantic-core schema for <class 'mcp.client.session.ClientSession'>. Set arbitrary_types_allowed=Truein the model_config to ignore this error or implementget_pydantic_core_schema on your type to fully support it.

I also tried @ryanthomas8 configuration, but i receive
google-cloud-aiplatform[adk,agent-engines] (1.93.0) depends on pydantic (>=2.11.1,<3)

[matthiasak]

no amount of tweaking the pydantic version or anything works for me either --

Here's what I found as a workaround for now:

tag:

"google-adk<1.16.0",                    # <1.16.0 for compat with /api/docs for now..
"fastapi<0.119",                         # for /api/docs compat

Then generate the openapi.json for later use, then upgrade adk to latest (yay!) and then I have a python server which handles all the redirects and loads our openapi.json as a statically generated schema

from google.adk.cli import fast_api
...
...
# server.py

app = fastapi.FastAPI(
    docs_url="/api/docs",  
    redoc_url="/api/redoc", 
    lifespan=lifespan,
)

py_static_files_dir = os.path.join(
    ".", "src", "nsha", "server", "static", "openapi.json"
)
with open(py_static_files_dir, "r") as openapi_file:
    api_spec = json.loads(openapi_file.read())
    app.openapi_schema = api_spec

# setup ADK
api = fast_api.get_fast_api_app(
    allow_origins=[
        "http://localhost",
        f"http://localhost:{VARS.PORT}",
        "*",
    ],
    agents_dir="./src/nsha/agents",
    session_service_uri=session_service_uri,
    session_db_kwargs=session_db_kwargs,
    web=False,
    trace_to_cloud=VARS.AF_TRACE_TO_CLOUD,
    reload_agents=reload,
    ....
)
app.mount("/api", api)

[Jacksunwei]

Root Cause

The issue occurs due to incompatibility between ADK's Pydantic models and newer FastAPI/Pydantic versions:

1. FastAPI 0.119.0+ and Pydantic 2.11+ are more aggressive when generating OpenAPI schemas, performing deep introspection of all Pydantic model fields
2. ADK has Pydantic models (specifically BaseAgent and its subclasses like RemoteA2aAgent, plus tools like McpTool) that contain non-JSON-serializable types:
   • httpx.AsyncClient in RemoteA2aAgent._httpx_client
   • mcp.client.session.ClientSession in MCPSessionManager._sessions
3. When FastAPI generates the OpenAPI schema at startup, it traverses through Session → Event → EventActions → agent_state, eventually encountering these problematic types and failing with PydanticInvalidForJsonSchema

The addition of the agent_state field to EventActions in v1.16 increased exposure of agent/tool instances to schema generation.

Recommended Solution

Short-term workaround: Pin compatible versions as documented by users:

fastapi==0.118.3
pydantic>=2.11.1,<3  # or pydantic==2.10.6 if mcp compatibility allows

Proper fix: Update ADK code to mark non-serializable fields as private using Pydantic v2 patterns:

1. Use __pydantic_private__ prefix for fields that shouldn't be serialized (requires Pydantic 2.x field declaration)
2. Or use Field(exclude=True) for these fields
3. Apply to RemoteA2aAgent._httpx_client, McpTool._mcp_session_manager, and similar fields

This prevents newer Pydantic/FastAPI from attempting to generate schemas for these internal implementation details.