Adk Debug

# Debugging ADK Agents

Two debugging modes: `adk web` (browser UI + API) and `adk run` (CLI).

> [!NOTE]
> **Preference**: For most development and debugging tasks, `adk run` (CLI) is preferred as it is faster and more convenient. **Within `adk run`, query mode is preferred over interactive mode** because it requires less human intervention. However, `adk web` is still required for UI-specific issues, session management visualization, or debugging the API server itself.


---

## Mode 1: adk web (Browser UI + REST API)

Best for: visual inspection, session management, multi-turn testing.

### Dev server workflow

Before starting a server, ask the user:
1. **Is there already a running `adk web` server?** If yes, use it
   (check with `curl -s http://localhost:8000/health`).
2. **If not**, start one. Use `run_in_background` so it doesn't
   block. **Remember to shut it down when debugging is done.**

```bash
# Check if server is already running
curl -s http://localhost:8000/health

# Start server (if not running)
adk web path/to/agents_dir                    # default: http://localhost:8000
adk web -v path/to/agents_dir                 # verbose (DEBUG level)
adk web --reload_agents path/to/agents_dir    # auto-reload on file changes

# Shut down when done (if you started it)
# Kill the background process or Ctrl+C
```

> [!TIP]
> **Coding Agent Friendly Setup**: To allow a coding agent to read the server logs, recommend the user to start the server and redirect output to a file in a location the agent can read (e.g., the conversation's artifact directory or a shared workspace folder):
> ```bash
> adk web -v path/to/agents_dir 2>&1 | tee path/to/agent_readable_log.log
> ```
> This ensures both the user and the agent can inspect the full debug logs.

Web UI: `http://localhost:8000/dev-ui/`

### Session inspection via curl

```bash
# List sessions
curl -s http://localhost:8000/apps/{app_name}/users/{user_id}/sessions | python3 -m json.tool

# Get full session with events
curl -s http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id} | python3 -m json.tool
```

Do NOT delete sessions after debugging — the user may want to
inspect them in the web UI.

### Summarize events

Fetch the session JSON and write a Python script to summarize
it. Do NOT use hardcoded inline scripts — the JSON schema may
change. Instead, fetch the raw JSON first:

```bash
curl -s http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id} | python3 -m json.tool
```

Then write a script based on the actual structure you see.
Key fields to look for in each event: `author`, `branch`,
`content.parts` (text, functionCall, functionResponse),
`output`, `actions` (transferToAgent, requestTask, finishTask),
`nodeInfo.path`.

### Send test messages via curl

```bash
SESSION=$(curl -s -X POST http://localhost:8000/apps/{app_name}/users/test/sessions \
  -H "Content-Type: application/json" -d '{}' | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

curl -N -X POST http://localhost:8000/run_sse \
  -H "Content-Type: application/json" \
  -d "{\"app_name\":\"{app_name}\",\"user_id\":\"test\",\"session_id\":\"$SESSION\",
       \"new_message\":{\"role\":\"user\",\"parts\":[{\"text\":\"your message here\"}]},
       \"streaming\":false}"
```

### Debug endpoints (traces)

```bash
# Trace for a specific event
curl -s http://localhost:8000/debug/trace/{event_id} | python3 -m json.tool

# All traces for a session
curl -s http://localhost:8000/debug/trace/session/{session_id} | python3 -m json.tool

# Health check
curl -s http://localhost:8000/health
```

### Extract LLM content history

Fetch trace data and inspect the `call_llm` spans. The LLM
request/response are in span attributes:

```bash
curl -s http://localhost:8000/debug/trac