adk-debugger

ADK 调试技能

什么是 ADK 调试？

每个 ADK Agent 都会将其行为记录为跟踪记录和日志——每轮对话、工具调用、大模型推理步骤和错误都包含在内。这些记录是了解 Agent 做了什么以及为什么这么做的事实依据。

ADK CLI 提供了所需的调试工具。大多数诊断命令都支持 --format json；可用它获取程序化输出。例外是 adk dev，它没有 --format 标志，可使用 adk dev --non-interactive 获取结构化 NDJSON 输出。

何时使用此技能

当开发者询问以下问题时，请使用此技能：

• 机器人无法正常工作——不响应、响应错误或行为异常
• 工具问题——调用了错误的工具、工具报错或参数出现幻觉
• 工作流问题——工作流卡住、步骤未执行或状态异常
• 读取跟踪记录/日志——如何查询、筛选和解读调试输出
• 大模型行为异常——产生幻觉、拒绝回答、循环或提取效果不佳
• 构建/部署失败——验证错误或架构不匹配
• 配置问题——agent.json 与 agent.local.json 的区别、集成设置
• 修复后验证——确认修复有效、编写回归评估

触发问题：

• “我的机器人没有响应”
• “调用了错误的工具”
• “我的工作流卡住了”
• “如何读取跟踪记录？”
• “如何查看日志？”
• “大模型在产生幻觉”
• “上次更改后出了问题”
• “我的部署失败了”
• “adk check 发现了错误”
• “总结这条跟踪记录”
• “跟踪记录 X 中发生了什么？”
• “概述一下这一轮对话”
• “为什么机器人在这条跟踪记录中执行了 X？”
• “带我了解一下发生了什么”
• “如何调试这个问题？”
• “总结这段对话”
• “解释一下对话 X 中发生了什么”
• “机器人为什么会这样回答？”
• “带我了解一下这段对话”
• “这段对话中出了什么问题？”

可用文档

文件	内容
references/traces-and-logs.md	CLI 调试工具、日志查询、跟踪记录结构、跨度类型、onTrace 钩子，以及使用 adk chat 复现问题
references/common-failures.md	运行时故障模式——验证、机器人无响应、工具错误、工作流卡住、集成失败、构建错误和配置混淆
references/llm-debugging.md	大模型行为问题——调用错误工具、参数幻觉、拒绝回答、令牌限制、循环，以及读取模型推理内容
references/debug-workflow.md	系统化的 8 步调试循环：验证 → 复现 → 查看日志 → 查看跟踪记录 → 分类 → 修复 → 验证 → 预防
references/trace-summarization.md	如何获取、梳理并以自由形式的自然语言叙述总结跟踪记录——根据上下文调整详略程度
references/conversation-analysis.md	如何总结并解释完整对话——列出对话、分析时间线、与跟踪记录关联，以及常见模式

如何回答

1. “如何查看跟踪记录／日志？” → 阅读 traces-and-logs.md，了解 CLI 命令和跟踪记录结构
2. 某项功能出故障，且属于已知模式 → 阅读 common-failures.md，查找对应的故障模式
3. 大模型行为异常 → 阅读 llm-debugging.md，查找对应的行为问题
4. 需要系统化调查 → 阅读 debug-workflow.md，并按照 8 步循环操作
5. “总结这条跟踪记录”／“发生了什么？” → 阅读 trace-summarization.md，了解如何获取、梳理和讲述跟踪记录
6. “总结这段对话”／“解释发生了什么” → 阅读 conversation-analysis.md，了解如何总结和解释多轮对话
7. 修复后需要防止回归 → 指向 adk-evals 技能，了解如何编写评估

---

快速参考

调试循环

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

CLI 命令（优先使用结构化输出）

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 类型

类型	内容说明
think	大模型推理——说明它为何选择某个操作
tool_call	工具调用——名称、输入、输出、成功／错误
code_execution_exception	运行时错误——消息和堆栈跟踪
end	对话轮次已完成

---

前提条件检查

开始调试前，请确认：

• 项目有效？ 运行 adk check --format json，先修复报告的所有问题
• 开发服务器正在运行？ 运行 adk dev（或运行 adk dev --non-interactive 以获取结构化 NDJSON 输出）
• Bot 已关联？ agent.json 中存在 botId 和 workspaceId（由 adk link 创建）
• 开发 Bot 已创建？ agent.local.json 中包含 devId（首次运行 adk dev 时自动设置）
• 集成已配置？ 查看 localhost:3001 上的 Dev Console，检查是否存在未配置的集成

---

关键模式

✅ 调试运行时问题前先运行 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

---

✅ 所有 CLI 命令都使用 --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

---

示例问题

基础：

• “我的 Bot 没有响应——如何找出原因？”
• “如何检查我的 ADK 项目是否有错误？”
• “agent.json 和 agent.local.json 有什么区别？”

中级：

• “Bot 调用了 createTicket 而不是 lookupTicket——如何修复？”
• “工作流启动了，但第二步始终没有运行”
• “如何查看大模型做出决策时的思考过程？”
• “集成操作因身份验证错误而失败”

高级：

• “如何设置 onTrace 钩子以自动检测错误？”
• “模型反复调用同一个工具——如何添加防护措施？”
• “如何使用计时指标监控工具调用性能？”
• “如何系统化地调试多步骤工作流故障？”

---

回复格式

根据问题调整详略程度。

简单问题（“如何查看日志？”，“什么是跟踪 Span？”）

直接回答——用一句话说明，并提供 CLI 命令或概念。对于信息查询问题，不要执行完整的调试循环。

主动调试（“我的机器人坏了”“X 不工作”）

遵循完整流程：

1. 检查前置条件——确认开发服务器、配置文件和项目验证
2. 从 adk check --format json 开始——排除离线问题
3. 复现问题——使用 adk chat --single "msg" --format json 创建干净的复现
4. 查看证据——使用 adk logs error --format json 快速扫描，使用 adk traces --format json 查看详细信息
5. 找出根本原因——指出具体的跨度、日志条目或配置问题
6. 提出有针对性的修复方案——参考相应的故障模式文档
7. 验证——重新运行复现，确认输出正常
8. 编写回归评估——加载 adk-evals 技能并自动生成评估文件