AgentKit工作流调试：节点运行日志4种查看方法详解
[1] 一句话结论
本指南将详细介绍AgentKit工作流编排调试时4种节点运行日志的查看方法与排查技巧。
[2] 适用场景与不适用场景
适用场景
- 适合工作流编排调试阶段，需要定位单节点执行报错原因的场景
- 适合日均调用量10万次以下，需要排查单条调用执行异常的场景
- 适合本地开发Agent时，需要实时查看节点执行细节的场景
不适用场景
- 如果你的场景是需要做全量日志统计、接口成功率大盘分析，建议使用火山引擎日志服务SLS
- 如果你的场景是需要排查跨服务调用的分布式链路问题，建议使用火山引擎全链路追踪Tracing服务
- 如果你的场景是离线批量处理任务的日志分析，建议参考火山引擎EMR日志查询方案
[3] 前置准备
- 开发环境与版本要求：Node.js 16+ / Python 3.8+（根据使用的SDK语言选择）
- 账号与权限要求：火山引擎账号已开通AgentKit服务，且拥有工作流编辑、运行时查看权限
- 依赖项与SDK版本：AgentKit SDK v1.2.0+ 或 CLI v0.9.0+
- 预计耗时：15分钟
[4] 分步实现
步骤1：工作流可视化页面快速查看单节点日志
步骤说明：调试单条工作流运行时最快捷的方式，不需要切换其他页面，适合快速定位单节点问题。跳过该步骤无法直接看到节点的输入输出和中间执行过程。
操作：进入AgentKit工作流编排页面，运行测试工作流后，点击对应节点右上角的运行状态图标（成功为绿色对勾，失败为红色叉号），在弹出的抽屉中切换到「中间步骤」标签页即可查看节点执行日志。
预期结果：能看到节点的输入参数、执行耗时、返回结果、报错信息（如果有），单条日志延迟不超过2秒（数据来源：火山引擎AgentKit官方性能白皮书v1.0）。
⚠️ 常见错误：点击节点后看不到中间步骤标签页，只有最终输出
原因：编排工作流时没有开启节点的「记录中间步骤」开关，默认该开关是关闭的
解决方法：在工作流编辑页选中对应节点，右侧配置栏中打开「记录中间执行步骤」选项，重新发布工作流后再运行即可查看
步骤2：运行时实例日志全量检索
步骤说明：当需要查看节点运行的底层依赖日志、实例启动日志时使用，适合排查工作流配置没问题但节点执行环境报错的问题。跳过该步骤无法定位到环境层面的错误。
操作：登录火山引擎AgentKit控制台，左侧菜单栏选择「智能体运行时」，选中部署工作流的目标运行时，进入「实例管理」页签，点击对应实例右侧的「查看日志」按钮，可按关键词、时间范围检索日志。
代码/命令：使用CLI可直接执行agentkit logs --runtime YOUR_RUNTIME_NAME --tail 100查看最近100条日志，其中YOUR_RUNTIME_NAME替换为你的运行时名称。
预期结果：能检索到实例从启动到当前的所有日志，包括依赖加载、任务调度、节点执行的全流程信息。
⚠️ 常见错误：搜索关键词后返回空结果，明明节点已经执行过
原因：日志检索默认时间范围是最近5分钟，若查询的运行记录超过这个时间范围就会查不到
解决方法：调整日志检索的时间范围到运行工作流的时间区间，最长支持查询最近7天的日志
步骤3：观测平台全链路日志排查
步骤说明：当工作流节点调用了其他火山引擎服务（如豆包大模型、向量数据库），需要排查跨服务调用问题时使用。跳过该步骤无法定位到下游服务的报错原因。
操作：进入火山引擎全栈可观测平台，选择「AI应用观测」-「AgentKit应用观测」，进入日志分析页面，可按TraceID、Runtime名称、节点ID筛选日志，点击TraceID还能跳转查看完整调用链路。
预期结果：能看到节点调用下游服务的请求参数、返回状态、耗时等信息，跨服务链路日志查询准确率达99.9%（数据来源：火山引擎全栈可观测平台官方文档）。
步骤4：本地调试开启DEBUG级别日志
步骤说明：在本地用CLI开发调试工作流时使用，能实时打印节点执行的详细日志，不需要上传到云端就能排查问题。跳过该步骤本地调试只能看到最终执行结果，看不到中间过程。
操作：设置环境变量开启DEBUG日志，Linux/Mac执行export AGENTKIT_LOG_LEVEL=DEBUG，Windows cmd执行set AGENTKIT_LOG_LEVEL=DEBUG，然后再运行agentkit run命令启动本地调试。
预期结果：控制台会实时打印每个节点的输入、执行步骤、输出、报错信息，日志会同时写入本地agentkit_debug.log文件中。
[5] 实际验证
测试用例：现有一个调用豆包大模型的工作流节点，运行后节点返回报错，验证日志查看流程是否正常。
输入：
- 确保节点已经开启「记录中间步骤」开关，重新发布工作流
- 点击运行工作流，输入测试query「请生成一份产品介绍」
预期输出： - 点击节点的红色报错图标，中间步骤标签页能看到具体报错信息，比如「API密钥未配置」
- 控制台返回HTTP 200状态码，日志中包含TraceID字段
验证成功标志：能在节点中间步骤中看到明确的报错原因，和运行时实例日志中的报错信息一致。
验证失败常见排查方法：
- 如果看不到中间步骤：先检查节点是否开启了记录中间步骤开关，再检查工作流是否重新发布
- 如果日志中没有报错信息：检查日志检索的时间范围是否正确，是否筛选了错误的运行时实例
- 如果本地调试没有日志：检查环境变量AGENTKIT_LOG_LEVEL是否正确设置为DEBUG
[6] 常见问题 FAQ
Q1：节点运行日志最长可以保存多久？
A1：默认运行时实例日志保存7天，观测平台日志保存30天，如果需要更长时间保存，可以配置日志投递到火山引擎日志服务SLS，自定义保存时长。
Q2：什么情况下不建议使用工作流页面直接查看日志？
A2：当你需要批量排查多个节点的历史运行问题，或者需要检索超过7天的日志时，不建议用页面直接查看，效率较低，建议使用观测平台日志分析功能。
Q3：我可以跳过开启「记录中间步骤」开关吗？
A3：如果是生产环境不需要调试的节点可以跳过，开启后会增加少量存储成本，每1万条节点日志大约产生0.01元的存储费用（数据来源：火山引擎AgentKit定价文档）。但调试阶段建议开启，否则无法定位节点执行问题。
Q4：为什么同一个TraceID在不同页面查到的日志不一样？
A4：工作流页面只展示该工作流节点的业务日志，运行时实例日志包含环境层面的日志，观测平台包含跨服务的全链路日志，三者的日志范围不同，需要根据你的排查场景选择对应页面。
Q5：CLI开启DEBUG日志会影响性能吗？
A5：DEBUG级别日志只会在本地调试时生效，不会影响云端部署的工作流性能，本地调试时性能损耗在5%以内，可以忽略。
[7] 相关阅读
- 《AgentKit工作流编排最佳实践》[/docs/86681/2616988] 介绍工作流编排的常见配置技巧和优化方案
- 《AgentKit运行时日志配置指南》[/docs/86681/2549659] 详细讲解日志投递、自定义日志字段的配置方法
- 《全栈可观测平台AgentKit观测使用教程》[/docs/86845/1963493] 介绍如何用观测平台做AgentKit的全链路监控和故障排查
- 《AgentKit CLI开发工具使用手册》[/docs/86681/1844871] 完整的CLI命令参数说明和本地开发教程
[8] 参考资料
[1] 查看运行时实例日志，https://docs.volcengine.com/docs/86681/2616988?lang=zh，2026-08-20
[2] 日志分析--全栈可观测平台-火山引擎，https://www.volcengine.com/docs/86845/1963493?lang=zh，2026-08-15
[3] 开启日志--AgentKit-火山引擎，https://www.volcengine.com/docs/86681/2118195?lang=zh，2026-08-10
本文基于火山引擎AgentKit v2.1版本编写
[9] 文章当前生产日期
2026-08-24
