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

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

Install google-adk v1.16
Run adk web
Open the Swagger documentation page
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.

@natansalvadorligabo

@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

@lifnaja

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

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

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",
]

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

@ryanthomas8

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)

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)

Root Cause

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

FastAPI 0.119.0+ and Pydantic 2.11+ are more aggressive when generating OpenAPI schemas, performing deep introspection of all Pydantic model fields
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
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:

Use __pydantic_private__ prefix for fields that shouldn't be serialized (requires Pydantic 2.x field declaration)
Or use Field(exclude=True) for these fields
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.

I tried with:

dependencies = [
    "fastapi==0.118.3",
    "google-adk>=1.18.0",
    "pydantic>=2.11.1,<3",
]

which failed

Then tried this:

uv add "mcp==1.12.0" "pydantic==2.10.6" "fastapi==0.118.3"

didn't work either:

➜  agent_repository git:(main) ✗ uv add "mcp==1.12.0" "pydantic==2.10.6" "fastapi==0.118.3"
  × No solution found when resolving dependencies for split (markers: python_full_version >= '3.14'):
  ╰─▶ Because google-cloud-aiplatform[agent-engines]>=1.125.0 depends on pydantic>=2.11.1 and pydantic>=2.11.1, we can conclude that
      google-cloud-aiplatform[agent-engines]>=1.125.0,<=1.126.0 depends on pydantic>=2.11.1.
      And because google-cloud-aiplatform[agent-engines]==1.127.0 depends on pydantic>=2.11.1, we can conclude that all of:
          google-cloud-aiplatform[agent-engines]>=1.125.0,<=1.126.0
          google-cloud-aiplatform[agent-engines]>=1.127.0
      depend on pydantic>=2.11.1.
      And because google-cloud-aiplatform[agent-engines]>=1.126.1 depends on pydantic>=2.11.1 and only the following versions of
      google-cloud-aiplatform[agent-engines] are available:
          google-cloud-aiplatform[agent-engines]<=1.125.0
          google-cloud-aiplatform[agent-engines]==1.126.0
          google-cloud-aiplatform[agent-engines]==1.126.1
          google-cloud-aiplatform[agent-engines]==1.127.0
      we can conclude that google-cloud-aiplatform[agent-engines]>=1.125.0 depends on pydantic>=2.11.1.
      And because google-adk==1.18.0 depends on google-cloud-aiplatform[agent-engines]>=1.125.0 and only google-adk<=1.18.0 is
      available, we can conclude that google-adk>=1.18.0 depends on pydantic>=2.11.1.
      And because your project depends on google-adk>=1.18.0 and pydantic==2.10.6, we can conclude that your project's requirements
      are unsatisfiable.

      hint: While the active Python version is 3.13, the resolution failed for other Python versions supported by your project.
      Consider limiting your project's supported Python versions using `requires-python`.
  help: If you want to add the package regardless of the failed resolution, provide the `--frozen` flag to skip locking and syncing.
➜  agent_repository git:(main) ✗

Anyone able to get around?

@sedhha

@sedhha see https://docs.astral.sh/uv/reference/settings/#override-dependencies and use this to force pydantic==2.10.6 through your dependency graph

@allenli873

Hi @allenli873 thanks for the reply, I will look into this too!

@sedhha see https://docs.astral.sh/uv/reference/settings/#override-dependencies and use this to force pydantic==2.10.6 through your dependency graph

Thanks! It solved for me.

dependencies = [
  "google-adk>=1.18.0",
  "fastapi==0.118.3",
  "pydantic==2.10.6",
]

This isn't working.

      we can conclude that google-cloud-aiplatform[agent-engines]>=1.125.0 depends on
      pydantic>=2.11.1.
      And because google-adk==1.18.0 depends on google-cloud-aiplatform[agent-engines]>=1.125.0
      and only google-adk<=1.18.0 is available, we can conclude that google-adk>=1.18.0 depends
      on pydantic>=2.11.1.
      And because your project depends on google-adk>=1.18.0 and pydantic==2.10.6, we can
      conclude that your project's requirements are unsatisfiable.

You have to go all the way back to google-cloud-aiplatform[agent-engines]==1.89.0 to lower the pydantic requirement to <=2.11.0.

EDIT: I missed this part:

[tool.uv]
override-dependencies = ["pydantic==2.10.6"]

Hopefully trying to use VertexAI doesn't blow it up.

Fix issue with recent pydantic (WIP)

fix: Make OpenAPI /docs path work again

chore: Limits fastapi to <0.119, so that swagger api can still render

fix: Make OpenAPI /docs path work again

Navigation Menu

Repository navigation

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

Root Cause

Recommended Solution

13 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Activity

lifnaja commented on Oct 15, 2025

natansalvadorligabo commented on Oct 15, 2025

leebaro commented on Oct 23, 2025

ryanthomas8 commented on Oct 23, 2025

AlfredoJF commented on Oct 24, 2025

erickleal-azos commented on Oct 24, 2025

matthiasak commented on Oct 24, 2025

Jacksunwei commented on Oct 26, 2025

Root Cause

Recommended Solution

13 remaining items

sedhha commented on Nov 14, 2025

allenli873 commented on Nov 17, 2025

GWeale commented on Nov 17, 2025

adrianoresende commented on Nov 19, 2025

dcode commented on Nov 19, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions