AgentKit智能体运行报错如何定位底层日志

AgentKit故障需分层排查：先查实时错误流定位异常点，再解析JSONL会话日志确认失败步骤，接着下钻工具调用日志分析API响应，最后检查systemd系统日志排除环境问题。

当AgentKit智能体在运行中突然报错、任务卡死或响应空白，却只显示模糊提示（如“execution failed”“timeout”或无任何输出）时，问题往往藏在底层日志里——这些日志未被CLI默认展示，也未聚合到Web控制台，必须主动切入文件系统与结构化流中提取。

确认运行时实例与日志根路径

AgentKit的日志按运行时（Runtime）隔离存储，不同Runtime绝不会混写。先明确当前出问题的Runtime名称：

执行 agentkit list-runtimes，找到状态为

该Runtime的所有原始日志都会存放在：~/.agentkit/runtimes//logs/这个位置。在进入这个目录之前，得先确保你有读取权限哦；要是出现了 Permission denied 的提示，那就得先运行 sudo chown -R $USER:$USER ~/.agentkit 这条命令，不然的话，后续所有日志读取都会失败的。

抓取实时错误流（适用于刚发生的异常）

此方法捕获正在输出的ERROR/WARNING堆栈，对复现型问题最有效，能绕过日志轮转丢失风险。

执行：agentkit logs --runtime --follow

立即复现触发报错的操作（例如发送一条测试消息、调用一个工具）。观察终端滚动内容，重点盯住以 ERROR、CRITICAL 或 Traceback 开头的行——它们一定紧邻真实失败点，而非事后包装的提示语。

若看到 Connection refused by gateway，说明AgentKit Runtime无法连接上游模型网关，需检查 agentkit.yaml 中 gateway_url 配置是否可达；若出现 tool not found: xyz，则问题出在技能注册阶段，不是运行时本身故障。

解析结构化会话日志（定位具体哪一步崩了）

AgentKit会把每次用户会话完整记录为独立的JSONL文件（每个JSON对象占一行），其路径为：~/.agentkit/runtimes//sessions/。每个文件名包含时间戳和session_id，比如 20260819_154221_abcd1234.jsonl。

方法一：快速筛选最近一次失败会话

执行：ls -t ~/.agentkit/runtimes//sessions/*.jsonl | head -n 1 | xargs -I{} jq -r 'select(.status == "failed") | .session_id, .step_id, .error_message' {}

方法二：人工逐行检查事件链完整性

用 tail -n 50 查看最后50行，确认是否存在「有 action 无 result」或「step_id 跳跃」现象。例如上一行是 "step_id": 3, "action": "search_web"，下一行直接变成 "step_id": 5, "status": "failed"，说明第4步在执行中崩溃且未落盘，此时必须回查实时日志或系统级日志。

下钻到工具层原始调用日志

多数报错根源在工具（Tool）执行环节，而工具日志单独存于：~/.agentkit/runtimes//tools/。每个子目录对应一个已注册工具，如 web_search/、db_query/。

第一步：定位报错工具名

从上一步的会话JSONL中提取 tool_name 字段值（如 web_search）。

第二步：查看该工具最近10次调用摘要

执行：tail -n 10 ~/.agentkit/runtimes//tools//invocations.log

第三步：提取最后一次失败调用的完整上下文

执行：grep -B 5 -A 10 "status=failed" ~/.agentkit/runtimes//tools//invocations.log | tail -n 20

注意：此处的 invocations.log 是纯文本格式，含HTTP状态码、工具参数哈希、外部服务返回的原始body片段。若看到 status_code=401，说明API密钥失效；若为 status_code=429，则需检查配额或限流策略。

检查系统级日志排除环境干扰

当上述路径均未发现明显错误，但AgentKit进程反复重启或CPU飙升，问题可能来自OS层。

执行：journalctl -u agentkit-runtime@ -n 50 --no-pager

这条命令调取systemd托管的Runtime服务日志，可暴露：OOM killed process（内存溢出）、Failed to start process: exec format error（二进制不兼容）、Cannot assign requested address（端口被占）等底层信号。若输出中间出现 fork: Cannot allocate memory，请立刻检查 ulimit -v 和宿主机剩余内存，不要继续排查应用层日志。