agentkit故障需分层排查：先查实时错误流定位异常点，再解析jsonl会话日志确认失败步骤，接着下钻工具调用日志分析api响应，最后检查systemd系统日志排除环境问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当AgentKit智能体在运行中突然报错、任务卡死或响应空白，却只显示模糊提示（如“execution failed”“timeout”或无任何输出）时，问题往往藏在底层日志里——这些日志未被CLI默认展示，也未聚合到Web控制台，必须主动切入文件系统与结构化流中提取。
确认运行时实例与日志根路径
AgentKit的日志按运行时（Runtime）隔离存储，不同Runtime绝不会混写。先明确当前出问题的Runtime名称：
执行 agentkit list-runtimes，找到状态为 【running】 且 【last_active】 时间接近故障发生时刻的那行，记下其 RUNTIME_ID（如 rt-7f3a9b21）。
该Runtime的所有原始日志均落盘在：~/.agentkit/runtimes/<runtime_id>/logs/</runtime_id>。进入此目录前，请确保你拥有读取权限；若提示 Permission denied，需先运行 sudo chown -R $USER:$USER ~/.agentkit，否则后续所有日志读取将失败。
抓取实时错误流（适用于刚发生的异常）
此方法捕获正在输出的ERROR/WARNING堆栈，对复现型问题最有效，能绕过日志轮转丢失风险。
执行：agentkit logs --runtime <runtime_id> --follow</runtime_id>
立即复现触发报错的操作（例如发送一条测试消息、调用一个工具）。观察终端滚动内容，重点盯住以 ERROR、CRITICAL 或 Traceback 开头的行——它们一定紧邻真实失败点，而非事后包装的提示语。
若看到 Connection refused by gateway，说明AgentKit Runtime无法连接上游模型网关，需检查 agentkit.yaml 中 gateway_url 配置是否可达；若出现 tool not found: xyz，则问题出在技能注册阶段，不是运行时本身故障。
解析结构化会话日志（定位具体哪一步崩了）
AgentKit将每次用户会话完整记录为独立JSONL文件（每行一个JSON对象），路径为：~/.agentkit/runtimes/<runtime_id>/sessions/</runtime_id>。每个文件名含时间戳与session_id，如 20260819_154221_abcd1234.jsonl。
方法一：快速筛选最近一次失败会话
执行：ls -t ~/.agentkit/runtimes/<runtime_id>/sessions/*.jsonl | head -n 1 | xargs -I{} jq -r 'select(.status == "failed") | .session_id, .step_id, .error_message' {}</runtime_id>
方法二：人工逐行检查事件链完整性
用 tail -n 50 <session_file></session_file> 查看最后50行，确认是否存在「有 action 无 result」或「step_id 跳跃」现象。例如上一行是 "step_id": 3, "action": "search_web"，下一行直接变成 "step_id": 5, "status": "failed"，说明第4步在执行中崩溃且未落盘，此时必须回查实时日志或系统级日志。
下钻到工具层原始调用日志
多数报错根源在工具（Tool）执行环节，而工具日志单独存于：~/.agentkit/runtimes/<runtime_id>/tools/</runtime_id>。每个子目录对应一个已注册工具，如 web_search/、db_query/。
第一步：定位报错工具名
从上一步的会话JSONL中提取 tool_name 字段值（如 web_search）。
第二步：查看该工具最近10次调用摘要
执行：tail -n 10 ~/.agentkit/runtimes/<runtime_id>/tools/<tool_name>/invocations.log</tool_name></runtime_id>
第三步：提取最后一次失败调用的完整上下文
执行：grep -B 5 -A 10 "status=failed" ~/.agentkit/runtimes/<runtime_id>/tools/<tool_name>/invocations.log | tail -n 20</tool_name></runtime_id>
注意：此处的 invocations.log 是纯文本格式，含HTTP状态码、工具参数哈希、外部服务返回的原始body片段。若看到 status_code=401，说明API密钥失效；若为 status_code=429，则需检查配额或限流策略。
检查系统级日志排除环境干扰
当上述路径均未发现明显错误，但AgentKit进程反复重启或CPU飙升，问题可能来自OS层。
执行：journalctl -u agentkit-runtime@<runtime_id> -n 50 --no-pager</runtime_id>
这条命令调取systemd托管的Runtime服务日志，可暴露：OOM killed process（内存溢出）、Failed to start process: exec format error（二进制不兼容）、Cannot assign requested address（端口被占）等底层信号。若输出中出现 fork: Cannot allocate memory，请立刻检查 ulimit -v 和宿主机剩余内存，不要继续排查应用层日志。
