三项都过才算修好：火山引擎把 Agent 故障收成回归

线上 Agent 报错，不能从所有监控页挨个点。火山引擎 AgentKit 的基础排障，把观测收成一条固定顺序：先备故障样本，再按五个阶段缩小范围，最后用同类请求验证。下面只记排查约束，不记某一次故障的修复结果。

开工前要备齐的样本

链路类问题必须有 trace id。它可以从应用观测的链路详情、日志字段、Runtime / Tool / MCP 调用详情，以及后端服务日志里复制。异常时间窗口是必备项，用来限定监控曲线、日志和告警的查询范围。资源名称和类型也是必备项，对象包括 Runtime、Tool、Memory、Knowledge、MCP 服务、MCP 工具集。错误码和错误信息建议必备，用来区分鉴权失败、工具入参异常、检索失败、模型超时和后端报错。变更之后才出现的问题，变更记录必备，用来判断是不是发布、改配置、扩缩容、镜像更新、索引调整或权限变更带出来的。

监控不是全部默认开着。Runtime 监控要在创建智能运行时或创建之后开启观测服务。Tool 监控开启观测服务后，才能看沙箱模板的指标和日志。表里没列出的监控项，文档写明默认开启。日志要单独开，开了才能查 Runtime、Tool、MCP 服务的错误码、入参出参和请求上下文。

五个阶段，先看变更点

建议顺序是：发现异常，初步定位，逐层排查，根因分析，解决与验证。

发现异常要核实它是不是真发生了，并分清是资源层、应用链路层还是外部依赖。输出是时间窗口和影响范围。初步定位要判断这是单次请求，还是持续的指标问题，手里要有 trace id、错误码、资源名称和变更时间。逐层排查按执行链路缩小范围。根因分析把失败节点、依赖返回和变更记录对上，写出原因和处置。解决与验证看错误率、平均延时、请求分布、实例数量，以及重新打进去的验证请求。输出要有验证结论和复盘材料。

如果异常紧跟发布、改配置、扩缩容或认证变更，先围绕变更时间回看曲线和日志。文档把变更时间当成识别起点和影响范围的线索。

发现阶段有四个入口，按现象选，不要所有页面都扫一遍。告警适合指标越界、突发异常和已知风险。基础设施类告警，例如 CPU、内存、实例异常、网络带宽，先进基础监控。智能体业务类告警，例如请求错误率、请求延时、链路中断、关键步骤耗时，进应用观测，用 TraceID 或 RequestID 找失败节点。基础监控看的是采集周期里的请求次数、请求分布、运行中实例数、平均延迟和总错误率。文档举例的周期是 1 小时，总错误率也可以按 1 天这类统计周期看，这是举例，不是写成唯一窗口。应用观测看链路是否中断、埋点是否缺失。日志用 trace id 把单次请求的现场滤出来。

组件按固定层级往下收

根因还不清楚时，顺序是 Runtime，然后 Tool，然后 Memory / Knowledge，然后 MCP 服务，然后 MCP 工具集。先确认主执行链路稳不稳，再查依赖。

Runtime 看请求量、时延分布、失败率和实例水位，先看出向带宽、CPU、内存，以及发布前后的指标变化。Tool 看成功率、时延和资源，对照入参、出参、耗时和错误信息，区分工具自身、运行环境，还是外部依赖。Memory 按写入、召回、检索三段看。召回为空时，要同时核对有没有写进去、召回条件对不对、这条请求有没有真的调到 Memory。MCP 服务确认请求进没进来，失败在认证、协议转换、运行环境还是后端。MCP 工具集看索引、检索条件、标签、工具集版本，以及工具描述和语义检索结果。

五类故障怎么对

文档归纳了五类。

认证失败：请求还没进 Runtime，就返回权限错误，常见 HTTP 状态码是 401 MissingAuthenticationToken。原因在接入鉴权，不是 Agent 业务、Tool 或 Memory 内部。要核对 Authorization 是否存在，Token 是否过期、被截断或夹了空格和换行。签名模式还要核对 AppKey、AppSecret、算法、时间戳和参数组装。再用响应里的 request_id 查接入网关日志，不要去查 Agent Runtime 日志。

Tool 失败：执行到工具节点才报错，请求分布里非 2xx 占比升高，或平均延迟明显抬升。入参可能和 Schema 不符，模型生成的工具 JSON 可能被截断。文档写了一条资源线：CPU 使用率长期高于 80%，或内存接近上限，就扩容或改工具逻辑。修好后用相同入参打回归请求，看该 tool name 的错误率是否回落。

模型失败：节点没有有效响应，或内容被截断，Runtime 里 5xx 或超时占比升高。超时的话，把 Runtime 的调用 timeout 调到不低于模型 P99 响应时长的 1.5 倍，并一起看上游客户端的超时。内容被截断就查 max_tokens 是否盖住预期长度，必要时调低 temperature 和 top_p。

检索失败：Memory 或 Knowledge 没命中，或检索节点直接报错，总错误率会波动。要确认 Memory 状态为可用，并用创建事件看写入是否完成。同一条 Query 如果离线检索能命中、线上不能，就查线上的 top_k、相似度阈值、租户或标签过滤。写入和检索用的 Embedding 模型和版本必须一致。

后端失败：常见状态码是 500、502、503、504。用 trace id 把子调用链展开，先分清是网关侧还是后端侧。网关侧看 MCP 的 CPU、内存、实例数和健康检查。还要对照接口 Schema。报错窗口里请求量骤增，要看是不是触发限流。MCP 工具集则看语义检索请求次数和语义检索工具索引数，确认索引和路由。

怎样才算修好

处置和验证要配成对，避免「已经处理但没有验证」。验证通过至少要同时满足三条：核心监控回到正常区间；同类请求再跑能过，且不再复现；对应日志和链路里不再出现同类型异常。只恢复其中一项，文档认为通常不够。

监控上要看请求次数、请求分布、平均延时、总错误率、实例数量和资源水位，观察窗口内不能持续抖动。日志按 trace id、错误码和时间窗口复核。链路要看 Runtime、Tool、Memory、MCP 和后端节点是否恢复成功，关键节点耗时回到预期。验证请求用修复前失败的那一类重新调用，必要时覆盖多个入参样本。

变更引起的，优先回滚或改回配置。负载引起的，先把实例拉回健康再看容量。依赖引起的，先恢复依赖，再看主链路。埋点或字段口径引起的，先改接入，再对指标定义。还没定位清楚的，保留 trace id、错误信息和时间窗口。

这一页没有给出某次故障的错误率、恢复时长，也没有对照「修复前 / 修复后」的曲线。80% 的 CPU、1.5 倍 P99、401 和 5xx 状态码、三条验证标准，以及五层排查顺序，是排障约束，不是线上效果。

字节，火山引擎 AgentKit 文档，基础排障：基于观测体系的统一排障方案，2026-08-11，https://docs.volcengine.com/docs/agentkit/basic-troubleshooting-unified-troubleshooting-scheme-based-on-observation-system