AgentKit工作流卡顿：3种快速定位详细报错日志方法

[1] 一句话结论 #

本指南将介绍AgentKit工作流卡顿场景下3种查看详细报错日志的实操方法与排查技巧。

[2] 适用场景与不适用场景 #

适用场景

1. 单节点工作流执行卡顿超过30s、无明确返回值的故障排查场景；
2. 日均工作流调用量在1000次以上、偶发卡顿需要根因定位的生产环境场景；
3. 多工具调用链路长、需要关联跨组件日志的复杂智能体场景。

不适用场景

1. 本地测试环境未部署AgentKit Runtime的场景，建议直接查看IDE本地输出日志；
2. 工作流卡顿由大模型接口限流导致的场景，建议优先参考豆包API限流排查指南[/docs/68851/1769553]；
3. 服务器硬件故障导致的全链路不可用场景，建议先查看云服务器ECS监控告警[/docs/218794/1128865]。

[3] 前置准备 #

• 已开通火山引擎AgentKit服务，拥有实例读权限与日志查询权限；
• AgentKit CLI版本≥v1.2.0，Python环境≥3.9；
• 已知故障工作流对应的Runtime ID或Trace ID；
• 预计操作耗时：15分钟。

[4] 分步实现 #

步骤1：控制台快速查询表层报错

步骤说明：先通过控制台可视化界面快速定位卡顿发生的阶段，不需要额外部署工具，适合快速排查入门级问题。跳过这一步直接查深层日志会增加不必要的排查成本。
操作：登录火山引擎控制台进入AgentKit页面，找到目标运行时实例，进入日志页签选择卡顿发生的时间范围，筛选ERROR级日志。
预期结果：能看到对应时间点的错误堆栈，包含报错节点ID与异常类型。

⚠️ 常见错误：选择时间范围后看不到任何日志
原因：AgentKit日志上报延迟约1分钟，且默认只展示最近1小时的日志
解决方法：将时间范围放宽5分钟，若还是没有可切换到「全量日志」标签页查看归档数据。

步骤2：CLI实时抓取运行时日志

步骤说明：当控制台日志不全时，用CLI可以实时抓取运行时的全量日志，适合复现卡顿场景时动态捕获报错，不需要开通额外的观测服务。
代码/命令：

# 先获取所有运行时ID
agentkit list-runtimes
# 实时拉取指定运行时的日志
agentkit logs --runtime <YOUR_RUNTIME_ID> --follow

预期结果：复现卡顿操作后，控制台会实时输出DEBUG到ERROR级别的全量日志，包含每个工作流节点的入参出参。

⚠️ 常见错误：执行CLI命令返回权限报错403
原因：本地配置的AK/SK没有AgentKit的日志查询权限，或者CLI版本低于v1.2.0不支持logs命令
解决方法：先执行agentkit upgrade升级CLI到最新版，再到访问控制RAM页面给账号添加「AgentKitFullAccess」权限。

步骤3：本地日志文件解析结构化数据

步骤说明：CLI拉取的日志默认会存放在本地目录，适合需要离线分析长时间范围日志的场景，不需要依赖网络连接。
代码/命令：

# 进入会话日志存储目录
cd ~/.agentkit/runtimes/<YOUR_RUNTIME_ID>/sessions/
# 筛选ERROR级别的日志（需要提前安装jq工具）
jq 'select(.level == "ERROR")' session_20260824_1234.jsonl

预期结果：输出所有ERROR级别的结构化日志，包含Trace ID、节点耗时、异常堆栈等信息。

步骤4：全栈观测平台关联跨组件日志

步骤说明：当卡顿是由依赖的其他服务（比如大模型API、向量数据库）导致时，需要通过Trace ID串联全链路日志，定位跨服务的异常点。
操作：登录火山引擎全栈可观测平台，进入「AgentKit应用观测」-「日志分析」，输入工作流返回的Trace ID进行检索。
预期结果：能看到从工作流触发到所有依赖服务调用的完整链路日志，标注每个节点的耗时，快速定位耗时最长的卡顿节点。

步骤5：关联资源指标排除硬件瓶颈

步骤说明：如果日志中没有明确报错，需要排查是不是资源不足导致的卡顿，这是很多新手容易忽略的排查点。
操作：在观测平台中切换到「指标监控」标签页，查看对应Runtime的CPU、内存、磁盘IO指标。
预期结果：若CPU使用率持续超过90%超过10s，说明是资源不足导致的卡顿，需要扩容运行时实例。

[5] 实际验证 #

测试用例：输入触发卡顿的工作流请求，拿到返回的Trace ID为trace_20260824_abc123，预期能定位到卡顿根因为向量数据库调用超时。
验证步骤：1. 控制台查询该Trace ID对应日志，能看到工作流执行到第三个工具调用节点时停止；2. CLI拉取对应Runtime日志，能看到该节点抛出「连接向量数据库超时」的异常；3. 观测平台查看链路日志，显示向量数据库返回504超时。
验证成功标志：三个渠道查询到的报错信息一致，明确指向超时的依赖服务。
常见排查方法：1. 若三个渠道日志不一致，优先以观测平台全链路日志为准；2. 若没有找到对应Trace ID，检查时间范围是否正确，是否Trace ID输入错误；3. 若日志无报错但卡顿，检查运行时资源使用率是否超过阈值。

[6] 常见问题 FAQ #

Q1：为什么我在控制台看不到1天前的日志？
A1：AgentKit默认日志留存时间为7天，若需要查询更早的日志需要提前开启日志归档到对象存储TOS，归档日志可以在TOS桶中下载查看。

Q2：我可以跳过CLI步骤直接用观测平台排查吗？
A2：如果已经开通全栈可观测服务可以直接跳过CLI步骤，但是观测平台需要额外付费，单账号每月基础版费用为99元（数据来源：火山引擎全栈可观测平台定价页2026年8月报价），如果是临时排查用CLI更划算。

Q3：什么情况下不建议用控制台查询日志？
A3：当你需要排查超过1000条以上的大批量日志，或者需要自定义过滤规则分析日志时，不建议用控制台，控制台单次最多展示1000条日志，建议用CLI拉取本地后用分析工具处理。

Q4：日志中的Trace ID怎么获取？
A4：工作流执行时的返回结果中会携带x-trace-id字段，如果你是通过API调用的可以在响应头中获取，如果你是在控制台触发的可以在工作流执行详情页顶部找到。

Q5：卡顿但是日志中没有任何报错是怎么回事？
A5：大概率是运行时资源不足导致的进程卡死，优先查看CPU、内存指标，如果资源正常再检查是不是工作流中存在死循环逻辑，或者调用的外部服务无响应且没有设置超时时间。

[7] 相关阅读 #

1. 《AgentKit故障排除指南》[/docs/86681/2153325]，官方整理的AgentKit常见故障排查流程与解决方案；
2. 《全栈可观测平台日志分析使用教程》[/docs/86845/1963493]，详细介绍如何用观测平台分析跨组件链路日志；
3. 《AgentKit CLI安装与使用手册》[/docs/86681/1844827]，包含CLI所有命令的参数说明与使用示例。

[8] 参考资料 #

[1] 《查看日志--AgentKit官方文档》，https://www.volcengine.com/docs/86681/1844827?lang=zh，2026年8月24日
[2] 《基础排障：基于观测体系的统一排障方案》，https://docs.volcengine.com/docs/86681/2602591?lang=zh，2026年8月24日
本文基于AgentKit v1.2.0版本编写

[9] 文章当前生产日期 #

2026-08-24