Agent Runtime与Checkpoint机制#

一、Runtime 核心职责

二、执行状态机

                    ┌─────────┐
        创建任务 ──→│  INIT    │
                    └────┬────┘
                         │ 开始执行
                    ┌────▼────┐
            ┌──────│ RUNNING  │◄──────────┐
            │      └────┬────┘            │
            │           │ 工具调用          │
            │      ┌────▼────┐      恢复执行│
            │      │ WAITING  │────────────┘
            │      │(工具/人工)│   (工具返回/审批通过)
            │      └────┬────┘
            │           │ 超时/取消
   max_steps│           │
   /预算耗尽 │           │
       ┌────▼────┐      │
       │ PAUSED   │      │
       └────┬────┘      │
            │           │
   手动恢复 │           │
       (→RUNNING)       │
                        ▼
      ┌─────────┐ ┌─────────┐
      │COMPLETED│ │ FAILED   │──→ 重试 ──→ RUNNING
      └─────────┘ └─────────┘       └──→ 人工介入
        ▲  (RUNNING→COMPLETED：目标达成)

状态转换规则：

• RUNNING → WAITING：发起工具调用或等待人工审批
• WAITING → RUNNING：工具返回结果或审批通过
• WAITING → FAILED：工具超时或返回不可恢复错误
• RUNNING → PAUSED：达到 max_steps 或 token 预算耗尽
• PAUSED → RUNNING：人工追加预算或调整参数后恢复
• 任意状态 → FAILED：不可恢复异常
• RUNNING → COMPLETED：任务目标达成

三、Checkpoint 机制设计

什么时候 checkpoint：

1. 每次工具调用返回后（最关键的检查点）
2. LLM 生成执行计划后
3. 完成一轮 ReAct 循环后
4. 人工审批通过后
5. 达到 step 阈值时（如每 5 步强制一次）

checkpoint 需要保存什么：

{
  "task_id": "uuid",
  "state": "RUNNING",
  "step": 7,
  "conversation_history": [...],   // 完整对话（含system/user/assistant/tool）
  "tool_call_results": [...],      // 已完成的工具调用及结果
  "execution_plan": {...},         // 当前执行计划（如果有）
  "partial_outputs": [...],        // 中间产出
  "token_usage": {"prompt": 12000, "completion": 3000},
  "metadata": {
    "created_at": "...",
    "last_checkpoint_at": "...",
    "retry_count": 0
  }
}

存储选型：

四、断点恢复语义

恢复策略有三种：

1. Replay（重放）：从最近的 checkpoint 重新执行后续步骤。要求工具调用幂等。
2. Skip（跳过）：直接使用 checkpoint 中已保存的工具结果，从下一步继续。最常用。
3. Compensate（补偿）：对已执行但需要撤销的步骤执行反向操作。用于部分成功场景。

恢复流程：

加载最近 checkpoint → 恢复对话历史和状态
  → 检查最后一步的状态
    ├─ 工具调用已完成 → Skip，从下一步继续
    ├─ 工具调用进行中 → 查询工具状态，决定重试或跳过
    └─ 工具调用未开始 → Replay，重新执行
  → 恢复 token 计数器和 step 计数器
  → 继续执行循环

幂等性要求：

• 查询类工具天然幂等（搜索、读取）
• 写入类工具需要幂等键（订单号、请求ID）
• 不可幂等工具（发邮件、转账）需要额外防重机制

五、部分失败处理

六、框架实现对比

LangGraph 的 checkpoint 最成熟：支持按 thread_id 管理、时间旅行（回到任意历史节点重新执行）、人工介入后恢复。

Agent Runtime 是 Agent 的执行引擎，我把它类比为线程池——负责任务的生命周期管理、执行循环驱动、工具调度和异常处理。它维护一个状态机：INIT→RUNNING→WAITING（等工具或人工审批）→COMPLETED/FAILED，关键转换点会触发 Checkpoint。Checkpoint 机制的核心是在工具调用返回后、LLM 生成计划后等关键节点持久化当前状态，包括完整对话历史、工具调用结果、执行计划和 Token 用量。恢复时加载最近的 checkpoint，检查最后一步状态：如果工具调用已完成就 Skip 到下一步，如果未完成就 Replay 重新执行，前提是工具调用需要幂等。存储方面生产上推荐混合方案：热数据放 Redis 保证恢复速度，冷数据落数据库支持查询和审计。部分失败时策略是：工具超时重试三次、LLM 格式错误重新请求、Token 耗尽暂停等待追加。这套机制保证了长任务不会因为中间某一步失败就完全白跑。

追问方向：

• “Checkpoint 存储量大怎么治理？”→ 对话压缩（摘要替代原文）+ 只存增量状态差异 + 历史 checkpoint 定期清理（保留最近 N 个 + 关键节点的快照）
• “如何保证 checkpoint 写入的原子性？”→ 事务写入（数据库事务或 WAL 预写日志）+ 写入确认后才继续执行下一步；写失败则从上一个 checkpoint 恢复重试
• “恢复时 LLM 上下文怎么处理？”→ 从 checkpoint 重建对话历史注入 LLM context，如果历史过长则先做压缩/摘要再注入，保证不超过模型上下文窗口限制
• “多 Agent 场景 checkpoint 怎么协调？”→ 每个 Agent 独立维护自己的 checkpoint，Supervisor 维护全局编排状态（任务分配、完成进度）；恢复时先恢复 Supervisor 状态再恢复各 Worker
• “与传统工作流引擎（Temporal/Airflow）的区别？”→ Agent 步骤是动态的（LLM 运行时决定下一步），不能预定义 DAG；checkpoint 粒度更细（每次工具调用前后都可能存档），且状态包含非结构化的对话上下文

易错点：

• ❌ “每步都 checkpoint”——写入开销大，应该只在关键节点checkpoint
• ❌ “恢复就是重新跑一遍”——应该从最近 checkpoint 恢复，而不是从头开始
• ❌ “工具调用都是幂等的”——写入类工具（发邮件/创建工单）需要额外防重设计
• ❌ 混淆 Agent checkpoint 与数据库 WAL——Agent checkpoint 粒度是”步骤级”，不是”操作级”
• ✅ 主动提到”checkpoint 的核心价值是避免长任务失败从头来”