adk-debugger

name	adk-debugger
description	Systematic debugging for ADK agents — trace reading, log analysis, common failure diagnosis, and the debug loop.
license	MIT

ADK Debugger Skill

What is ADK Debugging?

Every ADK agent records its behavior as traces and logs — every conversation turn, tool call, LLM reasoning step, and error. These are the source of truth for understanding what your agent did and why.

The ADK CLI provides the tools you need to debug. Most diagnostic commands support --format json; use it for programmatic output. The exception is adk dev, which has no --format flag and uses adk dev --non-interactive for structured NDJSON output.

When to Use This Skill

Use this skill when the developer asks about:

• Bot not working — not responding, wrong responses, unexpected behavior
• Tool issues — wrong tool called, tool errors, hallucinated parameters
• Workflow problems — stuck workflows, steps not executing, state issues
• Reading traces/logs — how to query, filter, and interpret debug output
• LLM misbehavior — hallucinations, refusals, looping, poor extraction
• Build/deploy failures — validation errors, schema mismatches
• Config issues — agent.json vs agent.local.json, integration setup
• Post-fix verification — confirming a fix worked, writing regression evals

Trigger questions:

• "My bot isn't responding"
• "The wrong tool was called"
• "My workflow is stuck"
• "How do I read traces?"
• "How do I check logs?"
• "The LLM is hallucinating"
• "Something broke after my last change"
• "My deploy failed"
• "adk check found errors"
• "Summarize this trace"
• "What happened in trace X?"
• "Give me an overview of this conversation turn"
• "Why did the bot do X in this trace?"
• "Walk me through what happened"
• "How do I debug this?"
• "Summarize this conversation"
• "Explain what happened in conversation X"
• "Why did the bot respond that way?"
• "Walk me through this conversation"
• "What went wrong in this conversation?"

Available Documentation

File	Contents
references/traces-and-logs.md	CLI debugging tools, log querying, trace structure, span types, onTrace hooks, reproduction with adk chat
references/common-failures.md	Runtime failure patterns — validation, bot not responding, tool errors, workflow stuck, integration failures, build errors, config confusion
references/llm-debugging.md	LLM behavior issues — wrong tool, hallucinated params, refusals, token limits, looping, reading model reasoning
references/debug-workflow.md	The systematic 8-step debug loop: validate → reproduce → logs → traces → classify → fix → verify → prevent
references/trace-summarization.md	How to fetch, walk, and summarize traces as free-form natural-language narratives — adapting depth to context
references/conversation-analysis.md	How to summarize and explain full conversations — listing conversations, timeline analysis, correlating with traces, common patterns

How to Answer

1. "How do I read traces/logs?" → Read traces-and-logs.md for CLI commands and trace structure
2. Something is broken, known pattern → Read common-failures.md for the matching failure pattern
3. LLM is misbehaving → Read llm-debugging.md for the matching behavior issue
4. Systematic investigation needed → Read debug-workflow.md and follow the 8-step loop
5. "Summarize this trace" / "What happened?" → Read trace-summarization.md for how to fetch, walk, and narrate traces
6. "Summarize this conversation" / "Explain what happened" → Read conversation-analysis.md for multi-turn conversation summaries and explanations
7. After fixing, need to prevent regression → Point to the adk-evals skill for writing evals

---

Quick Reference

The Debug Loop

symptom → validate (adk check) → reproduce (adk chat) → logs (adk logs) → traces (adk traces) → root cause → fix → verify

CLI Commands (prefer structured output)

adk check --format json                         # offline validation
adk logs error --format json                     # recent errors
adk logs --follow --format json                  # stream live
adk traces --format json                         # recent traces
adk traces conversation=<id> --format json       # specific conversation
adk chat --single "msg" --format json            # test message
adk dev --non-interactive                        # structured NDJSON dev output (no TUI)
adk conversations --format json                  # list recent conversations
adk conversations show <id> --format json        # conversation timeline
adk conversations show <id> --include-llm --format json  # timeline with LLM reasoning

Span Types

Type	What It Shows
think	LLM reasoning — why it chose an action
tool_call	Tool invocation — name, input, output, success/error
code_execution_exception	Runtime error — message and stack trace
end	Conversation turn completed

---

Prerequisites Check

Before debugging, verify:

• Project valid? Run adk check --format json — fix any reported issues first
• Dev server running? adk dev (or adk dev --non-interactive for structured NDJSON output)
• Bot linked? agent.json exists with botId and workspaceId (created by adk link)
• Dev bot created? agent.local.json has devId (set automatically by the first adk dev run)
• Integration configured? Check Dev Console at localhost:3001 for unconfigured integrations

---

Critical Patterns

✅ Run adk check before debugging runtime issues

# CORRECT — catch config/schema problems offline first
adk check --format json
# Then debug runtime issues

❌ Skipping offline validation

# WRONG — jumping straight to runtime debugging wastes time on config issues
adk traces --format json  # might be chasing a config problem

---

✅ Use --format json on all CLI commands

# CORRECT — structured output for reliable parsing
adk logs error --format json
adk traces --format json
adk chat --single "test" --format json

❌ Parsing human-readable output

# WRONG — human-readable format is for display, not parsing
adk logs error
adk traces

---

✅ Use adk logs error to filter errors

# CORRECT — focused error scan
adk logs error --format json
adk logs warning since=1h --format json

❌ Scrolling through all output

# WRONG — too much noise, easy to miss the actual error
adk logs --format json  # 50 entries of everything

---

✅ Use onTrace hooks for programmatic monitoring

// CORRECT — structured, automated trace analysis
hooks: {
  onTrace: ({ trace }) => {
    if (trace.type === 'tool_call' && !trace.success) {
      console.error(`[TOOL ERROR] ${trace.tool_name}`, trace.error)
    }
  }
}

❌ Only checking console output

// WRONG — console.log in handlers misses the structured trace data
handler: async (input) => {
  console.log('tool called') // not useful for debugging
}

---

✅ Write a regression eval after fixing

// CORRECT — prevents the bug from coming back
export default new Eval({
  name: 'fix-order-lookup',
  type: 'regression',
  conversation: [{ user: 'Look up order 123', assert: { tools: [{ called: 'lookupOrder' }] } }],
})

❌ Fixing and moving on

// WRONG — the same bug will return and you'll debug it again

---

Example Questions

Basic:

• "My bot isn't responding — how do I figure out why?"
• "How do I check for errors in my ADK project?"
• "What's the difference between agent.json and agent.local.json?"

Intermediate:

• "The bot called createTicket instead of lookupTicket — how do I fix this?"
• "My workflow starts but the second step never runs"
• "How do I see what the LLM was thinking when it made a decision?"
• "Integration actions are failing with auth errors"

Advanced:

• "How do I set up onTrace hooks for automated error detection?"
• "The model loops on the same tool call — how do I add a guardrail?"
• "How do I monitor tool call performance with timing metrics?"
• "How do I systematically debug a multi-step workflow failure?"

---

Response Format

Match depth to the question.

Simple questions ("how do I check logs?", "what are trace spans?")

Answer directly — one sentence + the CLI command or concept. Don't run the full debug loop for informational questions.

Active debugging ("my bot is broken", "X isn't working")

Follow the full loop:

1. Check prerequisites — verify dev server, config files, project validation
2. Start with adk check --format json — rule out offline issues
3. Reproduce — use adk chat --single "msg" --format json to create a clean reproduction
4. Read the evidence — adk logs error --format json for quick scan, adk traces --format json for details
5. Identify the root cause — point to the specific span, log entry, or config issue
6. Suggest a targeted fix — reference the appropriate failure pattern doc
7. Verify — re-run the reproduction, confirm clean output
8. Write a regression eval — load the adk-evals skill and generate the eval file automatically