用途：诊断行为异常的 ADK 智能体。做法是检查会话、事件、工具调用，以及实际到达模型的那次请求。两个入口：默认用 adk run，单进程无服务器，--jsonl 输出可直接管道给 grep 或 python3；需要浏览器 UI、可点击的持久化会话或暴露确切 LLM 请求的 trace 端点时改用 adk web。
起步：无头复现用 adk run --jsonl {agent_dir} "{query}"；不带 --jsonl 时 adk run 只打印文本部分，工具调用和工具错误不可见。注意 adk run 写入 /tmp/agents_log/agent.latest.log 而终端无输出，adk web 相反。文本正常但路由异常时，转储事件并查看 author、branch、nodeInfo.path 和 actions。模型本身表现异常时，读取 call_llm span 中它实际收到的内容，而不是仅凭智能体定义猜测。
参考文档：cli-run.md 覆盖 adk run 标志、JSONL 事件结构、多轮与人机回环恢复、退出码、从 Python 驱动 Runner；web-api.md 覆盖启动 adk web、通过 HTTP 列出和读取会话、向 /run_sse 发送测试消息；logs-and-traces.md 覆盖日志级别与各命令写入位置、trace 端点、span 属性及控制提示词是否出现在 span 中的环境变量；failure-modes.md 列出 ADK 特有症状及每种的具体检查方法；event-flow.md 说明一次调用如何变成事件、回调顺序、重要事件字段及各阶段在源码中的位置。
基本规则：结束时保留会话，用户可能仍想在 Web UI 中打开，且 adk web 无法撤销删除；删除为复现创建的临时智能体，除非用户要求保留；当缺陷位于单个组件内部时使用 tests/unittests/ 中的单元测试，当只有 runner、agent 和 workflow 接在一起才能复现时使用 contributing/samples/ 下的示例。