adk-debug

调试 ADK Agent

有两个入口。默认使用 adk run：单进程、无需服务，并且 --jsonl 输出可以直接通过管道传给 grep 或 python3。需要浏览器界面、可供点击查看的持久化会话，或能公开精确 LLM 请求的 trace 端点时，切换到 adk web。

首选操作

1. 无头模式下复现：adk run --jsonl {agent_dir} "{query}"。不加 --jsonl 时，adk run 只会打印文本部分——工具调用和工具错误都不可见。
2. 阅读日志文件。adk run 会写入 /tmp/agents_log/agent.latest.log，而不会写入终端；adk web 则相反。请参阅 logs-and-traces.md。
3. 先在 failure-modes.md 中查找与症状相符的情况，再阅读源码——大多数问题都属于少数几种已知类型。
4. 如果文本正常，但路由不正常，请转储事件并查看 author、branch、nodeInfo.path 和 actions — event-flow.md。
5. 如果问题出在模型本身，请查看 call_llm span 中模型实际收到的内容，而不是根据 Agent 定义猜测 — logs-and-traces.md。

参考资料

• 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 无法恢复已删除的会话。
• 除非用户要求保留，否则删除为复现问题而创建的临时 Agent。
• 如果问题出在单个组件内部，请使用 tests/unittests/ 中的单元测试；如果只有在 Runner、Agent 和工作流连接在一起时才能复现，请使用 contributing/samples/ 下的示例（参见 adk-sample-creator）。