Index of every page on this site: llms.txt
All skills
google avatar

/adk-debug

@37de74d
by googlegoogle/adk-python22k stars
4,392
Run it yourself

Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model. Covers the `adk run` CLI and the `adk web` dev server with its session, trace, and debug HTTP endpoints. Use when an agent returns the wrong answer, ignores a tool or swallows a tool error, hangs, loops, emits raw JSON instead of calling tools, is not discovered by `adk web`, when a sub-agent cannot see the parent conversation, or when you need the LLM request/response, token counts, or logs for a run. Don't use for how ADK is designed internally (use `adk-architecture`), for building a new agent or workflow (use `adk-agent-builder`), for environment or dependency setup failures (use `adk-setup`), or for lint and style nits (use `adk-style`).

Use this Skill: https://skilld.dev/gh/google/adk-python/adk-debug

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈196 tokens for metadata: the name and description. ≈657 when used: this file. ≈6k more on demand in 5 files.

Description uses 9.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈785 characters, or 9.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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. The first two stdout lines are log-setup notices, not JSON; keep the events with grep '^{'.
  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 trace 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 or /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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts28d3 checks · Risk SAFE
  • Gen Agent Trust Hub28d

    This skill is a comprehensive debugging and diagnostic guide for ADK (Agent Development Kit) agents. It provides instructions for using command-line tools, inspecting logs, and interacting with development server APIs for troubleshooting agent behavior. The resources and libraries described are consistent with the vendor's ecosystem.

  • Socket28d

    No alerts

  • Snyk28d

    Risk: LOW · No issues

Signed by skilld at 37de74d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 days ago

README badge

README badge for google/adk-python/adk-debug