Agent Session 恢复与容错策略

Agent Session 恢复与容错策略

问题定义

AI Agent 在长会话中会遇到多种失败模式，每种都会中断工作流：

• API 调用失败（速率限制、网络错误、provider 宕机）
• 上下文窗口超限
• 工具调用结果缺失或格式错误
• 模型输出违反协议约束（如 thinking block 违规）
• JSON 解析错误
• 空消息或损坏的消息历史

没有恢复机制的 Agent 在遇到这些问题时会直接报错，用户必须重新开始——这对长任务（可能已工作数小时）是灾难性的。

恢复场景分类

1. 工具结果恢复

场景：Agent 调用了工具，但工具结果在会话重建中不可用。

恢复策略：

• 识别可恢复的工具调用（幂等操作）
• 重建工具结果状态
• 跳过无法恢复的 tool-part ID，而非让整个恢复失败

损坏消息: [tool_use, tool_result(丢失), text]
恢复策略: 重建可恢复 tool state → 跳过丢失的 tool-part → 保留 text

2. Thinking Block 违规恢复

场景：模型在未启用 thinking mode 时输出了 thinking 标签，或 thinking block 格式不匹配。

恢复策略：

• 检测 thinking block 违规模式
• 重建消息历史，移除或修正违规的 thinking block
• 重新提示模型遵循当前 thinking 配置

3. 空消息恢复

场景：消息历史中出现空 content 字段。

恢复策略：

• 检测空消息位置
• 用占位符或从上下文重建消息内容
• 验证重建后消息历史完整性

4. JSON 解析错误恢复

场景：工具输出包含无效 JSON（如截断的日志、非 JSON 文本）。

恢复策略：

• 尝试部分解析（提取可用的 JSON 片段）
• 将解析错误作为错误消息注入上下文
• 允许 Agent 从错误中继续而非崩溃

5. 上下文窗口恢复

场景：提供商返回 context window exceeded 错误。

恢复策略：

• 智能压缩：优先保留最近的对话和工具结果
• 降级到 fallback 模型（使用不同的上下文窗口大小）
• 触发 compaction（摘要化历史消息）

6. 模型失败与回退

场景：首选模型 API 不可用或返回错误。

恢复策略：

• 双回退系统：
  • model-fallback：主动的模型链选择（在调用前切换）
  • runtime-fallback：被动的故障后恢复（在调用失败后切换）
• 按配置的 fallback_models 数组依次尝试
• 支持对象级 fallback（每个 fallback 可指定不同的 variant、thinking 配置）

恢复架构模式

关键设计原则

透明恢复

恢复发生在 Agent 执行过程中。用户看到结果，而不是失败过程。恢复不是「静默吞错误」，而是「自动修复后继续」。

分层恢复

不同错误类型需要不同的恢复策略。统一恢复逻辑无法处理多样化的失败模式。分层架构：

1. 消息级恢复：修复单条消息的问题（空消息、JSON 错误）
2. 会话级恢复：修复整个会话的状态（上下文超限、工具结果丢失）
3. 模型级恢复：切换模型或 provider

有界重试

无限重试循环比单次失败更糟糕——它会持续消耗 token 和时间。恢复机制必须：

• 设定最大重试次数
• 每次重试后增加退避延迟
• 在重试耗尽时清晰报告失败原因

陷阱与规避

陷阱 1：恢复过程中的状态不一致

问题：恢复操作本身可能引入新的状态不一致，例如跳过 tool-part 后后续消息引用了被跳过的部分。

规避：

• 恢复后验证消息历史的完整性
• 只跳过真正不可恢复的部分
• 保留尽可能多的原始状态

陷阱 2：上下文压缩导致关键信息丢失

问题：智能压缩可能丢弃后续推理所需的关键上下文。

规避：

• 保留最近的对话（时间局部性）
• 保留工具调用的关键输出（而非完整输出）
• 使用 Agent 辅助的压缩（让模型总结重要信息）

陷阱 3：Fallback 模型能力差异

问题：Fallback 模型可能不支持首选模型的工具调用格式或 thinking 模式。

规避：

• 在 fallback 配置中明确指定兼容的工具格式
• 在切换模型时通知 Agent 当前模型的能力差异
• 避免将能力差异过大的模型放在同一 fallback 链中