Debugging ADK agents

Two entry points. Default to adk run: one process, no server, and --jsonl output that pipes straight into grep or python3. Switch to adk web when you need the browser UI, a persisted session you can click through, or the trace endpoints that expose the exact LLM request.

First moves

1. Reproduce headlessly: adk run --jsonl {agent_dir} "{query}". Without --jsonl, adk run prints only text parts — tool calls and tool errors are invisible.
2. Read the log file. adk run writes to /tmp/agents_log/agent.latest.log and nothing to the terminal; adk web does the opposite. See logs-and-traces.md.
3. Match the symptom in failure-modes.md before reading source — most reports are one of a handful of known shapes.
4. If the text is fine but the routing is not, dump the events and read author, branch, nodeInfo.path, and actions — event-flow.md.
5. If the model itself misbehaved, read what it actually received from the call_llm span rather than guessing from the agent definition — logs-and-traces.md.

References

• cli-run.md — adk run flags, the JSONL event shape, multi-turn and human-in-the-loop resume, exit codes, driving a Runner from Python.
• web-api.md — starting adk web, listing and reading sessions over HTTP, posting test messages to /run_sse.
• logs-and-traces.md — log levels and where each command writes them, the trace endpoints, span attributes, and the env vars that control whether prompts appear in spans.
• failure-modes.md — ADK-specific symptoms with the cause and a concrete check for each.
• event-flow.md — how an invocation becomes events, callback order, the event fields that matter, and where each stage lives in the source.

Ground rules

• Leave sessions in place when you finish. The user may still want to open them in the web UI, and adk web has no undelete.
• Delete any throwaway agent you created for a repro, unless the user asked to keep it.
• Reach for a unit test in tests/unittests/ when the bug is inside one component, and for a sample under contributing/samples/ (see adk-sample-creator) when it only reproduces with runner, agent, and workflow wired together.