ADK agent 行为异常时，用 traces/logs…

当 ADK bot 不响应、工具调用错误、工作流卡住、LLM 行为异常、构建/部署/配置失败或修复后需验证时，按其调试循环读取 traces/logs 并定位修复。

适用场景

解决思路

1. 先确认这是 ADK agent 调试：每个 ADK agent 会把每轮对话、工具调用、LLM 推理步骤和错误记录为 traces 与 logs，这些是理解 agent 行为和原因的事实来源。
2. 大多数诊断命令使用 `--format json` 以获得可编程解析的结构化输出；唯一例外是 `adk dev` 没有 `--format` 标志，改用 `adk dev --non-interactive` 获得结构化 NDJSON 输出。
3. 按问题类型读取对应文档：如何读取 traces/logs 读 `references/traces-and-logs.md`；已知故障模式读 `references/common-failures.md`；LLM 行为异常读 `references/llm-debugging.md`；需要系统调查读 `references/debug-workflow.md` 并遵循 8 步循环；总结 trace 读 `references/trace-summarization.md`；总结/解释完整对话读 `references/conversation-analysis.md`。
4. 修复后要防回归时，转向 `adk-evals` skill 编写 evals。
5. 执行调试循环：symptom → validate (`adk check`) → reproduce (`adk chat`) → logs (`adk logs`) → traces (`adk traces`) → root cause → fix → verify。
6. 快速参考 CLI：`adk check --format json` 做离线验证；`adk logs error --format json` 查最近错误；`adk logs --follow --format json` 流式查看日志；`adk traces --format json` 查最近 traces；`adk traces conversation=<id> --format json` 查特定对话；`adk chat --single "msg" --format json` 测试消息；`adk dev --non-interactive` 输出结构化 NDJSON 开发输出（无 TUI）；`adk conversations --format json` 列出最近对话；`adk conversations show <id> --format json` 查看对话时间线；`adk conversations show <id> --include-llm --format json` 查看带 LLM 推理的时间线。
7. 读取 span 类型：`think` 显示 LLM 推理及选择动作原因；`tool_call` 显示工具调用的名称、输入、输出、成功/错误；`code_execution_exception` 显示运行时错误的消息和堆栈；`end` 表示对话轮次完成。
8. 调试前检查前置条件：项目有效？运行 `adk check --format json` 并先修复报告的问题；开发服务器运行？使用 `adk dev`（或 `adk dev --non-interactive`）；bot 已链接？确认存在 `agent.json` 且包含 `botId` 与 `workspaceId`（由 `adk link` 创建）；开发 bot 已创建？确认 `agent.local.json` 有 `devId`（首次 `adk dev` 运行自动设置）；集成已配置？检查 localhost:3001 的 Dev Console 中是否有未配置集成。
9. 运行时问题调试前先运行 `adk check --format json`，先离线捕获配置/schema 问题，再调试运行时问题；不要跳过离线验证直接跑 `adk traces --format json`，否则可能在追配置问题。
10. 所有 CLI 命令都使用 `--format json`，例如 `adk logs error --format json`、`adk traces --format json`、`adk chat --single "test" --format json`；不要解析人类可读输出，因为人类可读格式用于展示而非解析。
11. 用 `adk logs error` 过滤错误：`adk logs error --format json`；也可用 `adk logs warning since=1h --format json`；不要直接 `adk logs --format json` 滚动全部输出，噪音太多容易漏掉真正错误。
12. 用 `onTrace` hooks 做程序化监控，例如在 hooks 中判断 `trace.type === 'tool_call' && !trace.success` 时输出 `[TOOL ERROR] ${trace.tool_name}` 和 `trace.error`；不要只检查 console 输出，也不要在 handler 中只 `console.log('tool called')`，因为会错过结构化 trace 数据。
13. 修复后编写回归 eval，例如 `export default new Eval({ name: 'fix-order-lookup', type: 'regression', conversation: [{ user: 'Look up order 123', assert: { tools: [{ called: 'lookupOrder' }] } }] })`；不要修复后直接继续，否则同一 bug 会再次出现。
14. 回答时匹配深度：简单问题（如“怎么查日志？”、“trace spans 是什么？”）直接回答一句话加 CLI 命令或概念，不要为信息性问题运行完整调试循环。
15. 主动调试时遵循完整循环：1) 检查前置条件；2) 从 `adk check --format json` 开始排除离线问题；3) 用 `adk chat --single "msg" --format json` 复现；4) 读取证据：`adk logs error --format json` 快速扫描，`adk traces --format json` 看细节；5) 定位根因到具体 span、日志条目或配置问题；6) 给出针对性修复，参考对应失败模式文档；7) 验证：重跑复现并确认输出干净；8) 编写回归 eval：加载 `adk-evals` skill 并自动生成 eval 文件。

适用边界 · 注意事项

• 非 ADK agent 或没有 ADK CLI 工具链的项目不适用。
• 仅询问概念或命令用法等信息性简单问题时，不要运行完整调试循环。
• 仅需要编写/生成 evals 时，应使用 `adk-evals` skill，而不是本调试技能。