adk api_server --a2a fails to register A2A routes in google-adk==2.2.0

[ufJmacca]

🔴 Required Information

Describe the Bug:

After upgrading google-adk from 2.1.0 to 2.2.0, running adk api_server --a2a --with_ui starts the FastAPI server successfully but fails to register A2A routes for an agent configured with agent.json.

The server logs the following during startup:

Failed to setup A2A agent orchestrator: cannot access local variable 'json' where it is not associated with a value

As a result, the expected A2A agent card endpoint is not registered and returns 404:

GET /a2a/orchestrator/.well-known/agent-card.json HTTP/1.1" 404 Not Found

This appears to be caused by a function-local import json inside get_fast_api_app() in google/adk/cli/fast_api.py. The function uses json.load(...) earlier during A2A route setup, but because json is later imported inside the same function, Python treats json as a local variable throughout the whole function scope. This causes an UnboundLocalError before the local import has executed.

Steps to Reproduce:

1. Install google-adk==2.2.0.

   uv add google-adk==2.2.0

2. Create an ADK agents directory containing an agent subdirectory with an agent.json file.

   Example structure:

   orchestrator_demo/
     orchestrator/
       agent.json
   

3. Start the ADK API server with A2A enabled.

   uv run adk api_server --a2a --with_ui orchestrator_demo \
     --host 127.0.0.1 \
     --port 8000 \
     --session_service_uri sqlite:///sessions.sqlite \
     --artifact_service_uri file:///artifacts

4. Observe the server startup logs.

   Setting up A2A agent: orchestrator
   Failed to setup A2A agent orchestrator: cannot access local variable 'json' where it is not associated with a value
   Application startup complete.
   

5. Attempt to access the expected A2A agent card endpoint.

   curl http://127.0.0.1:8000/a2a/orchestrator/.well-known/agent-card.json

6. Observe that the endpoint returns 404 Not Found.

Expected Behavior:

ADK should load:

orchestrator_demo/orchestrator/agent.json

Then create the A2A application and register A2A routes, including:

/a2a/orchestrator
/a2a/orchestrator/.well-known/agent-card.json

The agent card endpoint should return the configured A2A agent card instead of 404.

Observed Behavior:

The FastAPI server starts and reports startup completion, but A2A route setup fails internally.

Relevant startup log:

Setting up A2A agent: orchestrator
Failed to setup A2A agent orchestrator: cannot access local variable 'json' where it is not associated with a value
Application startup complete.

The expected A2A route is not registered:

GET /a2a/orchestrator/.well-known/agent-card.json HTTP/1.1" 404 Not Found

The server appears healthy, but A2A discovery and message flow are unavailable because the A2A endpoints are missing.

Environment Details:

• ADK Library Version (pip show google-adk): 2.2.0
• Desktop OS: N/A
• Python Version (python -V): Python 3.11

Model Information:

• Are you using LiteLLM: No
• Which model is being used: N/A

---

🟡 Optional Information

Regression:

Yes. This worked in google-adk==2.1.0 and fails after upgrading to google-adk==2.2.0.

Logs:

Setting up A2A agent: orchestrator
Failed to setup A2A agent orchestrator: cannot access local variable 'json' where it is not associated with a value
Application startup complete.
GET /a2a/orchestrator/.well-known/agent-card.json HTTP/1.1" 404 Not Found

Screenshots / Video:

N/A

Additional Context:

The suspected root cause is in google/adk/cli/fast_api.py, inside get_fast_api_app().

The function uses json.load(...) while setting up A2A routes. Later in the same function, there is a function-local import:

import json

Because Python treats any name assigned or imported inside a function as local to the entire function scope, the earlier json.load(...) resolves json as a local variable before it has been assigned. This causes:

UnboundLocalError: cannot access local variable 'json' where it is not associated with a value

This can occur even if the later conditional branch containing import json is not executed, because Python determines local variables at function compile time.

The module already imports json at module scope, so the later function-local import json appears unnecessary.

Suggested fix:

-    import inspect
-    import json
+    import inspect

Alternatively, move all required imports to module scope and rely on the existing module-level json import.

A regression test could call get_fast_api_app(..., a2a=True, web=True) against a temporary agents directory containing:

orchestrator/
  agent.json

Then assert that the generated FastAPI app includes routes for:

/a2a/orchestrator
/a2a/orchestrator/.well-known/agent-card.json

Minimal Reproduction Code:

# Minimal reproduction is primarily CLI-based.
# Directory structure:
#
# orchestrator_demo/
#   orchestrator/
#     agent.json
#
# Then run:
#
# uv run adk api_server --a2a --with_ui orchestrator_demo \
#   --host 127.0.0.1 \
#   --port 8000 \
#   --session_service_uri sqlite:///sessions.sqlite \
#   --artifact_service_uri file:///artifacts
#
# Then request:
#
# curl http://127.0.0.1:8000/a2a/orchestrator/.well-known/agent-card.json
#
# Expected:
#   Agent card JSON
#
# Actual:
#   404 Not Found

How often has this issue occurred?:

• Always (100%)

[adk-bot]

GitHub Issue #5994 Analysis: adk api_server --a2a fails to register A2A routes in google-adk==2.2.0

Executive Summary

1. What is broken? Starting the ADK API server with A2A habilitated (adk api_server --a2a) fails to initialize A2A routes and raises UnboundLocalError: cannot access local variable 'json' where it is not associated with a value due to a function-local import json inside get_fast_api_app.
2. Is there a linked PR that fixes this issue? None
3. Recommendation: Should Fix (High Priority) — This regression completely breaks A2A functionality and discovery/routing capabilities in google-adk==2.2.0 when started via the CLI. It has zero risk and is extremely simple to resolve.

Detailed Analysis

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

When checking whether A2A is enabled inside get_fast_api_app, the application loads the configuration file agent.json from each agent directory:

          with (p / "agent.json").open("r", encoding="utf-8") as f:
            data = json.load(f)
            agent_card = AgentCard(**data)

This parsing statement fast_api.py:L719-L721 relies on the json module.

However, later in the same function under a separate conditional block, there is a function-local import fast_api.py:L748:

    import inspect
    import json

Because Python resolves variable scope at compile time, any assignment or import of a name inside a function scope declares that name as local to the entire function scope. Thus, json is treated as local throughout get_fast_api_app. Since the execution path reaches json.load(f) before execution reaches the import json statement at line 748, Python raises:
UnboundLocalError: cannot access local variable 'json' where it is not associated with a value

Since fast_api.py:L19 already performs a global import of json:

import json

The local import on line 748 is redundant and directly causes this runtime error.

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

• Linked PR: None
• PR URL: N/A
• Analysis: No pull requests exist in the repository that mention or address the issue number 5994 or the associated UnboundLocalError error.

3. Recommendation

• Recommendation: Should Fix (High Priority)
• Rationale:
  • Impact: It is a critical blocker. It causes total A2A route registration failure, returning 404 Not Found for any A2A related endpoints (like agent-card.json). Standard developer workflows using A2A are broken in google-adk==2.2.0.
  • Complexity: Extremely low. Simply removing the reduntant import json statement on line 748 of fast_api.py resolves the scope binding issue.
  • Risk: Verifiably zero. The json module is already safely imported at the top-level of fast_api.py:L19, guaranteeing its availability.