文章类型技术长文 所属专栏Agent 观测 预计阅读57 分钟 文档状态已发布

第 4 篇：Agent 生产故障诊断——网络恢复、循环检测、回放与 SLO

从生产故障分类、网络与流式恢复、循环和振荡检测，到 Replay、故障注入、SLI/SLO 与事故复盘，构建 Agent 诊断闭环。

开始阅读全文11466 字 · 57 分钟 查看系列目录Agent 观测

作者Jupiter 发布日期2026/08/05 最近更新2026/08/05 正文规模11466 字

关键词 Agent可观测性故障诊断SLOReplay

栏目 AgentObservability；专栏 Agent 观测；标签 Agent、可观测性、故障诊断、SLO、Replay

文章目标#

这一篇把 Agent 的故障诊断、恢复正确性、性能成本与生产 SLO 放在同一条链路中讨论。

原因很直接：在 Agent 系统里，“失败”“变慢”“变贵”经常不是三个相互独立的问题，而是同一个异常的不同表现。例如：

模型请求收到 429；
Agent 立即重试；
多个子 Agent 同时触发重试；
请求量和 Token 用量被放大；
任务延迟进入长尾；
工具调用因为超时被重复执行；
最终任务虽然成功，却产生了重复副作用和异常成本。

如果把网络故障、循环检测、成本分析和 SLO 分成互不相干的专题，就很容易只看到局部：

网络层只看到连接断开；
Agent Loop 只看到步骤变多；
成本系统只看到 Token 暴涨；
业务系统只看到重复创建了资源；
告警系统最后只发出一个“任务失败率升高”。

真正的生产诊断必须把这些证据重新串成一条因果链。

本文使用一个 Coding Agent 任务作为贯穿案例：

用户要求 Agent 修复订单模块中的折扣计算 Bug，只允许修改 orders/ 和对应测试目录，不得修改支付模块；Agent 需要读取仓库、调用检索和文件工具、修改代码、运行测试，并返回最终结果。

任务运行时可能发生：

模型 API 建连失败或流式中断；
429、5xx 与 Retry-After；
Tool Call 已生成但客户端未确认；
工具已经执行，Tool Result 却丢失；
Agent 重复搜索、重复编辑或在两个工具间振荡；
Context Compaction 丢失禁止修改支付模块的约束；
子 Agent 已完成任务但主 Agent 无法汇合；
最终回复声称成功，环境测试实际仍然失败。

本文的核心目标是建立一套能够回答以下问题的生产方法：

1
发生了什么
2
→ 最早的异常在哪里
3
→ 异常如何传播
4
→ 系统是否安全恢复
5
→ 恢复花费了多少时间和成本
6
→ 用户实际受到了什么影响
7
→ 应该如何告警
8
→ 如何把事故沉淀为后续回归评测样本

生产故障诊断的三个基本原则#

原则一：任务 Outcome 高于接口状态#

一次模型请求返回 HTTP 200，只说明该请求被成功处理；它不能证明：

Agent 理解了任务；
Tool Call 正确；
工具真实执行成功；
环境达到目标状态；
没有产生额外副作用。

生产健康度必须以经过环境验证的任务 Outcome为核心，而不是以模型请求成功率代替任务成功率。

原则二：最终错误不等于最初根因#

最终错误可能是：

1
Task Timeout

但真正的起点可能是：

1
索引版本落后
2
→ 召回错误文件
3
→ 模型选择错误工具
4
→ 权限被拒绝
5
→ Agent 反复改写计划
6
→ 超过任务截止时间

根因分析应寻找“最早打破系统不变量的事件”，而不是只统计最后一个 Error Span。

原则三：恢复成功不等于从未失败#

一次逻辑模型或工具操作经历：

1
Attempt 1：429
2
Attempt 2：Stream Disconnect
3
Attempt 3：Success

最终可以标记为成功，但前两次失败、退避等待、额外费用和恢复路径必须完整保留。否则系统会把“健康请求”和“经过两次失败才恢复的请求”混为一谈。

AWS Builders’ Library 将重试描述为一种会额外消耗下游资源的机制，并强调重试、Backoff、Jitter 与幂等性必须共同设计；当故障来自过载时，激进重试甚至会扩大事故。[1]

1. Agent 故障分类#

Agent 生产故障分类图谱

Agent 故障分类不能只沿 HTTP 状态码组织，因为一次任务同时包含模型、工具、编排、状态、环境和人类决策。

更适合生产诊断的分类方式是：

故障域	典型现象	最关键证据	默认恢复方向
模型决策	选错动作、误解约束	Model Span、上下文清单、候选动作	重规划、模型降级、人工确认
工具	选错工具、参数非法、执行失败	Tool Discovery、Schema、Arguments、Attempt	参数修复、替代工具、幂等重试
编排与状态	Loop、状态丢失、重复步骤	Step、State Snapshot、Checkpoint	从安全 Checkpoint 恢复
检索与记忆	错召回、旧记忆污染	Candidate、Filter、Rerank、Injection	重新检索、过滤、禁用记忆
网络与外部服务	429、5xx、断流、超时	HTTP/MCP Span、Retry-After、序列号	Backoff、Fallback、状态查询
权限与安全	Approval 拒绝、策略阻断	Policy、Actor、Decision、Risk	降低权限、替代路径、人工接管
环境结果	测试未过、重复副作用、状态不一致	Before/After/Diff、Outcome Verifier	回滚、补偿、人工修复

这套分类的目的不是为每个故障贴一个唯一标签。复杂事故往往跨越多个故障域。更重要的是确定：

Trigger：什么事件触发了事故；
Root Cause：哪个设计或状态使事故成为可能；
Contributing Factors：哪些因素扩大了影响；
Detection Gap：为什么系统没有更早发现；
Recovery Gap：为什么恢复路径没有更快或更安全。

1.1 模型决策错误#

模型决策错误是指模型 API 正常完成，但模型生成的计划、回答或 Tool Call 不符合任务目标。

常见类型：

1
goal_misunderstanding
2
constraint_omission
3
wrong_tool_selection
4
premature_completion
5
unsupported_claim
6
unsafe_action_proposal
7
stale_plan_reuse

必须区分“决策错误”和“生成错误”#

以下是决策错误：

1
模型选择了 shell.run，而正确工具应为 read_file。

以下更接近生成或协议错误：

1
模型选择了正确工具，但 Tool Arguments JSON 无法解析。

两者修复方向不同：

决策错误需要检查上下文、工具描述、模型版本和规划策略；
协议错误需要检查 Structured Output、Schema、Parser 和 Repair。

模型决策错误的诊断字段#

1
model_provider
2
request_model
3
response_model
4
prompt_version
5
system_prompt_hash
6
tool_schema_set_hash
7
context_manifest_ref
8
normalized_stop_reason
9
selected_tool_name
10
selected_tool_call_id
11
task_contract_hash
12
outcome_verification_status

不要把隐藏思维文本作为必需证据#

生产系统应优先记录：

模型真实可见输入；
候选工具和工具描述；
结构化 Tool Call；
任务 Contract；
后续动作；
环境结果。

这些证据足以支持大部分根因分析。隐藏 Chain-of-Thought 不应成为可观测性的必要依赖。

1.2 工具选择和参数错误#

工具故障至少包含四个阶段：

1
Tool Discovery
2
→ Tool Selection
3
→ Argument Validation
4
→ Tool Execution

常见故障：

1
正确工具未被发现
2
正确工具被策略过滤
3
同名工具产生歧义
4
工具描述与实际能力不一致
5
参数字段缺失
6
参数类型错误
7
参数通过 Schema 但违反业务规则
8
审批后参数被错误修改
9
工具实现与 Schema 版本不匹配

参数合法不等于操作安全#

例如：

1
{
2
  "path": "payments/service.py",
3
  "patch": "..."
4
}

可能完全符合 edit_file 的 JSON Schema，但违反任务 Contract：

1
不得修改支付模块。

因此参数校验至少需要三层：

语法解析；
Schema 校验；
任务约束、权限和环境规则校验。

1.3 编排与状态错误#

编排故障发生在 Agent Loop、状态机、Checkpoint 或恢复逻辑中。

常见类型：

1
step_repeated
2
invalid_transition
3
stale_state_read
4
lost_pending_tool_call
5
duplicate_resume
6
checkpoint_conflict
7
wrong_parent_child_relation
8
fan_in_never_completed
9
budget_not_propagated
10
cancel_not_propagated

一个典型状态错误#

1
Step 12：edit_file 已成功执行
2
Step 13：Checkpoint 写入失败
3
进程重启
4
Step 12 从旧 Checkpoint 再次执行
5
同一补丁被应用第二次

这里模型和工具本身都没有错误，根因是：

Tool Side Effect 与 Checkpoint 提交之间缺乏原子性；
恢复时没有执行结果 Ledger；
工具调用没有 Idempotency Key。

编排状态的关键对象#

1
run_id
2
step_id
3
operation_id
4
attempt_id
5
checkpoint_id
6
state_version
7
pending_tool_call_ids
8
completed_side_effect_ids
9
resume_id
10
cancellation_token_id

1.4 检索和记忆错误#

检索与记忆故障经常表现为模型错误，但根因在模型调用之前。

检索故障#

1
query_rewrite_lost_constraint
2
stale_index
3
low_recall
4
irrelevant_high_rank
5
acl_overfilter
6
rerank_regression
7
selected_chunk_truncated
8
unsupported_citation

记忆故障#

1
stale_memory
2
cross_task_memory
3
conflicting_memory
4
incorrect_summary
5
scope_leakage
6
overdominant_memory
7
deleted_memory_reappeared

诊断必须覆盖完整漏斗#

1
原始 Query
2
→ Rewrite
3
→ Candidate
4
→ Filter
5
→ Rerank
6
→ Selected Chunk
7
→ Context Injection
8
→ Model Decision

以及：

1
Memory Recall
2
→ Candidate
3
→ Filter
4
→ Injection
5
→ Downstream Action

如果只保存“最终注入了哪些文本”，就无法判断正确内容是没有召回，还是召回后被错误过滤。

1.5 网络与外部服务错误#

这一类包括：

1
dns_failure
2
tcp_connect_failure
3
tls_failure
4
proxy_failure
5
authentication_failure
6
connect_timeout
7
first_event_timeout
8
stream_idle_timeout
9
connection_reset
10
429_rate_limit
11
5xx_provider_error
12
mcp_disconnect
13
tool_service_timeout
14
delivery_failure

必须记录故障发生的阶段。

错误写法：

1
network_error

更有用的写法：

1
{
2
  "error_type": "connect_timeout",
3
  "network_stage": "tls_handshake",
4
  "server_address": "api.provider.example",
5
  "attempt_number": 2,
6
  "timeout_ms": 5000
7
}

AWS 的生产实践强调远程调用需要分别考虑连接和请求超时，因为某些超时设置并不自动覆盖 DNS、TLS 等所有阶段。[1]

1.6 权限和安全阻断#

权限阻断不一定是故障。它可能是系统正确执行安全策略的结果。

应区分：

1
expected_policy_denial
2
unexpected_policy_denial
3
approval_rejected
4
approval_expired
5
credential_missing
6
credential_expired
7
sandbox_denied
8
network_egress_denied
9
unsafe_action_blocked

正常阻断#

Agent 尝试直接推送主分支，策略正常拒绝：

1
decision = denied
2
policy_outcome = expected

异常阻断#

Agent 只读文件，却因错误权限配置被拒绝：

1
decision = denied
2
policy_outcome = misconfigured

两者不能都计入 Tool Failure Rate。

审批拒绝后的恢复能力#

一个成熟 Agent 不应在拒绝后立刻失败，而应尝试：

生成 Patch 而不是直接写入；
创建草稿而不是提交；
请求较低权限工具；
缩小作用域后重新审批；
Handoff 给人工。

1.7 环境结果错误#

环境结果错误是指 Agent 的最终声明与真实环境状态不一致，或者环境虽然达到目标，但伴随不可接受副作用。

常见类型：

1
tests_still_failing
2
wrong_files_modified
3
unexpected_database_write
4
duplicate_resource_created
5
partial_deployment
6
stale_read_after_write
7
rollback_failed
8
final_answer_mismatch

环境结果必须独立验证#

Coding Agent 的成功条件不应是：

1
模型输出：“修复完成。”

而应是：

1
指定测试通过
2
允许范围内的文件发生预期 Diff
3
禁止目录没有变化
4
构建成功
5
没有新增失败测试

推荐对象：

1
state_before_ref
2
state_after_ref
3
state_diff_ref
4
outcome_verifier_version
5
outcome_status
6
unexpected_side_effect_count
7
rollback_status

2. 网络和流式故障#

网络与流式故障恢复时序图

网络故障最危险的地方，不是请求失败，而是系统无法判断请求或副作用到底执行到了哪一步。

一条模型流式请求可以划分为：

1
DNS
2
→ TCP
3
→ TLS
4
→ Proxy / Gateway
5
→ Authentication
6
→ Request Sent
7
→ Response Headers
8
→ First Event
9
→ Streaming Events
10
→ Finish Event
11
→ Usage Event
12
→ Connection Close

不同阶段的失败，安全恢复方式不同。

2.1 连接建立失败#

连接建立失败至少要细分为：

1
dns_resolution_failed
2
tcp_connect_refused
3
tcp_connect_timeout
4
tls_handshake_failed
5
certificate_validation_failed
6
proxy_authentication_failed
7
gateway_route_failed
8
provider_authentication_failed

关键字段#

1
network_stage
2
server_address
3
server_port
4
proxy_address
5
dns_duration_ms
6
tcp_connect_duration_ms
7
tls_handshake_duration_ms
8
request_attempt_id
9
error_type
10
error_code
11
retryable

为什么要拆分阶段#

如果所有错误都表现为 connect timeout，你无法区分：

DNS Server 故障；
企业代理不可达；
新证书未被信任；
Provider 区域 Endpoint 不可达；
连接池耗尽；
请求根本没有离开本机。

安全性#

建连失败且没有发送请求体时，通常没有远端副作用，重试相对安全。

但客户端必须能够证明：

1
request_bytes_sent = 0

如果 TCP 已建立、请求已部分发送，却只收到本地超时，就进入“不确定执行状态”，不能简单视为完全未发送。

2.2 Stream 中途断开#

Stream Disconnect 必须记录断开时的协议进度。

至少区分：

1
before_first_event
2
during_text_delta
3
during_tool_name
4
during_tool_arguments
5
after_complete_tool_call
6
after_finish_reason
7
before_usage

断开时的状态快照#

1
{
2
  "stream_state": "during_tool_arguments",
3
  "received_event_count": 47,
4
  "last_event_sequence": 46,
5
  "partial_text_bytes": 1820,
6
  "partial_tool_call_ids": ["call_017"],
7
  "complete_tool_call_ids": [],
8
  "finish_event_received": false,
9
  "usage_received": false
10
}

处理原则#

只有部分文本#

可以：

丢弃部分输出并重新请求；
保留部分输出用于调试；
使用序列号避免 UI 重复渲染。

不要把部分文本直接当作完整答案。

Tool Arguments 未完成#

不应执行工具。
半截 JSON 不能被当作可恢复的业务参数。

Tool Call 已完整生成但流未完成#

此时需要回答：

Tool Call 是否已经本地执行；
Provider 是否还会继续输出其他 Tool Call；
当前协议是否支持从 Response ID 继续；
重新请求是否会再次生成相同 Tool Call。

必须使用 tool_call_id、operation_id 和执行 Ledger 防止重复副作用。

2.3 响应完成但 Usage 丢失#

有些流式协议在最后才返回 Token Usage。可能出现：

1
模型内容和 Finish Event 已收到
2
→ 网络在 Usage Event 前断开

此时：

任务内容可能已经完整；
模型调用不一定失败；
费用数据却不完整。

错误做法：

1
按字符数估算后覆盖 Provider Usage。

正确做法：

1
response_status = completed
2
usage_status = missing
3
usage_source = unavailable

同时保存：

1
provider_request_id
2
response_id
3
finish_reason
4
received_input_token_estimate
5
received_output_token_estimate
6
billing_reconciliation_status

如果 Provider 后续提供 Usage API、账单日志或请求查询接口，可以异步补齐。补齐过程必须保留来源：

1
usage_source = provider_billing_reconciliation

不能把估算值伪装成 Provider 精确值。

OpenTelemetry 的 GenAI 语义约定定义了模型操作时长和 Token Usage 等指标；实践中应同时记录 Usage 是否完整，避免把缺失值当作零。[2]

2.4 429 限流#

RFC 6585 将 429 定义为“在给定时间内请求过多”，响应可以带 Retry-After 提示等待时间；RFC 9110 规定 Retry-After 可以是绝对 HTTP 日期或等待秒数。[3][4]

Agent 系统不能把所有 429 统一处理为：

1
sleep(1)
2
retry()

429 可能代表不同额度#

1
requests_per_minute
2
tokens_per_minute
3
concurrent_requests
4
concurrent_streams
5
daily_quota
6
organization_budget
7
product_plan_limit
8
tool_api_quota

应记录#

1
rate_limit_scope
2
rate_limit_dimension
3
retry_after_ms
4
limit_value
5
remaining_value
6
reset_at
7
provider_request_id
8
retry_budget_remaining

恢复策略#

优先级：

尊重 Provider 返回的 Retry-After；
没有明确指示时使用指数 Backoff 和 Jitter；
限制最大 Attempt；
使用共享 Retry Budget；
降低并发或子 Agent Fan-out；
必要时切换模型或 Provider；
不要让每个子 Agent 独立无限重试。

AWS 指出，同一时刻同步重试会重新制造流量尖峰，因此需要 Jitter；同时应限制重试层级和重试总量，避免调用链中每一层都成倍重试。[1]

2.5 5xx 服务异常#

常见 5xx：

1
500 Internal Server Error
2
502 Bad Gateway
3
503 Service Unavailable
4
504 Gateway Timeout

但状态码本身并不能完全说明请求是否产生了处理结果。

关键问题#

1
请求是否到达 Provider
2
Provider 是否开始处理
3
是否已经生成部分响应
4
是否已经执行服务端副作用
5
Gateway 是否只是丢失了响应

对纯模型生成请求，通常没有外部业务副作用，但仍可能产生：

计费；
Provider 侧 Response 对象；
部分输出；
服务端 Tool Execution；
会话状态推进。

对外部工具服务，5xx 更不能直接等同于“没有执行”。

2.6 请求是否可以安全重试#

安全重试不是一个 HTTP 状态码表，而是一个“当前副作用状态”判断。

决策矩阵#

当前阶段	已知副作用	是否可直接重试	推荐动作
DNS/TCP 建连前失败	无	通常可以	Backoff + Jitter
请求未发送	无	可以	新 Attempt
模型流未返回任何内容	通常无业务副作用	多数可以	重试模型操作
收到部分文本	无工具副作用	条件可重试	丢弃或去重部分输出
Tool Call 参数不完整	无	不执行工具	重新获取完整 Tool Call
Tool Call 完整但未执行	无	不必重跑工具	从本地 Tool Call 继续
工具已执行、Ack 丢失	不确定	不可盲目重试	查询状态或使用幂等键
最终消息发送状态未知	不确定	不可直接重发全文	查询 Delivery Ledger
不可逆工具已成功	已发生	不可重放	继续后续状态或补偿

2.7 幂等键与重复副作用#

幂等的目标不是“请求只能发送一次”，而是：

相同逻辑操作即使发生多次物理请求，也只产生一次预期业务结果。

AWS EC2 使用 Client Token 提供请求幂等性；Stripe 也通过 Idempotency-Key 将多次请求识别为同一逻辑操作。[5][6]

三类 ID 必须分开#

1
operation_id     一次逻辑业务操作
2
attempt_id       一次物理执行尝试
3
idempotency_key  远端去重键

示例：

1
{
2
  "operation_id": "create_pr_repo42_issue17",
3
  "attempt_id": "att_003",
4
  "idempotency_key": "repo42:issue17:create-pr:v1",
5
  "request_payload_hash": "sha256:..."
6
}

幂等 Ledger#

服务端或本地应保存：

1
idempotency_key
2
request_hash
3
status
4
result_ref
5
created_at
6
expires_at

状态：

1
pending
2
succeeded
3
failed_retryable
4
failed_final
5
unknown

同一 Key 不应允许不同参数#

如果同一个 Idempotency Key 收到不同 Payload，应拒绝：

1
idempotency_conflict

否则 Key 不再代表同一个逻辑操作。

重复副作用的防线#

Idempotency Key；
业务唯一约束；
Compare-and-set / ETag；
执行结果查询；
Transactional Outbox；
Tool Execution Ledger；
补偿操作；
人工确认。

3. Agent 特有异常#

循环、振荡与过早结束检测

传统服务通常一次请求执行固定代码路径；Agent 会动态选择下一步，因此会出现一类独特的“控制流失控”问题。

3.1 无限循环#

无限循环不是简单的 while true，而是 Agent 在有限状态集合中不断运行，却没有朝任务目标推进。

不能只依赖最大步数#

max_steps=20 只是最后保险。更早的检测应使用 Progress Signal。

推荐构造：

1
progress_signature =
2
hash(
3
    task_contract,
4
    unresolved_requirements,
5
    environment_revision,
6
    pending_tool_calls,
7
    last_verified_outcome
8
)

如果多个 Step 中：

1
progress_signature 不变
2
且成本、时间持续增长

就可能进入无进展循环。

停止策略#

1
重新规划
2
切换工具
3
清空非必要记忆
4
降低上下文
5
请求人工
6
安全停止

3.2 工具振荡#

工具振荡表示 Agent 在两个或多个工具之间来回切换：

1
search_code
2
→ read_file
3
→ search_code
4
→ read_file
5
→ ...

或：

1
edit_file
2
→ run_tests
3
→ revert_file
4
→ edit_file
5
→ ...

检测方式#

对工具序列做窗口检测：

1
A B A B A B
2
A B C A B C

并结合参数和结果 Hash：

1
tool_name
2
normalized_arguments_hash
3
result_hash
4
environment_revision

仅工具名重复不一定是振荡。例如读取不同文件是合理行为。

振荡判定条件#

1
周期模式重复
2
结果没有新增信息
3
环境没有净变化
4
任务未接近完成

3.3 重复调用相同工具#

重复调用比振荡更简单：

1
run_tests(args_hash=H)
2
run_tests(args_hash=H)
3
run_tests(args_hash=H)

Tool Fingerprint#

1
fingerprint =
2
hash(
3
    tool_name,
4
    normalized_arguments,
5
    environment_revision,
6
    relevant_context_version
7
)

如果 Fingerprint 相同，Tool Result 也相同，就应：

复用缓存；
阻止重复调用；
要求模型解释新增信息需求；
触发重新规划。

合理重复的例外#

环境 Revision 已变化：

1
edit_file
2
→ run_tests
3
→ edit_file
4
→ run_tests

虽然参数相同，但执行环境不同，不能判为无意义重复。

3.4 重复修改环境#

重复修改的风险远高于重复读取。

常见问题：

1
同一补丁应用两次
2
同一数据库记录更新两次
3
重复发送邮件
4
重复创建 Pull Request
5
重复部署

检测字段#

1
mutation_operation_id
2
target_resource_id
3
state_before_version
4
state_after_version
5
diff_hash
6
idempotency_key
7
rollback_point_id

防止 Lost Update#

使用：

1
If-Match / ETag
2
Compare-and-set
3
版本号
4
事务
5
唯一约束

如果 Agent 基于旧状态修改环境，应返回冲突，而不是覆盖新状态。

3.5 过早结束#

模型的正常 Stop Reason 不等于任务完成。

Anthropic 官方文档也明确区分 Stop Reason 与 API 错误：Stop Reason 表示一次成功响应为什么停止，不能作为业务任务成功的唯一判断。[7]

常见过早结束：

1
模型输出最终文本，但必要工具未调用
2
模型达到 max_tokens 后被误当成完成
3
审批被拒绝后没有替代路径
4
子 Agent 部分完成，主 Agent 直接汇总
5
测试未执行就声称修复完成

任务完成判断#

1
task_contract.required_conditions
2
task_contract.forbidden_conditions
3
outcome_verifier
4
environment_state

例如：

1
completed = (
2
    tests_passed
3
    and modified_paths <= allowed_paths
4
    and not unexpected_side_effects
5
)

3.6 Context Compaction 后目标丢失#

Context Compaction 会重新表达历史状态，因此必须验证硬约束。

压缩前后的不变量#

1
goal
2
must_conditions
3
must_not_conditions
4
allowed_scope
5
pending_actions
6
completed_side_effects

本文案例必须保留：

1
修复折扣计算
2
不得修改支付模块
3
相关测试必须通过

漂移检测#

1
goal_hash_before
2
goal_hash_after
3
hard_constraint_recall
4
forbidden_constraint_recall
5
scope_diff
6
pending_action_diff

普通语义相似度高，不代表硬约束完整。

3.7 子 Agent 无法汇合#

多 Agent 扇出后，主 Agent需要等待结果并做 Merge。

常见故障：

1
child_timeout
2
child_cancelled
3
child_result_schema_invalid
4
merge_barrier_never_released
5
conflicting_results
6
missing_child_result
7
duplicate_child_result
8
parent_cancel_not_propagated

Fan-in 状态#

1
fanout_id
2
expected_child_ids
3
completed_child_ids
4
failed_child_ids
5
cancelled_child_ids
6
merge_deadline
7
merge_policy

Merge Policy#

1
all_required
2
quorum
3
first_success
4
best_score
5
manager_selected
6
partial_allowed

如果策略要求所有子任务完成，而一个子 Agent 永远不返回，主任务会永久阻塞。必须有：

Deadline；
Partial Result 策略；
取消传播；
失败替代路径；
人工接管。

4. 根因分析方法#

Google SRE 的 Incident Response 方法强调，在活跃事故中先评估影响并缓解用户痛苦，之后再进行根因分析；不要为了立即找出完美根因而延迟止血。[8]

Agent 事故响应可以采用：

1
Impact
2
→ Mitigation
3
→ Root Cause
4
→ Permanent Fix
5
→ Postmortem

4.1 最终报错不等于最初根因#

考虑下面的时间线：

1
10:00:00 代码索引仍停留在旧 Commit
2
10:00:03 Query Rewrite 删除了模块约束
3
10:00:05 RAG 召回旧文件
4
10:00:12 模型选择 edit_file
5
10:00:18 权限系统拒绝修改支付模块
6
10:00:25 Agent 重新搜索
7
10:01:40 多次重试后达到 Task Deadline
8
10:01:41 最终错误：task_timeout

task_timeout 是终止原因，不是根因。

更早的异常可能是：

1
stale_index

或：

1
query_rewrite_lost_constraint

Root Cause、Trigger 与 Contributing Factor#

1
Root Cause:
2
索引更新流程没有将仓库 Revision 纳入检索数据版本。
3

4
Trigger:
5
本次任务在新 Commit 合并后立即运行。
6

7
Contributing Factors:
8
Query Rewrite 丢失模块约束；
9
Agent 缺少重复搜索检测；
10
权限拒绝后仍采用同一检索路径。

4.2 首个异常事件#

“首个 Error Span”不一定是首个异常事件。

例如检索返回 HTTP 200，但 Candidate 中没有正确文档。它没有技术错误，却已经打破了：

1
目标文件必须存在于候选集

因此首个异常事件应定义为：

执行链中第一个偏离预期不变量、健康基线或成功 Trace 的节点。

不变量类型#

1
任务约束不变量
2
状态版本不变量
3
工具参数不变量
4
候选覆盖不变量
5
副作用不变量
6
预算不变量
7
安全不变量

RCA 记录#

1
first_anomaly_event_id
2
first_anomaly_type
3
expected_state
4
observed_state
5
detection_method
6
confidence

4.3 Attempt Tree#

重试必须建模成树，而不是覆盖同一条记录。

1
logical_operation: model_request op_009
2
├── attempt_1
3
│   └── 429
4
├── backoff_1
5
├── attempt_2
6
│   └── stream_disconnect
7
├── fallback_decision
8
└── attempt_3
9
    └── success

每个 Attempt 记录：

1
attempt_id
2
attempt_number
3
provider
4
model
5
start_time
6
end_time
7
error_type
8
retry_after_ms
9
bytes_sent
10
events_received
11
remote_outcome
12
cost

外层逻辑 Operation 记录：

1
final_status
2
attempt_count
3
recovery_status
4
total_duration
5
total_cost

为什么是 Tree#

Fallback 可能产生分支：

1
primary_provider
2
├── retry primary
3
└── fallback provider
4
    ├── regional endpoint A
5
    └── regional endpoint B

复杂恢复路径不是简单列表。

4.4 Success Trace 与 Failure Trace 对比#

单条 Failure Trace 经常难以判断什么是异常。更有效的方法是与同类 Success Trace 对齐。

不按时间戳直接对齐#

同类任务的具体时间和 Step 数可能不同。应使用语义键：

1
step_type
2
tool_name
3
operation_name
4
task_phase
5
artifact_type
6
outcome_checkpoint

对比维度#

1
模型和 Prompt 版本
2
上下文 Token 组成
3
Tool Discovery Snapshot
4
检索候选和 Rank
5
工具序列
6
重试次数
7
审批等待
8
环境 Diff
9
Stop Reason
10
成本
11
关键路径

Trace Diff 示例#

1
成功组：
2
search_code → read_file → edit_file → run_tests
3

4
失败组：
5
search_code → search_code → read_file → edit_file
6
→ run_tests → edit_file → run_tests → timeout

差异提示：

1
重复搜索
2
编辑—测试振荡
3
缺少进展检测

4.5 关键路径和等待时间分析#

并行 Agent 的总延迟不是所有 Span Duration 之和，而是最长依赖路径。

1
critical_path =
2
max(sum(duration of causally dependent spans))

时间分类#

1
active_model_time
2
active_tool_time
3
retrieval_time
4
queue_wait_time
5
rate_limit_backoff_time
6
human_approval_wait_time
7
subagent_wait_time
8
scheduler_idle_time

为什么需要分类#

任务耗时 180 秒，其中：

1
模型生成：22 秒
2
工具执行：18 秒
3
429 Backoff：64 秒
4
等待人工审批：70 秒
5
其他：6 秒

此时优化模型速度几乎没有意义。

5. Replay 与复现#

Replay 与故障注入矩阵

Replay 的目的不是“重新跑一次看看”，而是控制变量，逐层隔离故障来源。

可以把 Replay 分成四层：

层级	固定内容	重新执行内容	主要用途
Prompt Replay	输入和配置	模型、工具、环境	观察整体可复现性
固定模型响应	模型输出	编排、工具、状态	隔离模型随机性
Tool Result Replay	工具输出	模型和编排	隔离外部工具
环境快照 Replay	初始环境	完整 Agent	最接近真实复现

LangGraph 的 Checkpoint 与 Time Travel 支持从历史 Checkpoint Replay 或 Fork；Checkpoint 前的节点可以复用已保存结果，Checkpoint 后的 LLM、API 和 Interrupt 会重新执行，因此结果仍可能变化。[10][11]

5.1 Prompt Replay#

Prompt Replay 固定：

1
用户输入
2
System Prompt
3
Prompt Template
4
Tool Definitions
5
模型参数
6
上下文清单

重新调用模型和工具。

适合回答#

1
问题是否稳定复现
2
不同模型 Revision 是否回归
3
Prompt 版本是否改善
4
Temperature 是否导致波动

局限#

即使参数完全相同，模型也可能因为：

随机采样；
Provider 实现变化；
负载路由；
安全策略；
缓存；
后端 Revision；

生成不同结果。

所以 Prompt Replay 更适合多 Trial 统计，不适合要求字节级一致。

5.2 固定模型响应 Replay#

把生产 Trace 中的模型响应保存成 Stub：

1
Model Call 1 → 固定 Response 1
2
Model Call 2 → 固定 Response 2

然后重新运行：

Tool Call Parser；
Approval；
Tool Runtime；
State Update；
Compaction；
Outcome Verification。

适合回答#

1
错误来自模型输出，还是来自 Agent Runtime
2
Tool Arguments 是否被解析错误
3
取消和超时是否正确传播
4
Checkpoint 是否重复执行工具

注意#

模型响应中可能含敏感内容，应使用受控 Artifact、脱敏和短期保留策略。

5.3 Tool Result Replay#

固定外部工具结果：

1
code_search → recorded result
2
read_file → recorded result
3
run_tests → recorded result
4
MCP resource read → recorded result

重新运行模型决策和 Agent Loop。

适合回答#

1
模型是否误读工具结果
2
Tool Result 截断是否造成错误
3
RAG / MCP 内容变化是否影响决策
4
同一证据下模型是否稳定

Result Replay 必须带版本#

1
tool_name
2
tool_schema_version
3
arguments_hash
4
result_hash
5
environment_revision
6
recorded_at

否则旧结果可能与当前工具语义不兼容。

5.4 环境快照 Replay#

环境快照 Replay 固定：

1
仓库 Commit
2
未提交工作区
3
容器镜像
4
依赖锁文件
5
数据库快照
6
浏览器状态
7
MCP Server Revision
8
Tool List Snapshot
9
时间和随机源

然后重新运行整个 Agent。

适合回答#

1
事故能否在同一初始状态复现
2
环境差异是否为根因
3
修复是否阻止同类事故
4
故障注入下恢复是否正确

成本#

这是最昂贵的 Replay，需要：

可恢复 Sandbox；
Artifact Store；
数据脱敏；
外部服务 Mock；
时间和网络控制；
资源隔离。

5.5 为什么 Agent 很难完全确定性回放#

Agent 不是纯函数，非确定性来源很多。

模型非确定性#

1
采样
2
并行推理
3
模型 Revision
4
安全策略
5
Provider 路由

环境非确定性#

1
文件被其他进程修改
2
数据库状态变化
3
网页内容变化
4
第三方 API 返回变化
5
当前时间
6
随机数

并发非确定性#

1
子 Agent 完成顺序
2
并行工具结果顺序
3
队列调度
4
取消传播

运行时非确定性#

1
缓存命中
2
超时
3
重试
4
动态 Tool Discovery
5
Compaction
6
Human-in-the-loop

可复现 Manifest#

因此，生产 Replay 应保存：

1
agent_version
2
model_request_and_response_revision
3
prompt_hash
4
tool_schema_set_hash
5
environment_snapshot_id
6
retrieval_index_version
7
memory_snapshot_id
8
checkpoint_id
9
random_seed_if_supported
10
clock_mode
11
network_fixture_version

LangGraph 文档也提醒，Replay 模式下在受控 Task 外执行时间、随机数或网络调用会产生不同结果，从而改变控制流。[12]

6. 故障注入#

故障注入不是随意“把服务关掉”，而是验证一个明确的稳态假设：

1
当依赖 X 在阶段 Y 失败时，
2
系统应该执行恢复动作 Z，
3
且不得产生副作用 W。

每次实验至少定义：

1
steady_state_hypothesis
2
injection_point
3
fault_type
4
blast_radius
5
expected_detection
6
expected_recovery
7
forbidden_outcome
8
rollback_plan
9
success_criteria

6.1 429 和 5xx#

注入位置#

1
模型 Provider
2
企业 LLM Gateway
3
MCP Server
4
外部工具 API

注入场景#

1
第一次返回 429，带 Retry-After
2
连续三次 429
3
503 后恢复
4
502 与连接重置交替
5
响应已处理但 Gateway 返回 504

验证#

是否尊重 Retry-After；
是否使用 Jitter；
Retry Budget 是否生效；
是否出现重试风暴；
Fallback 是否记录；
最终成功是否保留中间失败；
成本是否被正确计算。

6.2 网络断流#

注入点必须覆盖不同窗口：

1
首事件之前
2
文本输出中途
3
Tool Name 中途
4
Tool Arguments 中途
5
完整 Tool Call 之后
6
Finish Event 之后
7
Usage Event 之前

禁止结果#

1
执行半截 Tool Arguments
2
重复渲染文本
3
重复执行完整 Tool Call
4
将部分响应标记为完成
5
Usage 缺失被写成 0

6.3 Tool Timeout#

至少测试：

1
工具尚未开始就超时
2
只读工具执行中超时
3
写工具在副作用前超时
4
写工具在副作用后、Ack 前超时
5
子进程没有响应取消

验证#

Timeout 是否传递到子进程；
是否杀死孤儿进程；
是否知道副作用是否发生；
是否查询执行状态；
是否使用幂等键；
是否从正确 Checkpoint 恢复。

6.4 MCP 中断#

测试：

1
Server Discovery 失败
2
Tool List 获取失败
3
Capability Snapshot 过期
4
Tool Call 过程中断
5
Resource Read 中断
6
重连后工具列表变化
7
Trace Context 未传播

验证#

是否刷新 Capability；
是否保留原 Request ID；
是否把旧 Tool Call 错发给新 Schema；
Client 与 Server Trace 是否仍能关联；
重连后是否重复执行写操作。

6.5 权限拒绝#

注入：

1
文件写权限拒绝
2
网络出站拒绝
3
高风险工具审批拒绝
4
凭证过期
5
Sandbox Policy 拒绝

验证#

拒绝是否被识别为策略结果而非网络错误；
Agent 是否降低权限；
是否生成替代方案；
是否请求人工；
是否停止重复申请同一权限。

6.6 错误工具结果#

注入类型：

1
malformed_result
2
stale_result
3
partial_result
4
contradictory_result
5
empty_result
6
oversized_result
7
poisoned_instruction
8
wrong_resource_version

验证#

Parser 是否拒绝非法结构；
结果是否被标记来源；
是否发生 Prompt Injection；
Agent 是否进行交叉验证；
是否把错误结果写入长期记忆；
Outcome Verifier 是否能阻止错误完成。

6.7 Context 截断#

测试：

1
删除最后一条用户约束
2
截断关键 Tool Result
3
移除未完成步骤
4
压缩掉禁止修改目录
5
丢失子 Agent Pending State

验证#

1
hard_constraint_recall
2
pending_action_consistency
3
goal_drift_score
4
duplicate_side_effect_count
5
outcome_verification

最有价值的故障注入，不只是确认系统“会报错”，而是确认系统以正确方式失败。

7. Agent 核心 SLI#

Agent 核心 SLI、SLO 与事故复盘闭环

Google SRE 将 SLI 定义为对用户关心的服务行为进行量化的指标，SLO 是该指标的目标值或目标范围；SLO 应从用户真正关心的结果出发，而不是从最容易采集的指标出发。[13]

Agent 的 SLI 也必须遵循这个原则。

一个完整 SLI Contract 应明确：

1
名称
2
用户含义
3
测量单位
4
事件口径
5
分子
6
分母
7
排除项
8
数据源
9
聚合窗口
10
分组维度
11
数据延迟
12
缺失数据处理
13
目标值

7.1 Task Success Rate#

定义#

1
Task Success Rate =
2
经过环境验证的成功任务数
3
/
4
符合统计条件的已结束任务数

公式：

\mathrm{TSR} = \frac{N_{\mathrm{verified\ success}}} {N_{\mathrm{eligible\ completed}}}

分母必须明确#

可选择纳入：

1
success
2
failed
3
partial
4
timeout
5
budget_exhausted

通常单独统计：

1
user_cancelled
2
invalid_user_request
3
planned_maintenance

不能在故障期间临时把失败任务从分母移除。

成功必须经过验证#

1
agent_claimed_success != verified_success

建议同时保留：

1
claimed_success_rate
2
verified_success_rate
3
claim_verification_gap

7.2 Recovery Rate#

定义#

1
Recovery Rate =
2
发生可恢复故障后最终成功的任务数
3
/
4
发生可恢复故障的任务数

\mathrm{RecoveryRate} = \frac{N_{\mathrm{faulted\ and\ recovered}}} {N_{\mathrm{recoverable\ faulted}}}

可恢复故障必须事先定义#

例如：

1
单次 429
2
单次 Provider 5xx
3
只读 Tool Timeout
4
首次 Stream Disconnect
5
临时 MCP 断开

不可把不可逆副作用事故归入同一分母。

同时记录：

1
median_attempts_to_recover
2
p95_recovery_latency
3
recovery_cost_multiplier
4
recovery_side_effect_rate

7.3 End-to-end Latency#

定义#

从用户任务被接受，到：

最终 Outcome 被验证；
或任务失败、取消、转人工。

而不是只到模型输出完成。

1
E2E =
2
queue
3
+ context
4
+ model
5
+ retrieval
6
+ tool
7
+ backoff
8
+ approval
9
+ subagent
10
+ outcome verification

需要分位数#

并按任务类型、成功状态和版本分组。

Wait 与 Active 分开#

1
active_compute_ms
2
external_wait_ms
3
human_wait_ms
4
backoff_ms
5
queue_ms

7.4 Tool Failure Rate#

建议同时定义两个指标。

逻辑工具失败率#

\mathrm{LogicalToolFailureRate} = \frac{N_{\mathrm{tool\ operations\ final\ failed}}} {N_{\mathrm{tool\ operations}}}

Attempt 错误率#

\mathrm{AttemptErrorRate} = \frac{N_{\mathrm{failed\ attempts}}} {N_{\mathrm{all\ attempts}}}

一次工具调用经过两次失败后成功：

1
逻辑失败率：成功
2
Attempt 错误率：2 / 3

两者同时需要，才能看见隐藏的依赖退化。

7.5 Human Escalation Rate#

\mathrm{HumanEscalationRate} = \frac{N_{\mathrm{tasks\ escalated\ to\ human}}} {N_{\mathrm{eligible\ tasks}}}

应区分：

1
policy_required
2
user_requested
3
low_confidence
4
recovery_failed
5
unsafe_action
6
unexpected_manual_takeover

高风险任务适当升级是正常行为，不能把所有人工升级都视为负面。

更有价值的是：

1
avoidable_escalation_rate
2
human_wait_latency
3
post_escalation_success_rate

7.6 Cost per Successful Task#

定义#

\mathrm{CostPerSuccessfulTask} = \frac{\mathrm{Total\ Agent\ Cost}} {N_{\mathrm{verified\ success}}}

总成本必须包括：

1
成功任务模型成本
2
失败任务模型成本
3
Retry 和 Fallback 成本
4
工具和第三方 API 成本
5
浏览器与 Sandbox 成本
6
子 Agent 成本
7
评测与验证成本

不能只统计成功任务自身的调用费用，否则会隐藏失败和重试造成的浪费。

同时记录#

1
cost_per_attempt
2
cost_per_task
3
cost_per_verified_success
4
wasted_work_cost
5
retry_cost_amplification

OpenTelemetry 的 GenAI 观测提供模型操作时长与 Token Usage 等基础信号，可以作为成本模型的底层输入，但业务侧仍需要补充单价、缓存、工具和 Sandbox 成本。[2]

7.7 Unsafe Side-effect Rate#

定义#

可以按任务统计：

\mathrm{UnsafeSideEffectRate} = \frac{N_{\mathrm{tasks\ with\ unsafe\ mutation}}} {N_{\mathrm{tasks\ performing\ mutation}}}

也可以按操作统计：

\mathrm{UnsafeMutationRate} = \frac{N_{\mathrm{unsafe\ mutation\ operations}}} {N_{\mathrm{all\ mutation\ operations}}}

Unsafe 的定义必须规则化#

1
修改禁止资源
2
重复不可逆操作
3
未经审批执行
4
越权访问
5
意外数据删除
6
错误收件人发送
7
跨租户副作用
8
无法回滚的未知状态

严重安全副作用不应只用平均率表达，还应单独计数和立即告警。

8. SLO 与告警#

SLO 不应覆盖所有可观测指标。Google SRE 建议保留少量真正代表用户体验的 SLO，并使用其他诊断指标解释为什么 SLO 正在被消耗。[9][13]

Agent 可以设置如下 SLO 组合：

1
Verified Task Success SLO
2
End-to-end Latency SLO
3
Unsafe Side-effect SLO
4
Recovery SLO

具体目标必须基于业务风险和任务类型确定，下面的数值仅用于说明方法。

8.1 失败率告警#

假设：

1
30 天 Task Success SLO = 99%
2
允许失败率 = 1%

定义 Error Budget Burn Rate：

\mathrm{BurnRate} = \frac{\mathrm{ObservedBadRate}} {\mathrm{AllowedBadRate}}

如果当前失败率为 5%：

\mathrm{BurnRate} = 5

表示以当前速度消耗预算，是长期允许速度的 5 倍。

多窗口告警#

建议同时看：

1
短窗口：发现快速事故
2
长窗口：避免瞬时噪声

例如：

1
5 分钟 + 1 小时
2
30 分钟 + 6 小时

Page 条件应满足：

用户 Outcome 明显受损；
Error Budget 快速消耗；
告警可执行；
有对应 Runbook。

低速、长期轻微回归更适合 Ticket，而不是半夜 Page。

8.2 重试放大告警#

Retry Amplification#

\mathrm{RetryAmplification} = \frac{N_{\mathrm{physical\ attempts}}} {N_{\mathrm{logical\ operations}}}

正常值接近 1。

还可以定义额外请求率：

\mathrm{ExtraAttemptRate} = \frac{N_{\mathrm{attempts}} - N_{\mathrm{operations}}} {N_{\mathrm{operations}}}

告警必须结合绝对量#

当只有两个请求时，Amplification 为 2 不一定值得 Page。应同时要求：

1
attempt_volume > minimum
2
and retry_amplification > threshold
3
and downstream_error_rate elevated

关联指标#

1
429_rate
2
5xx_rate
3
backoff_wait_ms
4
retry_budget_exhaustion
5
fallback_rate
6
recovery_rate

8.3 Token 和费用异常#

不要只对总 Token 告警，因为业务流量增长也会提高总量。

更合理的基线：

1
input_tokens_per_task
2
output_tokens_per_task
3
tokens_per_verified_success
4
cost_per_verified_success
5
retry_cost_multiplier
6
cache_read_ratio

按以下维度切分：

1
task_type
2
agent_version
3
model
4
prompt_version
5
tool_schema_version
6
outcome_status

常见异常模式#

1
Prompt 版本上线后输入 Token p95 上升
2
Tool Result 未裁剪导致上下文膨胀
3
Loop 造成模型调用次数增加
4
Fallback 到昂贵模型
5
Cache Hit Ratio 降低
6
失败任务持续消耗预算

8.4 长链路和循环任务#

建议告警指标：

1
step_count
2
model_call_count
3
tool_call_count
4
no_progress_duration
5
cycle_detection_score
6
task_age
7
pending_subagent_count
8
approval_wait_age

两级处理#

自动终止或转人工#

1
hard_step_limit
2
hard_cost_limit
3
hard_deadline

预警和诊断#

1
p99 step count
2
no-progress > threshold
3
same tool fingerprint repeated
4
ABAB tool cycle

不要只设置全局 Step Limit。不同任务复杂度差异很大，应按 Task Type 设置预算。

8.5 新模型或 Prompt 版本回归#

所有 Trace 和 Metric 必须带低基数版本标签：

1
agent_version
2
model_route
3
response_model
4
prompt_version
5
tool_schema_set_version
6
retrieval_index_version

发布策略#

1
离线回归集
2
→ Shadow
3
→ 小流量 Canary
4
→ 分阶段放量
5
→ 全量

比较指标#

1
Verified Task Success
2
Unsafe Side-effect
3
E2E Latency
4
Cost per Successful Task
5
Recovery Rate
6
Tool Argument Validation Failure
7
Human Escalation

不要只比较平均分#

Agent 结果有随机性。应使用：

多 Trial；
置信区间；
分任务类型结果；
严重失败单独门禁；
与同时间段 Control Group 对比。

回滚条件#

例如：

1
安全副作用出现任何严重事件
2
Verified Success 显著下降
3
Cost per Success 超出预算
4
Retry Amplification 明显升高
5
特定关键任务类型回归

Google SRE 建议监控生产中二进制、配置和发布版本，使告警能快速关联到最近变更，而不是事故发生后再翻 CI/CD 日志。[9]

9. 生产事故复盘#

Google SRE 将 Postmortem 定义为对事故、影响、缓解动作、根因和防复发行动的书面记录，并强调无责、数据驱动、及时发布和可执行 Action Items。[14][15]

Agent Incident Report 还需要额外回答：

模型看到什么；
工具和环境发生了什么；
重试是否安全；
Context、Memory 和 Checkpoint 是否一致；
最终 Outcome 如何验证；
事故如何转化为回归评测样本。

下面给出一份完整模板。

Agent Incident Report 模板#

1
# Agent Incident Report：<事故标题>
2

3
## 0. 元数据
4

5
- Incident ID：
6
- 严重级别：
7
- 状态：Draft / Reviewed / Final
8
- 事故开始时间：
9
- 事故结束时间：
10
- 用户影响结束时间：
11
- 发现方式：
12
- Incident Commander：
13
- 技术负责人：
14
- 涉及 Agent：
15
- Agent 版本：
16
- 模型与版本：
17
- Prompt 版本：
18
- Tool Schema 版本：
19
- 检索索引版本：
20
- 环境版本：
21
- 关联 Dashboard：
22
- 关联 Trace：
23
- 关联工单：
24

25
## 1. 执行摘要
26

27
用不依赖内部术语的语言说明：
28

29
- 发生了什么；
30
- 影响了哪些用户或任务；
31
- 持续了多久；
32
- 最终如何缓解；
33
- 当前是否仍有残余风险。
34

35
## 2. 用户任务
36

37
- 原始用户目标：
38
- Task Contract：
39
  - 必须满足：
40
  - 禁止行为：
41
  - 允许作用域：
42
  - 成本预算：
43
  - 时间预算：
44
- 任务类型：
45
- 是否涉及写操作：
46
- 是否涉及不可逆副作用：
47
- 是否需要人工审批：
48
- 预期环境 Outcome：
49

50
## 3. 影响评估
51

52
### 3.1 用户影响
53

54
- 受影响任务数：
55
- 失败任务数：
56
- 部分成功任务数：
57
- 延迟升高：
58
- 人工接管数：
59
- 用户可见错误：
60

61
### 3.2 环境影响
62

63
- 被修改资源：
64
- 重复副作用：
65
- 数据损坏：
66
- 越权或安全影响：
67
- 是否可回滚：
68
- 实际恢复状态：
69

70
### 3.3 成本影响
71

72
- 额外模型请求：
73
- 额外 Token：
74
- Fallback 成本：
75
- 工具/API 额外成本：
76
- 失败任务浪费成本：
77

78
## 4. 执行时间线
79

80
| 时间 | Trace/Span/Event | 发生事项 | 当时系统判断 | 后续影响 |
81
|---|---|---|---|---|
82
| T0 |  | 用户任务进入 |  |  |
83
| T1 |  |  |  |  |
84
| T2 |  |  |  |  |
85

86
时间线至少包含：
87

88
- 用户任务进入；
89
- 模型调用；
90
- Tool Call；
91
- 环境写操作；
92
- 首个异常；
93
- Retry / Fallback；
94
- 告警触发；
95
- 人工介入；
96
- 缓解动作；
97
- Outcome 恢复。
98

99
## 5. 首个异常点
100

101
- Event / Span ID：
102
- 时间：
103
- 期望状态：
104
- 实际状态：
105
- 被打破的不变量：
106
- 当时是否被检测：
107
- 如果没有，为什么：
108
- 证据来源：
109
- 判断置信度：Observed / Supported / Replay Changed / Counterfactual Verified
110

111
## 6. 错误传播路径
112

113
```text
114
Trigger
115
→ First Anomaly
116
→ Model / Tool / Retrieval / State Decision
117
→ Retry or Recovery
118
→ Environment Mutation
119
→ Final User Impact

逐节点记录：

节点	输入	决策/动作	输出	传播到哪里	是否可阻断

7. 根因与促成因素#

7.1 Root Cause#

描述使事故成为可能的系统性原因，不归咎个人。

7.2 Trigger#

描述本次事故被触发的具体事件。

7.3 Contributing Factors#

重试放大：
缺失幂等：
Context 漂移：
检索/记忆污染：
告警延迟：
Runbook 缺失：
人工审批延迟：
版本或配置变化：

7.4 非根因#

列出已经排除的假设及其证据。

8. 最终环境影响#

state_before：
state_after：
state_diff：
Outcome Verifier 结果：
不安全副作用：
重复副作用：
残余风险：
用户数据是否需要修复：
是否需要重新执行任务：

9. 恢复动作#

9.1 即时缓解#

停止哪些 Agent 或版本；
是否关闭写工具；
是否关闭自动 Retry；
是否切换模型或 Provider；
是否回滚 Prompt；
是否转人工。

9.2 状态恢复#

使用的 Checkpoint：
回滚点：
幂等查询：
补偿操作：
重复副作用清理：
恢复验证：

9.3 恢复结果#

恢复耗时：
Recovery Attempt 数：
是否完全恢复：
是否产生二次影响：

10. 缺失的观测字段#

逐项说明：

缺失字段	导致无法回答的问题	临时补救	永久修复	Owner

重点检查：

Provider Request ID；
Stream Sequence；
Tool Call ID；
Operation ID / Attempt ID；
Idempotency Key；
State Before / After / Diff；
Context Manifest；
Retrieval Candidate；
Memory Injection；
Checkpoint / Resume；
Cost；
Outcome Verification。

11. 哪些地方做得好#

哪些保护机制降低了 Blast Radius；
哪些告警及时触发；
哪些 Runbook 有效；
哪些幂等或回滚机制生效；
哪些团队协作有效。

12. 哪些地方需要改进#

检测；
缓解；
恢复；
工具设计；
状态持久化；
人工审批；
监控；
发布流程。

13. 后续行动项#

优先级	行动项	类型	Owner	截止时间	验收标准	Tracking ID
P0		修复/防护/监控/评测

所有行动项必须有：

明确 Owner；
优先级；
截止时间；
可验证验收标准；
跟踪 ID。

14. 后续评测样本构造方式#

14.1 样本目标#

本事故要验证哪一种能力：

网络恢复；
幂等写入；
Loop 检测；
权限拒绝后的替代路径；
Context Compaction；
子 Agent 汇合；
Outcome Verification。

14.2 初始环境#

仓库 Commit：
数据库快照：
Tool/MCP Revision：
权限配置：
模型和 Prompt：
Checkpoint：

14.3 故障注入#

注入点：
注入时间：
故障类型：
持续时间：
是否重复：
随机种子：

14.4 成功标准#

任务 Outcome：
允许 Retry 次数：
最大延迟：
最大成本：
禁止副作用：
必须产生的告警：
必须保留的 Trace 字段：

14.5 Grader#

环境断言：
规则 Grader：
Trace Grader：
LLM Judge：
人工复核：

14.6 数据隔离#

是否进入 Regression Set：
是否进入 Safety Set：
是否冻结为 Test Holdout：
是否允许进入训练数据：
防止近重复泄漏方式：
Dataset Version：

1
---
2

3
### 从事故到评测样本的转换示例
4

5
假设事故是：
6

7
```text
8
run_tests 第一次执行成功，但 Tool Result 丢失；
9
Agent 重试 run_tests 并再次修改临时数据库；
10
最终测试通过，但产生重复测试数据。

应构造评测样本：

1
初始环境：
2
固定仓库和数据库快照。
3

4
故障注入：
5
第一次 run_tests 执行完副作用后丢弃 Tool Result。
6

7
期望行为：
8
Agent 查询 operation_id 对应状态；
9
不得直接重复执行；
10
恢复 Tool Result 或转人工；
11
最终数据库无重复记录。
12

13
评分：
14
任务成功；
15
重复副作用数量为 0；
16
Recovery Rate 成功；
17
Retry Amplification 在允许范围；
18
Trace 中必须存在 unknown_remote_outcome 和状态查询。

这样事故复盘才真正进入质量闭环，而不是停留在文档里。

结语#

Agent 的生产可靠性不能用“模型 API 成功率”概括。

一个完整的 Agent 可靠性系统必须同时管理：

1
模型决策正确性
2
工具和环境副作用
3
网络与流式恢复
4
编排状态一致性
5
循环与无进展检测
6
Checkpoint 与 Replay
7
任务结果验证
8
延迟和成本
9
安全边界
10
SLO 与事故学习

本文可以压缩成四条核心结论。

第一，错误诊断必须从 Outcome 反向追溯到首个异常#

最终 Timeout、Tool Error 或失败回答只是结果。根因分析必须找到最早被打破的任务、状态、检索、安全或副作用不变量。

第二，重试是一种新的业务操作，而不是透明网络细节#

每次重试都会改变：

下游负载；
成本；
延迟；
状态；
副作用风险。

所以必须有 Operation、Attempt、Retry Budget、Backoff、Jitter 和 Idempotency。

第三，Replay 必须逐层控制变量#

Prompt Replay、固定模型响应、Tool Result Replay 和环境快照 Replay 分别隔离不同故障域。完全确定性通常不可得，但足够明确的 Manifest、Checkpoint 和 Fixture 可以让故障变得可复现、可比较。

第四，SLO 必须以用户任务和环境结果为中心#

最重要的指标不是单次模型请求时延，而是：

Verified Task Success；
Recovery；
End-to-end Latency；
Cost per Successful Task；
Unsafe Side-effect。

最终，Agent 可观测性、故障恢复、SLO 和评测并不是四套系统，而是一条连续的数据链：

1
生产 Trace
2
→ 首个异常
3
→ 安全恢复
4
→ Outcome 验证
5
→ SLI / SLO
6
→ Incident Report
7
→ 故障注入回归样本

只有形成这条闭环，Agent 才真正具备可运营、可审计和可持续改进的生产能力。

参考资料#

第 4 篇：Agent 生产故障诊断——网络恢复、循环检测、回放与 SLO

https://jupiter-ws.cn/posts/agent-observability/04-agent-production-failure-diagnosis/

作者

Jupiter

发布于

2026-08-05

许可协议

CC BY-NC-SA 4.0

文章目标#

生产故障诊断的三个基本原则#

原则一：任务 Outcome 高于接口状态#

原则二：最终错误不等于最初根因#

原则三：恢复成功不等于从未失败#

1. Agent 故障分类#

1.1 模型决策错误#

必须区分“决策错误”和“生成错误”#

模型决策错误的诊断字段#

不要把隐藏思维文本作为必需证据#

1.2 工具选择和参数错误#

参数合法不等于操作安全#

推荐记录#

1.3 编排与状态错误#

一个典型状态错误#

编排状态的关键对象#

1.4 检索和记忆错误#

检索故障#

记忆故障#

诊断必须覆盖完整漏斗#

1.5 网络与外部服务错误#

1.6 权限和安全阻断#

正常阻断#

异常阻断#

审批拒绝后的恢复能力#

1.7 环境结果错误#

环境结果必须独立验证#

2. 网络和流式故障#

2.1 连接建立失败#

关键字段#

为什么要拆分阶段#

安全性#

2.2 Stream 中途断开#

断开时的状态快照#

处理原则#

只有部分文本#

Tool Arguments 未完成#

Tool Call 已完整生成但流未完成#

2.3 响应完成但 Usage 丢失#

2.4 429 限流#

429 可能代表不同额度#

应记录#

恢复策略#

2.5 5xx 服务异常#

关键问题#

推荐分类#

2.6 请求是否可以安全重试#

决策矩阵#

推荐伪代码#

2.7 幂等键与重复副作用#

三类 ID 必须分开#

幂等 Ledger#

同一 Key 不应允许不同参数#

重复副作用的防线#

3. Agent 特有异常#

3.1 无限循环#

不能只依赖最大步数#

推荐指标#

停止策略#

3.2 工具振荡#

检测方式#

振荡判定条件#

3.3 重复调用相同工具#

Tool Fingerprint#

合理重复的例外#

3.4 重复修改环境#

检测字段#

防止 Lost Update#

3.5 过早结束#

任务完成判断#

3.6 Context Compaction 后目标丢失#

压缩前后的不变量#

漂移检测#

3.7 子 Agent 无法汇合#

Fan-in 状态#

Merge Policy#

4. 根因分析方法#

4.1 最终报错不等于最初根因#

Root Cause、Trigger 与 Contributing Factor#

4.2 首个异常事件#