adk-web-debug-launcher

adk-web-debug-launcher

Launch ADK 2.0's built-in debug UI to test, inspect, and debug agents locally.

Quickstart

cd /path/to/project       # contains agent.py with root_agent
adk web                   # opens http://localhost:8000

The UI shows:

• Chat panel — interact with the agent
• Event timeline — every LLM call, tool call, state change
• State inspector — live session.state dict
• Function-call viewer — pretty-printed tool args + responses
• Trace export — download full session as JSON

Custom port

adk web --port 8080
adk web --host 0.0.0.0 --port 8080   # accessible on LAN

Multiple agents

If your project has several agent.py files in subdirs, ADK auto-discovers them:

project/
├── billing_agent/
│   └── agent.py        # has root_agent
├── support_agent/
│   └── agent.py
└── ...

adk web lists all in a dropdown.

Hot reload

adk web --reload

Watches *.py and reloads on change. Useful for iterative prompt tweaking.

Loading a config-defined agent

adk web --config ./agent.yaml

(See agent-config-no-code skill in adk-agent-builder.)

Environment

adk web reads .env in the working dir. Required for most agents:

GOOGLE_API_KEY=...           # AI Studio key
# OR for Vertex AI:
GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=my-project
GOOGLE_CLOUD_LOCATION=us-central1

Debugging tips

• Click an event in the timeline to see request/response payloads
• Tool call returns can be expanded — useful for malformed JSON
• The state diff panel shows what changed each turn
• Replay buttons (with rewindable sessions) let you re-run from any point

Validation

• adk web starts without import errors
• Browser opens automatically (or curl localhost:8000 returns HTML)
• Sending a message shows events streaming in
• API key validates against backend (test with a simple "hello")

See also

• cloud-run-deployer for moving from adk web to production
• agent-runtime-config for non-default runtime tuning