返回专栏
· 33 分钟阅读

Agent 的可靠性、容错与异常恢复


一、为什么 Agent 需要可靠性机制?

传统软件通常按照确定的程序逻辑执行,输入、处理过程和输出相对可控。

Agent 则不同。

它需要根据用户目标自主规划任务、选择工具、处理结果,并根据执行反馈不断调整策略。一次任务可能持续数分钟、数小时,甚至数天。

例如,用户要求:

分析公司过去三年的经营数据,整理行业资料,生成一份完整的分析报告,并发送给管理层。

Agent 可能需要完成:

  • 查询多个数据库。
  • 读取大量业务文件。
  • 搜索外部行业资料。
  • 调用多个分析工具。
  • 生成图表和报告。
  • 保存中间结果。
  • 发送最终报告。

执行过程中,任何一个环节都可能失败:

  • 模型 API 超时。
  • 工具服务不可用。
  • 数据库连接中断。
  • 文件读取失败。
  • 模型生成无效参数。
  • 外部 API 返回错误。
  • 任务执行超过时间限制。
  • 多 Agent 协作出现结果冲突。
  • 服务重启导致任务中断。
  • 用户审批长时间未完成。

如果没有可靠性机制,一个局部故障就可能导致整个任务失败。

更严重的是,Agent 可能已经执行了一部分操作,却无法准确判断哪些操作成功、哪些操作失败,从而产生重复写入、重复发送邮件或重复扣款等问题。

因此,Agent 系统必须具备四种核心能力:

  1. 可靠执行:在正常情况下稳定完成任务。
  2. 故障隔离:局部故障不会无限传播。
  3. 容错处理:出现异常时能够采取合理的替代策略。
  4. 状态恢复:系统中断后能够从正确的位置继续执行。

二、理解 Agent 的可靠性模型

1. 可靠性、可用性、容错性与恢复能力

这几个概念经常被混用,但它们关注的问题不同。

概念 英文 核心含义
可靠性 Reliability 系统在指定条件下持续正确完成任务的能力
可用性 Availability 系统在需要时能够提供服务的能力
容错性 Fault Tolerance 部分组件发生故障时,系统仍能维持服务
弹性 Resilience 系统受到故障影响后,能够恢复并适应的能力
可恢复性 Recoverability 故障后恢复状态和继续执行的能力
可观测性 Observability 通过日志、指标和追踪理解系统内部状态

例如:

一个 Agent 服务可能一直可以访问,但频繁生成错误结果。

这意味着它具有一定的可用性,却不一定具有良好的可靠性。

另一个 Agent 在调用外部 API 时遇到超时,能够自动切换备用服务并继续执行,这体现了容错能力。

如果服务重启后能够从持久化检查点恢复任务,则体现了可恢复性。

2. Agent 的可靠性由哪些部分决定?

Agent 的可靠性不是单纯的模型准确率。

可以从多个维度理解:

R_{agent} = f(R_{model}, R_{tool}, R_{state}, R_{workflow}, R_{runtime})

其中:

  • R_{model}:模型推理与输出可靠性。
  • R_{tool}:工具调用可靠性。
  • R_{state}:状态管理可靠性。
  • R_{workflow}:任务编排可靠性。
  • R_{runtime}:运行环境可靠性。

这些因素相互影响。

例如,模型生成了正确的工具调用参数,但工具服务发生超时,任务仍然无法完成。

又或者工具执行成功,但系统没有及时保存状态,进程崩溃后可能重复执行。

因此,可靠性必须覆盖整个执行链路。

3. Agent 的端到端执行链路

flowchart TD
    A["用户提交任务"] --> B["任务理解与规划"]
    B --> C["生成执行步骤"]
    C --> D["模型推理"]
    D --> E["选择工具"]
    E --> F["工具参数校验"]
    F --> G["工具执行"]
    G --> H["结果验证"]
    H --> I["更新任务状态"]
    I --> J{"任务是否完成"}
    J -->|"否"| D
    J -->|"是"| K["生成最终结果"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style K fill:#DCEFE5,stroke:#4F8B70,color:#24563F

每个环节都可能出现故障,因此不能只在最终结果阶段检查任务是否成功。

三、Agent 常见故障类型

在设计容错系统之前,需要先识别故障来源。

1. 模型层故障

模型层故障主要来自模型服务和推理过程。

故障 典型表现
API Timeout 模型请求超时
Rate Limit 请求频率超过限制
Service Unavailable 模型服务不可用
Context Overflow 输入超过上下文窗口
Invalid Output 输出格式不符合要求
Hallucination 生成不存在的信息
Tool Selection Error 选择错误工具
Reasoning Failure 推理过程出现逻辑错误

例如,Agent 要求模型生成 JSON:

{
  "tool": "search",
  "query": "AI Agent"
}

但模型实际返回:

我准备调用搜索工具,查询 AI Agent 相关资料。

如果系统直接将其作为 JSON 解析,就会出现格式错误。

模型输出必须经过结构校验,不能默认模型始终遵循约束。

2. 工具层故障

Agent 依赖外部工具完成实际操作,因此工具层是故障高发区域。

常见问题包括:

  • HTTP 请求超时。
  • API 返回 500。
  • API 返回 429。
  • 数据库连接断开。
  • 文件不存在。
  • 权限不足。
  • 第三方服务维护。
  • 工具返回格式变化。
  • 工具执行成功但响应丢失。

其中有一种特别危险的情况:

工具已经执行成功,但 Agent 没有收到成功响应。

例如:

Agent 调用邮件服务发送邮件。

邮件服务已经成功发送,但网络在返回响应之前中断。

Agent 只看到请求超时,无法确定邮件是否真正发送。

如果直接重试,就可能向客户发送两封相同邮件。

这类问题需要通过幂等性和执行状态查询解决。

3. 状态层故障

状态层负责保存 Agent 的任务进度、上下文和执行结果。

常见故障包括:

  • 状态没有及时保存。
  • 状态写入失败。
  • 多个 Worker 同时修改状态。
  • Checkpoint 数据损坏。
  • 恢复时加载了过期状态。
  • 并行任务结果合并冲突。
  • 状态与外部系统实际结果不一致。

例如:

Agent 已经完成数据分析,但尚未保存分析结果,服务就发生崩溃。

恢复后,Agent 可能重新执行整个分析过程。

如果分析过程包含有副作用的操作,就可能造成重复执行。

4. 工作流层故障

复杂 Agent 通常由多个步骤构成。

例如:

数据采集
  → 数据清洗
  → 数据分析
  → 报告生成
  → 审核
  → 发布

可能出现:

  • 某个步骤失败。
  • 前置步骤未完成,后续步骤提前执行。
  • 任务依赖关系错误。
  • 并行步骤未全部完成。
  • 某个子 Agent 长时间无响应。
  • 任务进入死循环。
  • 任务状态长期停留在处理中。

这类故障需要依靠工作流状态机、超时控制和任务调度机制解决。

5. 基础设施故障

基础设施层包括:

  • CPU 资源不足。
  • 内存耗尽。
  • 磁盘空间不足。
  • 容器异常退出。
  • 网络中断。
  • 消息队列不可用。
  • 数据库故障。
  • 云服务区域故障。
  • Worker 进程崩溃。

这类问题通常不能通过修改 Prompt 解决,需要依靠系统架构和基础设施的容错设计。

四、异常分类:哪些错误可以恢复?

并不是所有异常都应该重试。

如果不区分错误类型,Agent 可能在无法恢复的情况下不断重复执行,浪费资源,甚至扩大故障影响。

1. 暂时性异常(Transient Error)

暂时性异常通常可以通过等待或重试恢复。

例如:

  • 网络短暂中断。
  • HTTP 429。
  • 服务临时不可用。
  • 数据库连接超时。
  • 短暂的资源竞争。

适合采用:

  • 延迟重试。
  • 指数退避。
  • 随机抖动。
  • 服务切换。

2. 永久性异常(Permanent Error)

永久性异常通常无法通过简单重试解决。

例如:

  • API Key 无效。
  • 用户权限不足。
  • 参数格式错误。
  • 资源不存在。
  • 请求违反业务规则。
  • 工具名称不存在。

此时应该:

  • 立即停止当前操作。
  • 返回明确错误。
  • 修正参数或权限。
  • 必要时请求用户补充信息。

3. 业务异常(Business Error)

业务异常表示操作本身不符合业务规则。

例如:

  • 账户余额不足。
  • 审批未通过。
  • 订单状态不允许取消。
  • 用户超过操作额度。
  • 当前任务不允许发布。

这类异常不应该被当成技术故障不断重试。

4. 不确定性异常(Ambiguous Failure)

不确定性异常是 Agent 系统中尤其需要关注的一类。

例如:

  • 远程操作可能已经成功,但响应丢失。
  • 数据库提交结果未知。
  • 邮件发送成功与否无法确认。
  • 支付请求超时,但第三方支付平台尚未返回最终状态。

这种情况下,系统不能简单认定操作失败。

正确处理方式通常是:

  1. 查询远端操作状态。
  2. 使用幂等键检查是否已经执行。
  3. 根据实际结果决定是否继续。
  4. 无法确认时进入人工处理。

5. 异常分类表

异常类型 示例 推荐策略
暂时性异常 网络超时 有限重试
永久性异常 参数非法 立即失败
业务异常 审批拒绝 业务分支处理
不确定性异常 请求响应丢失 查询执行状态
资源异常 内存不足 限制资源或重新调度
状态异常 Checkpoint 损坏 恢复备份或人工介入

6. 异常分类与处理流程

flowchart TD
    A["捕获异常"] --> B["提取错误信息"]
    B --> C["异常分类"]
    C --> D{"错误类型"}
    D -->|"暂时性"| E["有限重试"]
    D -->|"永久性"| F["停止执行并返回错误"]
    D -->|"业务异常"| G["进入业务处理分支"]
    D -->|"不确定性"| H["查询远端执行状态"]
    D -->|"资源异常"| I["限流或重新调度"]
    E --> J{"是否恢复成功"}
    J -->|"是"| K["继续任务"]
    J -->|"否"| L["降级或终止"]
    H --> M{"是否确认操作结果"}
    M -->|"已成功"| K
    M -->|"已失败"| E
    M -->|"无法确认"| N["人工介入"]
    G --> O["更新业务状态"]
    I --> P["恢复资源后重新执行"]
    F --> Q["记录失败状态"]
    L --> Q
    N --> Q
    O --> Q
    P --> K

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style E fill:#EAF3EC,stroke:#83A995,color:#315D49
    style F fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style G fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style K fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style L fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style M fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style N fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style O fill:#EAF3EC,stroke:#83A995,color:#315D49
    style P fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style Q fill:#F5F8F4,stroke:#B5CBBB,color:#40594A

五、重试机制:让暂时性故障自动恢复

重试(Retry)是最常见的容错机制。

当 Agent 调用工具失败时,可以根据异常类型重新发起请求。

但重试不是简单地重复调用。

一个合理的重试系统需要控制:

  • 哪些错误可以重试。
  • 最大重试次数。
  • 重试间隔。
  • 总执行时间。
  • 是否存在副作用。
  • 是否需要切换服务。

1. 固定间隔重试

固定间隔重试是最简单的方式。

例如:

第一次失败
  → 等待 2 秒
  → 第二次重试
  → 等待 2 秒
  → 第三次重试

优点是实现简单。

缺点是当大量请求同时失败时,所有请求可能在相同时间重新发起,形成流量尖峰。

2. 指数退避(Exponential Backoff)

指数退避根据重试次数逐步增加等待时间。

公式:

T_n = \min(T_{max}, T_0 \times 2^n)

其中:

  • T_n:第 n 次重试的等待时间。
  • T_0:初始等待时间。
  • T_{max}:最大等待时间。
  • n:重试次数。

例如,初始等待 1 秒:

重试次数 等待时间
第一次 1 秒
第二次 2 秒
第三次 4 秒
第四次 8 秒
第五次 16 秒

这种方式能够降低故障期间对服务的持续压力。

3. 随机抖动(Jitter)

如果所有请求都采用相同的指数退避时间,仍然可能在相同时间重新发起请求。

因此通常加入随机抖动:

T_n = Random(0, \min(T_{max}, T_0 \times 2^n))

这样可以分散请求,避免大量请求同时恢复。

4. 重试次数必须有限制

无限重试会导致:

  • 资源持续消耗。
  • 任务长期无法结束。
  • 请求数量不断增加。
  • 下游服务承受更大压力。
  • 任务队列积压。

因此需要同时限制:

  • 最大重试次数。
  • 单次请求超时。
  • 整体任务截止时间。
  • 总重试预算。

例如:

import random
import time


def retry(
    operation,
    max_attempts=4,
    base_delay=1,
    max_delay=16
):
    for attempt in range(max_attempts):
        try:
            return operation()

        except TimeoutError:
            if attempt == max_attempts - 1:
                raise

            delay = min(
                max_delay,
                base_delay * (2 ** attempt)
            )

            delay = random.uniform(0, delay)

            time.sleep(delay)

    raise RuntimeError("重试失败")

这个示例只捕获超时异常。

实际工程中应根据异常类型决定是否重试,并将重试控制与整体任务截止时间结合,避免等待时间超过任务预算。

5. Retry-After 响应头

当外部 API 返回 HTTP 429 或 503 时,可能提供 Retry-After 响应头。

例如:

HTTP/1.1 429 Too Many Requests
Retry-After: 10

表示建议客户端等待 10 秒后再尝试。

Agent 工具客户端应该优先遵循服务端明确提供的重试建议,同时仍然受到整体截止时间和最大重试次数约束。

6. 重试流程

flowchart TD
    A["发起工具调用"] --> B["等待执行结果"]
    B --> C{"是否成功"}
    C -->|"是"| D["返回执行结果"]
    C -->|"否"| E["识别异常类型"]
    E --> F{"是否允许重试"}
    F -->|"否"| G["记录失败并终止"]
    F -->|"是"| H{"是否超过重试预算"}
    H -->|"是"| G
    H -->|"否"| I["计算退避时间"]
    I --> J["加入随机抖动"]
    J --> K["等待并重新执行"]
    K --> B

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAF3EC,stroke:#83A995,color:#315D49
    style C fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style D fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style G fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style H fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style I fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#EAF3EC,stroke:#83A995,color:#315D49

六、幂等性:防止重复执行产生副作用

重试机制有一个重要前提:

重复执行同一个操作,不能产生不可控的重复副作用。

这就是幂等性(Idempotency)。

1. 什么是幂等性?

如果一个操作执行一次和执行多次,最终结果相同,那么这个操作具有幂等性。

数学上:

f(f(x)) = f(x)

例如:

将用户状态设置为 active,执行一次或多次,最终状态都是 active。

但下面的操作通常不是天然幂等的:

  • 创建订单。
  • 发送邮件。
  • 扣款。
  • 创建文件。
  • 增加账户余额。
  • 发布社交媒体内容。

例如:

account.balance += 100

执行两次会增加 200,而不是 100。

2. 使用 Idempotency Key

可以为每个逻辑操作生成唯一的幂等键。

例如:

{
  "task_id": "task_001",
  "operation_id": "op_001",
  "idempotency_key": "task_001_send_report_001",
  "action": "send_email"
}

服务端收到请求后:

  1. 查询幂等键是否已经处理。
  2. 如果已处理,返回之前保存的结果。
  3. 如果未处理,则执行操作。
  4. 保存操作结果和幂等键。
  5. 后续相同请求直接返回已有结果。

简化示例:

class IdempotencyStore:
    def __init__(self):
        self.results = {}

    def execute_once(self, key, operation):
        if key in self.results:
            return self.results[key]

        result = operation()

        self.results[key] = result

        return result

这段代码仅用于说明幂等键的概念。

生产环境不能仅使用内存字典,因为进程重启后记录会丢失,并且并发请求可能同时通过检查。

应使用具有唯一约束和原子操作能力的持久化存储。

3. 幂等键需要绑定操作参数

同一个幂等键不应该被用于不同的业务操作。

例如:

第一次请求:

{
  "idempotency_key": "order_001",
  "amount": 100
}

第二次请求:

{
  "idempotency_key": "order_001",
  "amount": 1000
}

如果系统只检查幂等键,而不检查参数,就可能返回错误结果。

因此应该保存:

  • 幂等键。
  • 操作类型。
  • 关键业务参数摘要。
  • 执行状态。
  • 执行结果。
  • 创建时间。

如果相同幂等键对应不同参数,应该拒绝请求。

4. 幂等性状态机

stateDiagram-v2
    [*] --> PENDING
    PENDING --> PROCESSING: 开始执行
    PROCESSING --> SUCCEEDED: 执行成功
    PROCESSING --> FAILED: 明确执行失败
    PROCESSING --> UNKNOWN: 执行结果不确定
    FAILED --> PROCESSING: 满足重试条件
    UNKNOWN --> SUCCEEDED: 查询确认成功
    UNKNOWN --> FAILED: 查询确认失败
    UNKNOWN --> PROCESSING: 确认可安全重试
    SUCCEEDED --> [*]

需要特别注意:

UNKNOWN 不能直接等同于 FAILED。

如果远端服务已经完成操作,只是响应丢失,直接重试可能产生重复副作用。

七、断路器:避免故障持续传播

当 Agent 频繁调用一个已经不可用的服务时,持续重试可能进一步加重下游服务压力。

断路器(Circuit Breaker)用于在服务持续失败时,暂时停止调用。

1. 断路器的三个状态

状态 含义
Closed 正常状态,允许请求通过
Open 断开状态,直接拒绝请求
Half-Open 半开状态,允许少量探测请求

2. Closed:正常状态

正常情况下,请求通过断路器并调用服务。

如果错误率持续升高,达到设定阈值,就进入 Open 状态。

3. Open:断开状态

断路器打开后,不再向故障服务发送普通请求。

系统可以:

  • 快速返回错误。
  • 使用缓存结果。
  • 切换备用服务。
  • 暂停相关任务。
  • 将任务放入等待队列。

这样能够避免持续请求进一步压垮下游服务。

4. Half-Open:半开状态

经过一段冷却时间后,系统允许少量探测请求。

如果探测成功,则恢复 Closed 状态。

如果探测失败,则重新进入 Open 状态。

5. 断路器状态转换

stateDiagram-v2
    [*] --> Closed
    Closed --> Open: 失败率超过阈值
    Open --> HalfOpen: 冷却时间结束
    HalfOpen --> Closed: 探测请求成功
    HalfOpen --> Open: 探测请求失败

6. 断路器与重试的区别

机制 解决的问题
Retry 单次请求暂时失败
Circuit Breaker 下游服务持续故障
Timeout 请求长期没有响应
Rate Limiter 请求速度过快
Bulkhead 故障扩散到其他资源池

它们通常需要配合使用。

例如:

Agent 调用外部搜索 API 时:

  • 单次超时由 Timeout 控制。
  • 临时错误由 Retry 处理。
  • 服务持续失败由 Circuit Breaker 保护。
  • 请求过多由 Rate Limiter 限制。
  • 不同工具之间通过 Bulkhead 隔离资源。

八、超时控制:防止任务无限等待

Agent 经常需要等待外部工具返回结果。

如果工具没有合理的超时设置,一个请求可能长期占用连接、线程和任务资源。

1. 常见超时类型

超时类型 含义
Connection Timeout 建立连接的最大等待时间
Read Timeout 等待响应数据的最大时间
Tool Timeout 单次工具调用的最大时间
Model Timeout 模型请求的最大时间
Step Timeout 单个工作流步骤的最大时间
Task Deadline 整个任务的截止时间

2. 为什么需要整体任务截止时间?

假设一个 Agent 有 10 个步骤,每个步骤最多执行 60 秒。

如果每个步骤都独立等待 60 秒,整个任务可能耗时 10 分钟。

如果用户要求 3 分钟内完成,那么单步骤超时并不能保证整体任务满足要求。

因此需要统一的 Deadline。

每次执行步骤时,系统都要计算剩余时间:

T_{remaining} = T_{deadline} - T_{now}

当前步骤的超时时间不能超过剩余任务时间。

3. 超时控制流程

flowchart TD
    A["创建任务"] --> B["设置任务 Deadline"]
    B --> C["执行当前步骤"]
    C --> D["计算剩余时间"]
    D --> E{"是否超过截止时间"}
    E -->|"是"| F["取消或终止任务"]
    E -->|"否"| G["设置步骤超时"]
    G --> H["调用模型或工具"]
    H --> I{"是否在时间内完成"}
    I -->|"是"| J["保存步骤结果"]
    I -->|"否"| K["触发超时异常"]
    K --> L["判断是否允许重试"]
    L --> M{"是否仍有时间预算"}
    M -->|"是"| C
    M -->|"否"| F
    J --> N{"任务是否完成"}
    N -->|"否"| C
    N -->|"是"| O["返回最终结果"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAF3EC,stroke:#83A995,color:#315D49
    style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style E fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style F fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style G fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style H fill:#EAF3EC,stroke:#83A995,color:#315D49
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style K fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style L fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style M fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style N fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style O fill:#DCEFE5,stroke:#4F8B70,color:#24563F

超时并不代表远端操作已经停止。

例如,客户端停止等待邮件 API,不代表邮件服务停止发送邮件。

因此,对具有副作用的操作,超时之后仍然需要通过幂等键或远端状态查询确认执行结果。

九、Checkpoint:让 Agent 从中断位置恢复

对于长周期 Agent,仅依靠内存保存任务状态是不够的。

一旦进程崩溃,内存状态就会丢失。

Checkpoint(检查点)用于保存 Agent 在执行过程中的关键状态,使任务可以从之前的状态继续。

1. Checkpoint 保存什么?

典型内容包括:

  • Task ID。
  • 当前执行节点。
  • 当前任务状态。
  • 已完成步骤。
  • 中间结果。
  • 工具调用记录。
  • 重试次数。
  • 待处理操作。
  • 用户审批状态。
  • 上下文摘要。
  • 版本和时间戳。

例如:

{
  "task_id": "task_001",
  "status": "running",
  "current_step": "analyze_data",
  "completed_steps": [
    "collect_data",
    "clean_data"
  ],
  "retry_count": 1,
  "state_version": 12,
  "checkpoint_at": "2026-11-21T10:00:00Z"
}

2. 为什么不能只保存模型对话?

Agent 的状态不仅是聊天历史。

例如:

  • 对话记录描述用户说过什么。
  • 任务状态描述当前执行到了哪里。
  • 工具记录描述执行过哪些操作。
  • Checkpoint 描述某个时间点的可恢复状态。

如果只保存对话历史,系统仍然无法准确判断:

  • 哪些工具已经执行。
  • 哪些步骤已经完成。
  • 哪些操作尚未确认。
  • 哪些结果已经持久化。
  • 哪些任务可以安全重试。

因此,Checkpoint 应保存结构化任务状态,而不仅仅是聊天消息。

3. Checkpoint 的基本工作机制

flowchart TD
    A["开始 Agent 任务"] --> B["读取当前状态"]
    B --> C["执行工作流节点"]
    C --> D["产生节点结果"]
    D --> E["更新 State"]
    E --> F["持久化 Checkpoint"]
    F --> G{"是否还有后续节点"}
    G -->|"是"| C
    G -->|"否"| H["任务完成"]
    F --> I["发生进程中断"]
    I --> J["恢复 Worker"]
    J --> K["加载最近 Checkpoint"]
    K --> L["恢复任务状态"]
    L --> C

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAF3EC,stroke:#83A995,color:#315D49
    style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style H fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style I fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style L fill:#EAF3EC,stroke:#83A995,color:#315D49

4. Checkpoint 的保存时机

可以采用不同的保存策略。

节点完成后保存

每个工作流节点执行成功后立即保存状态。

优点是恢复粒度较细。

缺点是写入频率较高。

关键步骤保存

只在重要节点保存。

例如:

  • 数据采集完成。
  • 数据分析完成。
  • 报告生成完成。
  • 外部操作完成。

这种方式减少持久化开销,但发生故障时可能需要重新执行部分工作。

定时保存

按照固定时间间隔保存状态。

适合持续执行的任务,但需要考虑定时保存与实际操作之间的状态一致性。

5. Checkpoint 与外部副作用的一致性

这是生产级 Agent 设计中的难点。

假设:

  1. Agent 调用支付工具。
  2. 支付服务已经扣款。
  3. Agent 尚未保存 Checkpoint。
  4. 进程崩溃。

恢复后,Agent 可能不知道支付是否已经完成。

因此:

Checkpoint 只能恢复本地工作流状态,不能自动恢复外部系统的真实状态。

需要将 Checkpoint 与幂等操作记录、远端状态查询和事务机制结合起来。

十、状态机:明确任务处于什么阶段

Agent 的状态管理不能仅使用一个简单的 running 或 failed 字段。

复杂任务需要明确的状态机。

1. 常见任务状态

状态 含义
CREATED 任务已创建
PENDING 等待调度
RUNNING 正在执行
WAITING 等待外部事件
RETRYING 正在重试
PAUSED 主动暂停
RECOVERING 正在恢复
SUCCEEDED 成功完成
FAILED 执行失败
CANCELLED 用户取消
TIMED_OUT 超时终止

2. 为什么需要状态机?

假设一个任务当前处于 SUCCEEDED。

系统不应该再将其切换为 RUNNING,除非明确创建新的执行版本或重新打开任务。

同样,处于 CANCELLED 的任务也不能因为某个延迟到达的工具响应,就自动恢复执行。

状态机能够限制非法状态转换。

3. 状态转换规则

stateDiagram-v2
    [*] --> CREATED
    CREATED --> PENDING: 提交调度
    PENDING --> RUNNING: Worker 开始执行
    RUNNING --> WAITING: 等待外部事件
    WAITING --> RUNNING: 收到外部事件
    RUNNING --> RETRYING: 暂时性异常
    RETRYING --> RUNNING: 重试成功
    RETRYING --> FAILED: 重试耗尽
    RUNNING --> PAUSED: 主动暂停
    PAUSED --> RUNNING: 恢复执行
    RUNNING --> RECOVERING: 运行环境中断
    RECOVERING --> RUNNING: 恢复成功
    RECOVERING --> FAILED: 无法恢复
    RUNNING --> SUCCEEDED: 任务完成
    RUNNING --> FAILED: 不可恢复异常
    RUNNING --> TIMED_OUT: 超过截止时间
    PENDING --> CANCELLED: 用户取消
    RUNNING --> CANCELLED: 用户取消
    SUCCEEDED --> [*]
    FAILED --> [*]
    CANCELLED --> [*]
    TIMED_OUT --> [*]

状态机应在服务端执行转换校验。

不能让模型直接写入任意任务状态。

4. 状态更新需要并发控制

如果两个 Worker 同时处理同一个任务,就可能出现状态覆盖。

例如:

  • Worker A 读取版本 10。
  • Worker B 读取版本 10。
  • Worker A 更新为版本 11。
  • Worker B 使用旧数据覆盖版本 11。

可以使用乐观锁(Optimistic Locking):

UPDATE agent_tasks
SET
    status = 'RUNNING',
    version = version + 1
WHERE
    task_id = 'task_001'
    AND version = 10;

如果更新行数为 0,说明版本已经发生变化,需要重新读取状态并处理冲突。

生产环境还可以使用任务租约(Lease)、Worker 心跳和 fencing token,防止失去租约的旧 Worker 继续写入状态。

十一、长周期任务的故障恢复

长周期 Agent 与普通请求式 Agent 的最大区别,是任务可能跨越多个执行周期。

例如:

  • 任务执行过程中 Worker 重启。
  • 用户审批几个小时后才完成。
  • 外部服务第二天才恢复。
  • 任务等待第三方数据。
  • 系统部署升级导致执行进程退出。

这意味着 Agent 必须具备持久化任务和异步恢复能力。

1. 长周期任务架构

一个可靠的长周期 Agent 通常包含:

组件 作用
Task Store 保存任务基本信息
State Store 保存执行状态
Checkpoint Store 保存恢复检查点
Message Queue 调度任务
Worker Pool 执行任务
Scheduler 管理任务调度
Retry Manager 控制重试
Recovery Manager 检测并恢复异常任务
Event Store 保存关键执行事件

2. 任务中断与恢复

flowchart TD
    A["创建长周期任务"] --> B["保存任务信息"]
    B --> C["进入任务队列"]
    C --> D["Worker 获取任务"]
    D --> E["加载任务状态"]
    E --> F["执行当前步骤"]
    F --> G["保存 Checkpoint"]
    G --> H{"是否正常完成"}
    H -->|"是"| I["标记任务成功"]
    H -->|"否"| J{"是否发生异常"}
    J -->|"否"| F
    J -->|"是"| K["记录故障事件"]
    K --> L["Recovery Manager 分析"]
    L --> M{"是否可以自动恢复"}
    M -->|"是"| N["重新调度任务"]
    N --> D
    M -->|"否"| O["暂停任务并告警"]
    O --> P["人工处理"]
    P --> Q{"是否允许继续"}
    Q -->|"是"| N
    Q -->|"否"| R["标记任务失败"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style D fill:#EAF3EC,stroke:#83A995,color:#315D49
    style E fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style H fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style K fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style L fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style M fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style N fill:#EAF3EC,stroke:#83A995,color:#315D49
    style O fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style P fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style Q fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style R fill:#F7EAE7,stroke:#C98D7C,color:#754438

3. Worker 崩溃检测

Worker 可能因为以下原因退出:

  • 容器被终止。
  • 进程异常。
  • 内存耗尽。
  • 网络中断。
  • 节点故障。

系统可以使用心跳机制判断 Worker 是否仍然存活。

例如:

{
  "worker_id": "worker_001",
  "task_id": "task_001",
  "lease_expires_at": "2026-11-21T10:05:00Z",
  "heartbeat_at": "2026-11-21T10:04:30Z"
}

如果租约到期,调度器可以认为该 Worker 不再拥有任务执行权,并将任务重新分配。

但要注意:

旧 Worker 可能只是网络暂时中断,并没有真正停止。

因此,重新分配任务时必须使用租约、fencing token 和幂等执行机制,防止两个 Worker 同时产生副作用。

十二、Saga:处理跨服务长事务

Agent 可能需要连续调用多个外部服务。

例如:

  1. 创建订单。
  2. 扣减库存。
  3. 扣除账户余额。
  4. 创建物流单。
  5. 发送订单通知。

这些操作可能分布在多个独立服务中,无法使用一个数据库事务统一提交。

如果第三步失败,前两步已经产生的影响应该如何处理?

这就是 Saga 模式要解决的问题。

1. 什么是 Saga?

Saga 是一种分布式事务协调模式。

它将一个长事务拆分成多个局部事务,每个局部事务拥有对应的补偿操作。

例如:

正向操作 补偿操作
创建订单 取消订单
扣减库存 恢复库存
冻结余额 解冻余额
创建物流单 取消物流单

注意,补偿操作不一定等于数据库回滚。

例如,已经发送给客户的邮件无法真正撤回,只能通过后续通知进行补救。