ADK Debugger Skill

What is ADK Debugging?

--format json

When to Use This Skill

• 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

• "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?"

Available Documentation

references/traces-and-logs.md

onTrace

adk chat

references/common-failures.md

references/llm-debugging.md

references/debug-workflow.md

references/trace-summarization.md

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. 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 (always use

--format json

)

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 <id> --format json  # specific conversation
adk chat --single "msg" --format json            # test message
adk dev --non-interactive --format json          # structured dev output

Span Types

think

tool_call

code_execution_exception

end

Prerequisites Check

• Project valid? Run

  adk check --format json

  — fix any reported issues first
• Dev server running?

  adk dev

  (or

  adk dev --non-interactive --format json

  for structured 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 Control Panel at localhost:3001 for unconfigured integrations

Critical Patterns

adk check

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

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

--format json

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

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

adk logs error

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

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

onTrace

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

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

// 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' }] } }],
})

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

Example Questions

• "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?"

• "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"

• "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

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. Suggest a regression eval — point to the

   adk-evals

   skill