AgentKit故障排查：日志配置全流程与排坑指南

[1] 一句话结论 #

本指南将带你完成AgentKit日志配置，掌握常见故障快速排查方法。

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

适用场景

1. 部署在火山引擎的AgentKit实例，日均调用量1000次以上、需7*24小时稳定性保障的生产场景
2. 开发调试阶段需要定位Agent流程异常、工具调用失败问题的开发场景
3. 接入多工具链、有复杂编排逻辑的企业级智能体排障场景

不适用场景

1. 完全本地部署、未接入火山引擎AgentKit管控台的智能体，建议直接查看自研框架的日志文档
2. 仅需要简单对话、无工具调用/编排逻辑的轻量Chat场景，建议直接使用豆包API自带的日志功能，无需配置AgentKit日志
3. 日志存储需求超过单实例100G/天的超大规模场景，建议搭配火山引擎日志服务SLS进行独立存储

[3] 前置准备 #

• Python 3.9+ 或 Node.js 16+，对应AgentKit SDK v1.2.0及以上版本【数据来源：火山引擎AgentKit官方文档2026版】
• 已完成火山引擎账号实名认证，且拥有AgentKit FullAccess权限
• 已创建至少1个可正常运行的AgentKit实例
• 预计操作耗时：15分钟

[4] 分步实现 #

步骤1：配置日志输出规则

步骤说明：首先需要在AgentKit管控台配置日志的输出等级、存储周期、输出字段，这一步是后续排查的基础，跳过会导致关键错误信息丢失。

import agentkit
# 初始化鉴权信息
ak = "YOUR_ACCESS_KEY"
sk = "YOUR_SECRET_KEY"
agent_id = "YOUR_AGENT_ID"
# 配置日志等级：可选DEBUG/INFO/WARN/ERROR
agentkit.config.set_log_level("INFO")
# 配置是否输出工具调用、用户输入等敏感字段，生产环境建议关闭
agentkit.config.set_log_sensitive_field(False)

预期结果：管控台日志配置页显示「配置生效」，SDK初始化日志输出[INFO] log config initialized success。

⚠️ 常见错误：生产环境日志等级设为DEBUG导致存储费用超支
原因：根据我们的经验，DEBUG等级的日志量可达INFO等级的10倍以上，我们服务的某零售客户曾因为误开DEBUG日志导致当月存储费用超支3倍。
解决方法：生产环境默认设为INFO等级，排查问题时临时开启DEBUG，排查完成后立即回切。

步骤2：集成日志采集链路

步骤说明：如果需要把AgentKit日志同步到自有观测平台，需要配置日志采集出口，目前支持HTTP推送、SLS同步两种方式，跳过这一步的话只能在AgentKit管控台查看最近7天的日志。

# 配置日志同步到火山引擎SLS
agentkit.config.set_log_export(
    export_type = "sls",
    endpoint = "cn-beijing-intranet.log.volcengineapi.com",
    project = "YOUR_SLS_PROJECT",
    logstore = "YOUR_SLS_LOGSTORE"
)

预期结果：配置后5分钟内，可在对应SLS Logstore中看到AgentKit的日志流入。

⚠️ 常见错误：SLS权限配置错误导致日志同步失败
原因：使用的AccessKey没有SLS的写权限，或者Endpoint配置错误（比如选了外网Endpoint但实例在VPC内）。
解决方法：先调用SLS的PutLogs接口自测权限，VPC内实例必须使用VPC类型的Endpoint。

步骤3：配置故障告警规则

步骤说明：针对常见异常场景配置告警，比如ERROR日志占比超过1%、工具调用成功率低于95%，可以第一时间收到故障通知，跳过这一步会导致故障发现不及时。
操作路径：AgentKit管控台→告警配置→新建告警规则，选择对应指标阈值，设置通知渠道（飞书/短信/邮件）。
预期结果：告警规则状态显示「已启用」，点击测试告警可以正常收到通知。

步骤4：配置日志检索索引

步骤说明：给常用的检索字段（比如agent_id、request_id、tool_name）配置索引，提升检索速度，在排查百万级日志时可以把检索耗时从10秒降到1秒以内【数据来源：火山引擎日志服务SLS官方性能测试报告2025】。
操作路径：AgentKit管控台→日志检索→索引配置，将上述字段设为可检索。
预期结果：索引配置生效后，按request_id检索日志耗时≤2秒。

[5] 实际验证 #

测试用例：调用你的Agent接口，传入触发工具调用的请求，比如「查询今天北京的天气」，记录返回的request_id。
验证成功标志：接口返回HTTP 200状态码，天气结果正常；在日志检索页输入对应request_id，可以看到完整调用链路：用户输入→意图识别→工具调用请求→工具返回结果→Agent生成回答，日志中无ERROR级别内容。
验证失败常见排查路径：

1. 看不到对应日志：检查日志等级是否设为了WARN/ERROR，INFO级别的调用日志未输出，将等级调回INFO即可
2. 日志缺少工具调用字段：检查是否开启了敏感字段屏蔽，关闭后即可看到完整字段
3. 日志未同步到SLS：按照步骤2的踩坑提示检查SLS权限和Endpoint配置

[6] 常见问题 FAQ #

Q1：AgentKit管控台的日志最多可以保留多久？
A：管控台默认免费保留7天日志，如果需要更长时间可以配置导出到SLS，SLS最多支持保留3年，按实际存储量收费。

Q2：什么情况下不建议开启DEBUG级日志？
A：生产环境日常运行时不建议开启，DEBUG级日志会包含用户输入、工具返回的所有内容，不仅会增加存储成本，还可能导致敏感信息泄露，只有排查特定问题时临时开启即可。

Q3：我可以跳过日志导出配置，直接在管控台排查问题吗？
A：如果你的日志量不大、保留时间需求在7天以内，完全可以只使用管控台日志，不需要额外配置导出，还可以节省SLS的费用。

Q4：日志中出现「tool call timeout」错误怎么处理？
A：首先检查工具的超时配置，AgentKit默认工具调用超时是30秒，如果你的工具响应时间较长，可以在工具配置页把超时时间调到最多120秒，如果还是超时需要检查工具本身的可用性。

Q5：AgentKit日志和业务日志怎么打通？
A：可以在调用AgentKit SDK时传入自定义的trace_id，日志中会自动携带该trace_id，你可以用trace_id把AgentKit日志和业务系统的日志关联起来排查全链路问题。

[7] 相关阅读 #

1. 《AgentKit快速入门指南》，[/docs/agentkit/quickstart]，零基础快速搭建第一个可运行的智能体
2. 《AgentKit自定义工具接入全流程教程》，[/docs/agentkit/tool-integration]，教你快速接入自定义工具到AgentKit
3. 《火山引擎SLS日志服务使用手册》，[/docs/sls/guide]，了解如何配置SLS实现日志长期存储与分析

[8] 参考资料 #

[1] 火山引擎AgentKit官方文档，https://www.volcengine.com/docs/6458/1270103，2026-08-20
[2] 火山引擎日志服务SLS官方性能报告，https://www.volcengine.com/docs/6470/107524，2026-07-15
本文基于火山引擎AgentKit v1.2.0版本编写

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

2026-08-24