Agent Workflow Recovery Workflow Setup：实现原理与实操指南

什么是 Agent Workflow Recovery Workflow

Agent workflow recovery workflow 是一套在 agent 执行过程中，当工作流因错误、超时或外部中断而失败时，能够自动或手动恢复到一致状态的机制。它不是单个工具，而是结合了状态持久化、检查点（checkpoint）、重试逻辑和补偿操作（compensation）的系统设计。

很多开发者刚开始做 agent 时，只关注 forward path——定义工具、编排步骤、处理正常结果。但一旦遇到网络抖动、LLM 输出格式异常、工具调用超时，整个工作流就会卡住或产生脏数据，这时候 recovery workflow 就变成刚需。

为什么重要：一个真实场景

假设你构建了一个客服 agent，它负责：接收用户问题 -> 搜索知识库 -> 调用 CRM 获取订单信息 -> 生成回复。如果搜索知识库这步超时（比如第三方 API 挂了），没有 recovery workflow，agent 可能直接报错，用户得不到任何回应。更糟的是，CRM 调用已经发出并改变了订单状态（比如标记为“处理中”），此时失败导致状态不一致，后续人工干预会很困难。

有了 recovery workflow，超时后可以：① 重试 2 次搜索；② 如果仍失败，降级走本地缓存；③ 如果缓存也没有，则标记步骤失败并告知用户“部分信息不可用”，同时记录上下文供后续人工审查。整个过程不会破坏 CRM 状态，因为补偿操作会在降级前回滚 CRM 调用。

笔记本电脑屏幕上显示 agent recovery workflow 的 setup 检查清单，包含 checkpoint、idempotency、compensation 等步骤

Agent Workflow Recovery Workflow Setup 实操步骤

1. 定义检查点（Checkpoint）

在 workflow 的每个关键步骤（通常是对外部系统有副作用的操作前后）插入检查点。将当前 agent 的完整上下文（状态、已执行步骤、中间结果）序列化到持久化存储，如数据库或对象存储。

桌面上摊开的笔记，对比不同的 recovery 策略（重试、降级、人工介入），旁边有咖啡和键盘

# 示例：在步骤前后保存 checkpoint
import json, boto3
s3 = boto3.client('s3')

def save_checkpoint(session_id, step_name, context):
    data = {
        'session_id': session_id,
        'step': step_name,
        'context': context,  # 包含所有变量、工具调用历史
        'timestamp': datetime.utcnow().isoformat()
    }
    s3.put_object(Bucket='agent-checkpoints', Key=f'{session_id}/{step_name}.json', Body=json.dumps(data))

最容易做错的地方：只保存轻量状态忽略工具调用历史。恢复时 LLM 不知道之前说过什么，会重复调用或产生矛盾。必须保存完整的 conversation history 和 tool call results。

2. 实现幂等性（Idempotency）

每个可能产生副作用的工具调用都需要幂等键。例如，发送邮件 API 应该支持 deduplication key，这样重试不会发两次。如果不做幂等，重试本身就变成故障源。

3. 设计恢复策略

常见的恢复策略有三种：

自动重试：对于瞬时错误（网络超时、429 Too Many Requests），最大重试 3 次，指数退避。
降级路径：如果关键工具不可用，是否有替代工具或缓存数据？例如搜索失败改用本地索引。
人工介入：对于无法自动恢复的失败（如数据校验不通过），将 session 状态保存并推送到人工队列，同时向用户返回合适的错误消息。

4. 注册补偿操作（Compensation）

如果某个步骤失败，已经执行的前序步骤可能需要回滚。例如，已经创建了订单但后续支付失败，需要自动取消订单。补偿操作需要与正向步骤一一对应，并在 workflow 启动时注册。

compensation_map = {
    'create_order': 'cancel_order',
    'deduct_inventory': 'restore_inventory',
}

def execute_compensation(session_id, failed_step):
    # 反向遍历已执行步骤，执行对应补偿
    for step in reversed(executed_steps):
        if step in compensation_map:
            invoke_tool(compensation_map[step], session_id)

失败场景：补偿操作本身也可能失败。设计时需要考虑 compensation 的重试和最终一致性，或者记录失败让运维手动处理。

最容易踩的坑

过度依赖自动重试：有些错误（如工具不存在、参数错误）重试也不会成功，浪费时间和资源。应该根据错误类型分类，只对瞬态错误重试。
忽略上下文窗口：保存的检查点包含大量 LLM 对话历史，恢复时可能超出 context window limit。需要做摘要或截断。
调试困难：recovery 触发时日志散落各处，很难跟踪。建议引入 trace ID 贯穿所有步骤，集中日志。

备用方案：当 Recovery Workflow 本身失败时

如果 recovery workflow 的脚手架（如 checkpoint 存储不可用、补偿操作也失败），需要最外层的全局兜底：

fallback to manual：将错误详情和上下文发送到运维通知（如 Slack、PagerDuty），保留 session 数据以便人工恢复。
最终状态记录：不管恢复是否成功，总要把最终状态（成功、失败、部分成功）写到一个死信队列（DLQ）或审计表，方便事后分析。
渐进式退化：如果 checkpoint 写入失败，考虑是否仍可继续执行（例如降级为不保存状态，仅记录日志）。

整个 recovery workflow 的设计原则是：保证最终一致性，绝不产生幽灵状态。不要追求完美恢复，而是保证可观测、可补偿、可回滚。

下一步

如果你正在从普通开发者转型为 agent 工程师，理解 recovery workflow 只是第一步。更系统的学习需要你深入掌握 agent 的 context 管理、权限模型、llm evals 以及生产化部署。