AgentKit工具调用日志：4种查看路径及配置排查指南

[1] 一句话结论 #

本指南将详解火山引擎AgentKit工具调用日志的4种查看方式、配置方法及常见问题排查方案。

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

适用场景

1. 本地开发调试阶段，需要快速定位工具调用参数错误、返回值异常的场景；
2. 线上智能体运行异常，需要追溯工具调用链路、入参出参及耗时的场景；
3. 需要统计工具调用成功率、Token消耗、平均延迟等运营数据的场景。

不适用场景

1. 如果你需要查看非火山引擎AgentKit的通用Agent日志，建议直接参考对应开发框架的官方日志文档；
2. 如果你的场景是需要存储超过90天的归档日志，建议参考火山引擎日志服务CLS的归档方案，AgentKit默认日志仅保留7天；
3. 如果你只需要查看智能体对话内容日志，不需要工具调用细节，直接使用控制台对话历史页即可，无需查看工具调用日志。

[3] 前置准备 #

• 已开通火山引擎AgentKit服务，拥有对应实例的查看权限（权限角色为AgentKit管理员或开发者）；
• 本地开发环境已安装AgentKit CLI v1.2.0及以上版本；
• 已安装Python 3.8+环境（用于运行测试用例验证日志）；
• 预计操作耗时15分钟。

[4] 分步实现 #

步骤1：开启本地日志功能

步骤说明：本地调试阶段默认不会输出工具调用的详细日志，需要先开启日志开关，跳过这一步会看不到入参、返回值、错误栈等关键调试信息。
代码/命令：

# 开启控制台实时日志输出
export AGENTKIT_LOG_CONSOLE=true
# 如需开启本地文件日志，额外执行以下命令
export AGENTKIT_LOG_FILE=true

预期结果：执行命令无报错，后续运行Agent相关命令时，终端会实时输出INFO级别的运行日志，包含工具调用的关键信息。

⚠️ 常见错误：执行export命令后运行Agent依然看不到日志
原因：环境变量仅在当前终端会话生效，新开终端窗口需要重新执行，否则配置不生效。
解决方法：如果需要永久开启日志，执行echo 'export AGENTKIT_LOG_CONSOLE=true' >> ~/.bashrc && source ~/.bashrc配置全局环境变量。

步骤2：查看本地工具调用日志

步骤说明：本地运行的Agent工具调用日志会存储在本地指定路径，无需访问控制台即可离线排查问题，适合开发阶段快速定位问题。
操作说明：全局运行日志默认存放在./.agentkit/logs/agentkit-YYYYMMDD.log路径，单工具的调用详情日志存放在~/.agentkit/runtimes/<runtime_id>/tools/<tool_name>/invocations.log路径，其中<runtime_id>为智能体运行实例ID，<tool_name>为调用的工具名称。
预期结果：打开invocations.log文件，每行日志包含时间戳、调用ID、工具名称、入参、返回结果、耗时等字段，样例如下：

2026-08-24 19:00:00 [INFO] tool_call_id:call_123456, tool:weather_search, params:{"city":"北京","date":"2026-08-24"}, result:{"temperature":"25-32℃","weather":"晴"}, cost:128ms

步骤3：控制台网页端查看日志

步骤说明：线上部署的Agent实例可以直接在火山引擎控制台查看日志，无需登录服务器，适合快速排查线上单条调用异常问题。
操作说明：登录火山引擎AgentKit控制台，进入目标智能体的详情页，点击「运行日志」页签，筛选日志类型为「工具调用」即可查看所有工具的调用日志；也可以进入单个工具的实例详情页，查看该工具的所有历史调用记录。
预期结果：支持按时间范围、工具名称、调用状态（成功/失败）筛选，列表展示每条调用的入参、出参、耗时、状态码等信息。

⚠️ 常见错误：控制台日志只显示最近7天的记录，找不到更早的日志
原因：控制台默认日志存储周期为7天，超过周期的日志会自动清理（数据来源：火山引擎AgentKit官方日志文档v1.2）。
解决方法：如果需要存储更长时间的日志，提前在全栈观测平台配置日志转储到火山引擎CLS，最长可存储3年。

步骤4：全栈观测平台查看全链路日志

步骤说明：需要排查跨模块调用问题、统计全链路Token消耗、查看调用拓扑时使用，能关联智能体、工具、大模型的全链路日志，适合复杂问题排查和运营数据分析。
操作说明：进入火山引擎AI应用监控平台，选择对应的AgentKit应用，进入「会话分析」页面，输入会话ID即可检索完整的工具调用链路。
预期结果：能看到完整的调用拓扑图，每个节点的耗时、错误信息、Token消耗，根据我们在某电商智能客服客户的生产环境实测，工具调用的平均延迟为150ms左右。

[5] 实际验证 #

测试用例：本地调用AgentKit内置的天气查询工具，输入查询内容为「北京今天天气」，触发工具调用。
验证成功标志：1. 本地invocations.log中生成对应调用记录，入参为{"city":"北京","date":"2026-08-24"}，返回结果包含气温和天气信息；2. 控制台「运行日志」页签能查询到同一条调用记录，状态为成功；3. 全栈观测平台可以通过tool_call_id检索到对应的链路信息，HTTP状态码为200。
验证失败常见原因及排查方法：1. 本地日志路径不存在：检查是否开启了文件日志，环境变量是否配置正确，路径是否有写入权限；2. 控制台看不到日志：检查账号是否有对应实例的查看权限，是否选择了正确的地域和项目；3. 观测平台无数据：检查Agent配置中是否开启了全栈观测数据上报开关，默认关闭需要手动开启。

[6] 常见问题 FAQ #

1. 问题：工具调用返回报错，我应该优先看哪种日志？
   答案：优先看本地invocations.log或者控制台工具详情页的日志，里面会记录完整的入参和返回的错误信息，大部分参数错误、权限问题、第三方接口调用错误都能直接定位。
2. 问题：我可以修改本地日志的存储路径吗？
   答案：可以，通过export AGENTKIT_LOG_PATH=/your/custom/path环境变量指定自定义存储路径，注意路径需要有当前用户的写入权限。
3. 问题：什么情况下不建议使用控制台查看日志？
   答案：当你需要批量导出日志、自定义分析日志内容时，不建议用控制台，控制台仅支持基础筛选和单条查看，建议直接使用全栈观测平台的日志分析功能，支持SQL查询和批量导出。
4. 问题：日志里的tool_call_id有什么用？
   答案：可以用这个ID在全栈观测平台检索对应的完整调用链路，排查跨模块的超时、错误问题，也可以用来和大模型的调用日志做关联分析。
5. 问题：我可以关闭工具调用日志吗？
   答案：可以，设置AGENTKIT_LOG_ENABLE=false即可，但不建议线上环境关闭，出现问题后无法追溯调用链路，会大幅提升排查难度。

[7] 相关阅读 #

• 《AgentKit日志系统官方文档》[/docs/86681/2549659]，详细介绍日志的所有配置参数、字段说明和存储规则；
• 《全栈可观测平台会话分析使用指南》[/docs/86845/1963490]，教你如何配置日志转储、链路追踪和自定义数据分析；
• 《AgentKit常见错误排查手册》[/blog/agentkit-error-troubleshooting]，汇总了开发过程中常见的100+错误及对应解决方案；
• 《AgentKit CLI使用教程》[/docs/86681/2137711]，详细讲解CLI的所有命令、参数配置和使用技巧。

[8] 参考资料 #

[1] 火山引擎AgentKit日志系统官方文档，https://www.volcengine.com/docs/86681/2549659，2026-08-24
[2] 火山引擎全栈可观测平台会话分析文档，https://www.volcengine.com/docs/86845/1963490，2026-08-24
[3] 本文基于火山引擎AgentKit v1.2版本编写

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

2026-08-24