返回专栏
· 30 分钟阅读

Agent 的循环执行与状态持久化


一、为什么 Agent 需要循环执行

传统程序通常按照预先定义的流程执行,程序知道下一步应该做什么,执行完毕后便返回结果。

Agent 则不同。它需要根据当前任务状态、模型推理结果和工具执行反馈,动态决定下一步行动。

例如,一个自动分析数据并生成报告的 Agent,可能需要:

  1. 理解用户提出的分析目标。
  2. 判断是否需要查询数据库。
  3. 调用数据库工具获取数据。
  4. 分析查询结果。
  5. 发现数据不足,继续调用其他工具。
  6. 整合分析结果。
  7. 判断是否满足任务目标。
  8. 生成最终报告。

执行过程中,下一步操作往往取决于上一步的结果,因此无法完全依赖固定的线性流程。

Agent 需要一种能够持续运行、动态决策、根据反馈调整行为的执行机制,这就是 Agent Loop。

1.1 Agent Loop 的基本概念

Agent Loop 是 Agent 的循环执行机制,其核心是让模型在每一轮执行中观察当前状态,并决定下一步操作。

一个典型循环包含四个阶段:

阶段 核心职责
Observe 观察当前状态和执行结果
Think 分析任务进度,判断下一步行动
Act 调用工具或执行具体操作
Evaluate 检查执行结果,判断是否继续

其中,Evaluate 不一定是独立的模型调用,也可以由规则、程序或工具结果共同完成。

1.2 Agent Loop 的执行流程

flowchart TD
    A["接收用户任务"] --> B["初始化 Agent 状态"]
    B --> C["观察当前状态"]
    C --> D["模型推理与决策"]
    D --> E{"是否需要执行操作"}
    E -->|"需要"| F["调用工具或执行动作"]
    F --> G["获取执行结果"]
    G --> H["更新 Agent 状态"]
    H --> I{"任务是否完成"}
    I -->|"否"| C
    I -->|"是"| J["生成最终结果"]
    E -->|"不需要"| J

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

循环的关键在于:每次执行结束后,Agent 都会将新信息写入状态,并基于更新后的状态重新决策。

如果没有状态更新,Agent 就无法可靠地知道自己已经完成了哪些工作。


二、Agent Loop 的核心执行机制

Agent Loop 不只是简单地重复调用大模型,而是一套包含决策、动作执行、状态更新和终止判断的控制机制。

2.1 Observe:观察当前状态

Observe 阶段负责收集 Agent 当前能够使用的信息。

主要包括:

  • 用户最初提出的任务。
  • 已经完成的操作。
  • 历史模型推理结果。
  • 工具调用记录。
  • 工具执行返回值。
  • 当前任务进度。
  • 剩余执行预算。
  • 错误信息和异常状态。

例如:

state = {
    "task": "分析最近一个月的销售数据",
    "messages": [],
    "tool_results": [],
    "completed_steps": [],
    "current_step": "query_sales",
    "status": "running"
}

Observe 并不意味着每一轮都将所有历史信息直接交给模型。

在长任务中,应该根据当前决策需要,选择相关消息、工具结果和任务摘要,避免上下文无限增长。

2.2 Think:模型推理与决策

Think 阶段负责根据当前状态决定下一步操作。

模型可能产生以下决策:

  • 继续调用某个工具。
  • 调整工具参数。
  • 根据结果执行新的分析。
  • 请求用户补充信息。
  • 判断任务已经完成。
  • 识别错误并尝试恢复。

例如,模型可能返回:

{
  "action": "call_tool",
  "tool": "query_sales",
  "arguments": {
    "start_date": "2026-10-01",
    "end_date": "2026-10-31"
  },
  "reason": "需要先获取销售数据"
}

这里的输出是一个结构化决策,而不是直接执行数据库查询。

生产环境中,应对模型输出进行 Schema 校验、工具权限检查和参数验证,不能将模型生成的内容直接视为可信指令。

2.3 Act:执行具体操作

Act 阶段负责真正执行模型选择的动作。

常见操作包括:

操作类型 示例
工具调用 查询数据库、搜索网页
API 请求 调用业务系统接口
代码执行 运行 Python 分析数据
文件操作 读取、生成和修改文件
状态操作 更新任务进度
人工交互 请求用户确认

需要注意,模型决定调用工具,不代表工具已经成功执行。

工具调用至少需要区分以下状态:

  • Pending:等待执行。
  • Running:正在执行。
  • Succeeded:执行成功。
  • Failed:执行失败。
  • Timeout:执行超时。
  • Cancelled:执行被取消。

工具执行结果必须反馈给 Agent,才能进入下一轮决策。

2.4 Evaluate:评估执行结果

Evaluate 阶段负责判断当前结果是否满足预期。

例如:

  • 工具是否成功执行?
  • 返回的数据是否完整?
  • 当前步骤是否已经完成?
  • 是否需要重试?
  • 是否需要调整策略?
  • 是否满足最终任务目标?

评估可以由多种机制共同完成:

评估方式 适用场景
规则判断 检查字段、状态码、数量
模型判断 判断结果是否符合语义目标
工具验证 通过查询或测试验证结果
人工确认 涉及重要业务操作时
多重验证 高风险或高价值任务

对于重要任务,不应该仅凭模型说“已经完成”就结束循环,而应该通过可验证的业务条件确认完成状态。


三、Agent Loop 的终止条件

循环执行必须具有明确的终止机制,否则 Agent 可能无限调用工具、重复推理或不断尝试无效操作。

3.1 常见终止条件

终止条件 说明
Goal Achieved 任务目标已经达成
Max Iterations 达到最大循环次数
Timeout 超过任务执行时间
Token Budget 超出模型 Token 预算
Cost Budget 超出任务成本预算
User Cancelled 用户主动取消
Fatal Error 发生不可恢复错误
Human Approval 需要人工确认后暂停

这里需要区分两种状态:

  • Completed:任务已经完成。
  • Suspended:任务暂时暂停,后续可能恢复。

达到最大迭代次数并不意味着任务已经成功,通常应该标记为受限完成或暂停,并向用户说明当前进度。

3.2 带有终止判断的执行流程

flowchart TD
    A["进入 Agent Loop"] --> B["读取当前状态"]
    B --> C["检查任务执行预算"]
    C --> D{"是否超出预算"}
    D -->|"是"| E["标记任务暂停或失败"]
    D -->|"否"| F["执行模型决策"]
    F --> G["执行工具或内部操作"]
    G --> H["更新执行状态"]
    H --> I{"是否满足任务目标"}
    I -->|"是"| J["标记任务完成"]
    I -->|"否"| K{"是否发生不可恢复错误"}
    K -->|"是"| E
    K -->|"否"| L{"是否需要人工确认"}
    L -->|"是"| M["暂停并等待人工输入"]
    L -->|"否"| B
    M --> N["接收人工决策"]
    N --> O{"是否允许继续"}
    O -->|"是"| B
    O -->|"否"| P["结束任务"]

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

3.3 最大迭代次数与执行预算

生产环境中,通常需要同时设置多个限制。

MAX_ITERATIONS = 20
MAX_TOOL_CALLS = 30
MAX_EXECUTION_SECONDS = 300
MAX_RETRIES = 3

def should_stop(state):
    if state["iteration"] >= MAX_ITERATIONS:
        return True

    if state["tool_call_count"] >= MAX_TOOL_CALLS:
        return True

    if state["elapsed_seconds"] >= MAX_EXECUTION_SECONDS:
        return True

    return False

实际实现中,执行时间应由单调时钟或任务调度器计算,而不是依赖模型自行判断。

预算还应该支持按任务类型配置。例如,简单问答可能只允许少量模型调用,而复杂研究任务则允许更长时间和更多工具调用。


四、什么是 Agent 状态

Agent 状态是 Agent 在执行过程中需要持续维护的数据集合。

它不仅包含对话消息,还包含任务目标、执行进度、工具调用结果、错误信息和控制状态。

4.1 Agent 状态的组成

一个相对完整的 Agent 状态可以分成以下几类:

状态类别 典型字段 作用
Task State task_id、goal、status 描述任务本身
Conversation State messages 保存对话上下文
Execution State iteration、current_step 记录执行进度
Tool State tool_calls、tool_results 记录工具执行
Memory State summary、memory_refs 保存任务相关记忆
Error State errors、retry_count 记录异常和重试
Control State next_action、interrupt 控制执行流程
Budget State token_usage、cost、deadline 管理执行预算

不同 Agent 框架的字段设计可能不同,但需要覆盖的状态职责大致相同。

4.2 Agent 状态示例

from typing import TypedDict, Literal, Any

class AgentState(TypedDict):
    task_id: str
    goal: str

    messages: list[dict[str, Any]]

    status: Literal[
        "pending",
        "running",
        "waiting",
        "completed",
        "failed",
        "cancelled"
    ]

    iteration: int
    current_step: str

    tool_calls: list[dict[str, Any]]
    tool_results: list[dict[str, Any]]

    errors: list[dict[str, Any]]
    retry_count: int

    summary: str

    token_usage: int
    cost: float

这里的状态描述的是一个 Agent 任务的执行上下文。

需要注意,任务状态与模型上下文并不是同一个概念:

  • Agent 状态是完整的执行数据。
  • 模型上下文是每次请求模型时选择提供的信息。
  • 持久化状态是需要跨进程、跨时间保留的数据。

三者存在关联,但不能简单等同。

4.3 状态在循环中的变化

假设 Agent 需要查询销售数据并生成报告:

执行阶段 iteration current_step status
初始化 0 planning pending
首次推理 1 query_sales running
查询完成 1 analyze_data running
数据分析 2 generate_report running
报告生成 3 validation running
验证通过 4 completed completed

每一轮执行都可能改变多个状态字段。

因此,状态管理不仅要保存最终结果,还必须记录任务从开始到结束的变化过程。


五、Agent 状态为什么必须持久化

如果 Agent 只把状态保存在内存中,那么程序重启、服务器崩溃或执行环境销毁后,任务状态就可能丢失。

对于短时间、低复杂度的任务,内存状态通常足够。

但对于需要运行几分钟甚至几小时的任务,仅依赖内存就会带来明显风险。

5.1 不持久化会发生什么

假设 Agent 正在执行一个复杂的数据分析任务:

  1. 已经查询了多个数据源。
  2. 已经完成数据清洗。
  3. 已经生成中间分析结果。
  4. 正准备调用工具生成报告。
  5. 此时服务器突然重启。

如果所有状态都保存在进程内存中,重启之后 Agent 就无法准确知道:

  • 原始任务是什么。
  • 已经执行过哪些工具。
  • 哪些操作已经成功。
  • 哪些步骤还没有执行。
  • 当前应该从哪里继续。

Agent 可能被迫从头执行,造成重复计算、重复调用甚至重复业务操作。

5.2 状态持久化的核心价值

价值 说明
故障恢复 进程重启后恢复任务
长任务执行 支持跨时间持续运行
任务暂停 支持人工介入后继续执行
执行追踪 查询历史状态和执行记录
并发管理 支持多个 Worker 协作
审计分析 还原任务执行过程
时间旅行 回到历史状态检查或恢复

状态持久化解决的是 Agent 执行上下文的保存问题。

它并不自动保证外部工具调用不会重复,也不意味着整个系统已经具备事务一致性。


六、Checkpoint:Agent 的检查点机制

Checkpoint 是 Agent 状态持久化中最重要的机制之一。

它表示在某个执行时刻,将当前状态保存为一个可恢复的检查点。

当任务执行到特定阶段时,系统把状态写入持久化存储。

后续发生故障时,就可以从最近一次有效检查点恢复。

6.1 Checkpoint 的基本结构

一个检查点通常需要包含:

字段 作用
checkpoint_id 检查点唯一标识
task_id 所属任务
thread_id 执行会话标识
sequence 检查点序号
parent_checkpoint_id 上一个检查点
state 当前状态快照
metadata 版本、时间等元数据
created_at 创建时间

示例:

{
  "checkpoint_id": "cp_0003",
  "task_id": "task_1001",
  "thread_id": "thread_abc",
  "sequence": 3,
  "parent_checkpoint_id": "cp_0002",
  "state": {
    "status": "running",
    "iteration": 3,
    "current_step": "generate_report",
    "retry_count": 0
  },
  "metadata": {
    "schema_version": 1
  },
  "created_at": "2026-11-20T10:30:00Z"
}

这里的 state 是某个时刻的状态快照,而不是简单的日志文本。

6.2 Checkpoint 的保存时机

并不是每执行一条语句都必须创建检查点。

保存过于频繁会增加存储压力和写入成本,保存过于稀疏则会增加故障后的恢复工作量。

常见保存时机包括:

  • 一轮 Agent 推理完成后。
  • 一个工具调用完成后。
  • 一个重要任务阶段完成后。
  • Agent 即将进入人工审批等待状态时。
  • 任务状态发生关键变化时。
  • 任务正常结束时。

对于有外部副作用的工具调用,需要特别注意检查点与工具执行之间的顺序关系。

6.3 Checkpoint 保存流程

flowchart TD
    A["Agent 开始执行"] --> B["读取当前状态"]
    B --> C["执行模型推理"]
    C --> D["执行工具或任务节点"]
    D --> E["生成新的状态"]
    E --> F{"是否达到检查点条件"}
    F -->|"否"| B
    F -->|"是"| G["生成状态快照"]
    G --> H["写入持久化存储"]
    H --> I{"保存是否成功"}
    I -->|"否"| J["处理持久化异常"]
    J --> K{"是否允许重试"}
    K -->|"是"| H
    K -->|"否"| L["暂停或标记失败"]
    I -->|"是"| M["记录检查点版本"]
    M --> B

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

6.4 快照与增量记录

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

全量快照(Snapshot)

每次保存完整状态。

优点:

  • 恢复过程简单。
  • 不需要重放大量历史事件。
  • 读取当前状态比较直接。

缺点:

  • 状态较大时,存储开销明显。
  • 高频保存可能产生大量重复数据。

增量记录(Delta)

只保存相对于前一个版本发生变化的部分。

优点:

  • 减少重复存储。
  • 适合状态变化较小、历史较长的任务。

缺点:

  • 恢复时需要合并多个版本。
  • 需要处理增量链损坏和版本兼容。
  • 查询历史状态更加复杂。

工程上可以采用定期全量快照与中间增量记录相结合的策略。


七、Agent 状态持久化的存储架构

Agent 的状态存储不一定需要使用单一数据库。

不同类型的数据具有不同的访问模式和生命周期,可以根据数据特征选择存储介质。

7.1 常见存储方案

存储方式 适用场景 特点
Memory 本地开发、临时任务 简单,但无法跨进程恢复
SQLite 单机应用、小规模任务 部署简单,支持事务
PostgreSQL 生产环境任务状态 事务、索引和并发能力较好
Redis 缓存、短期状态、锁 访问速度快,需关注持久化配置
Object Storage 大型状态快照、文件 适合保存大对象
Event Store 事件历史和审计 便于追踪状态变化

实际项目中经常采用组合架构:

  • PostgreSQL 保存任务元数据和检查点索引。
  • Redis 保存短期执行状态和分布式锁。
  • 对象存储保存大型文件和快照附件。
  • 日志或事件存储记录完整执行过程。

7.2 状态数据与业务数据分离

不要把所有业务数据都直接塞进 Agent State。

例如,Agent 正在处理一份 500 MB 的文件。

如果每次创建检查点都将完整文件内容复制到状态快照中,会造成严重的存储和性能问题。

更合理的做法是:

state = {
    "task_id": "task_1001",
    "status": "running",
    "current_step": "analyze_file",
    "file_ref": {
        "object_key": "uploads/report_001.pdf",
        "version": "v3"
    },
    "summary": "正在分析销售报告",
}

Agent 状态保存文件引用、版本和必要的元数据,文件本身放在对象存储中。

这种设计能够减少检查点体积,并让大文件拥有独立的生命周期管理策略。

7.3 推荐的整体架构

flowchart TD
    A["用户请求"] --> B["Agent Runtime"]
    B --> C["Agent Loop"]
    C --> D["状态管理器"]
    D --> E["Checkpoint Manager"]
    E --> F["持久化存储"]
    D --> G["上下文构建器"]
    G --> C
    C --> H["工具执行层"]
    H --> I["外部 API / 数据库"]
    I --> J["执行结果"]
    J --> D
    F --> K["恢复服务"]
    K --> D
    D --> L["任务状态查询 API"]

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

这里需要区分 Agent Runtime 和持久化存储:

  • Runtime 负责当前任务的执行。
  • 状态管理器负责维护运行时状态。
  • Checkpoint Manager 负责生成和管理检查点。
  • 持久化存储负责可靠保存状态。
  • 恢复服务负责将历史状态重新加载到运行环境。

八、Agent 故障恢复机制

持久化的真正价值,在于系统发生异常后能够恢复任务。

但恢复并不是简单地读取最近一次检查点,然后无条件重复执行。

尤其是涉及外部工具调用时,需要判断操作究竟有没有成功。

8.1 常见故障场景

故障场景 可能影响 处理方式
Agent 进程崩溃 内存状态丢失 从检查点恢复
模型请求超时 推理结果未知 结合请求标识判断
工具调用超时 外部操作可能已执行 查询执行结果或幂等重试
数据库暂时不可用 检查点无法保存 重试、降级或暂停
Worker 被终止 任务中断 由调度器重新分配
状态版本变化 旧状态无法直接读取 Schema 迁移
并发恢复 同一任务重复执行 分布式锁或租约机制

8.2 从最近检查点恢复

典型恢复过程:

  1. 查询任务当前状态。
  2. 获取最近一个有效检查点。
  3. 验证检查点数据完整性。
  4. 检查状态 Schema 版本。
  5. 加载状态快照。
  6. 检查尚未完成的工具调用。
  7. 恢复 Agent Loop。
  8. 继续执行后续步骤。
flowchart TD
    A["检测到任务中断"] --> B["查询任务记录"]
    B --> C["读取最近有效检查点"]
    C --> D{"检查点是否存在"}
    D -->|"否"| E["尝试从任务初始状态重建"]
    D -->|"是"| F["验证快照完整性"]
    F --> G{"数据是否有效"}
    G -->|"否"| H["查找更早的有效检查点"]
    H --> C
    G -->|"是"| I["检查状态版本"]
    I --> J["执行 Schema 兼容转换"]
    J --> K["检查未完成工具调用"]
    K --> L["恢复 Agent 状态"]
    E --> L
    L --> M["继续 Agent Loop"]

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

8.3 为什么恢复时不能直接重复工具调用

假设 Agent 执行以下操作:

result = payment_tool(
    order_id="order_1001",
    amount=100
)

支付服务已经成功扣款,但 Agent 在保存检查点之前崩溃。

重启之后,Agent 可能发现当前状态中没有支付成功记录,于是再次调用支付工具。

如果支付接口不具备幂等能力,就可能造成重复扣款。

这说明:

状态持久化只能保存 Agent 已知的执行状态,无法天然保证 Agent 与外部系统之间的操作一致性。

因此必须结合幂等键、操作记录和外部结果查询。


九、工具调用的幂等性与一致性

Agent 的循环执行具有不确定性,而外部工具往往具有真实业务副作用。

因此,工具调用是状态持久化设计中最容易出现问题的部分。

9.1 什么是幂等性

幂等性(Idempotency)是指同一个操作执行一次或多次,最终产生的业务效果相同。

例如:

create_payment(
    order_id="order_1001",
    idempotency_key="task_1001_payment_01"
)

即使 Agent 因为超时或崩溃重复发送请求,支付服务也应该通过幂等键识别这是同一笔业务操作,避免重复扣款。

需要注意,幂等性不意味着每次请求都返回完全相同的响应,而是要求业务副作用不会被重复执行。

9.2 工具调用记录

建议为每一次工具调用建立独立记录:

tool_call = {
    "call_id": "call_001",
    "task_id": "task_1001",
    "tool_name": "create_payment",
    "idempotency_key": "task_1001_payment_01",
    "status": "succeeded",
    "request": {
        "order_id": "order_1001",
        "amount": 100
    },
    "result": {
        "payment_id": "payment_001"
    }
}

工具调用记录至少应该具备:

  • 唯一调用 ID。
  • 所属任务 ID。
  • 工具名称。
  • 幂等键。
  • 请求参数摘要。
  • 执行状态。
  • 返回结果或错误。
  • 开始和结束时间。

对于敏感数据,应该对请求参数和结果进行脱敏或加密。

9.3 工具调用状态机

工具调用可以独立维护状态机:

flowchart TD
    A["创建工具调用记录"] --> B["Pending"]
    B --> C["Running"]
    C --> D{"执行结果"}
    D -->|"成功"| E["Succeeded"]
    D -->|"失败"| F["Failed"]
    D -->|"超时"| G["Unknown"]
    G --> H["查询外部执行结果"]
    H --> I{"是否已经执行"}
    I -->|"是"| E
    I -->|"否"| J["判断是否允许重试"]
    J -->|"允许"| B
    J -->|"不允许"| F

    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:#E5F0E9,stroke:#83A995,color:#315D49
    style F fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D

其中 Unknown 是一个非常重要的状态。

工具调用超时不一定意味着执行失败,也可能意味着:

  • 请求尚未到达外部服务。
  • 外部服务已经执行,但响应丢失。
  • 外部服务仍在处理中。
  • 外部服务执行失败,但错误响应没有返回。

因此,遇到 Unknown 时,应优先查询外部执行结果,而不是直接重试。

9.4 为什么不能轻易承诺 Exactly Once

分布式系统中常见三种执行语义:

语义 含义 风险
At-most-once 最多执行一次 可能丢失操作
At-least-once 至少执行一次 可能重复执行
Exactly-once 业务效果恰好一次 需要额外协调机制

在 Agent 与外部 API 交互的场景中,通常无法仅靠本地检查点实现真正的 Exactly Once。

更实际的工程方案是:

  1. 使用持久化调用记录。
  2. 为业务操作生成稳定的幂等键。
  3. 使用外部系统支持的幂等接口。
  4. 对超时操作查询执行结果。
  5. 对无法确认的操作进入人工核查。
  6. 定期对账,修复状态不一致。

最终追求的是业务效果上的可控幂等,而不是简单地保证网络请求只发送一次。


十、并发执行与状态一致性

当 Agent 系统只有一个 Worker 时,状态更新相对简单。

但生产环境中通常会有多个 Worker,同时处理不同任务,甚至可能因为任务调度异常,让同一个任务被多个 Worker 同时执行。

这会带来状态覆盖、重复调用和检查点冲突。

10.1 并发更新问题

假设同一个 Agent 状态被两个 Worker 同时读取:

初始 iteration = 5

Worker A 读取 iteration = 5
Worker B 读取 iteration = 5

Worker A 更新 iteration = 6
Worker B 更新 iteration = 6

最终数据库中的 iteration 仍然是 6,而不是预期的 7。

这就是典型的丢失更新问题(Lost Update)。

10.2 乐观锁

一种解决方案是使用版本号进行并发控制。

UPDATE agent_tasks
SET
    state = :new_state,
    version = version + 1
WHERE
    task_id = :task_id
    AND version = :expected_version;

如果更新影响行数为 0,说明当前版本已经发生变化。

此时需要重新读取最新状态,再决定是否重新计算或合并更新。

10.3 分布式锁与租约

另一种方案是为任务分配执行租约。

lease = {
    "task_id": "task_1001",
    "worker_id": "worker_03",
    "lease_token": "token_abc",
    "expires_at": "2026-11-20T10:35:00Z"
}

Worker 只有持有有效租约时才能执行任务。

租约机制需要考虑:

  • 租约过期时间。
  • 定期续约。
  • Worker 崩溃后的自动释放。
  • 网络分区导致的过期误判。
  • 旧 Worker 恢复后继续写入的问题。

因此,仅使用分布式锁还不够,重要状态写入最好再结合 Fencing Token(栅栏令牌)或版本校验,拒绝过期 Worker 的写操作。


十一、Agent 长任务的暂停与恢复

有些任务无法在一次连续执行中完成。

例如:

  • 等待用户确认付款。
  • 等待管理员审批。
  • 等待外部系统返回处理结果。
  • 等待定时任务触发。
  • 等待用户补充资料。

此时 Agent 不能一直占用 Worker 资源。

更合理的方式是保存当前状态,暂停执行,等待外部事件到来后重新恢复。

11.1 暂停状态与完成状态

状态 含义 是否可以恢复
Pending 等待执行 可以
Running 正在执行 可通过恢复机制接管
Waiting 等待外部输入 可以
Suspended 主动暂停 可以
Completed 已完成 通常不需要
Failed 执行失败 视恢复策略决定
Cancelled 已取消 通常不允许

11.2 人工介入后的恢复流程

flowchart TD
    A["Agent 正在执行任务"] --> B["识别需要人工确认"]
    B --> C["保存当前状态"]
    C --> D["创建等待事件"]
    D --> E["释放 Worker 资源"]
    E --> F["等待用户或管理员响应"]
    F --> G{"是否收到有效响应"}
    G -->|"否"| F
    G -->|"是"| H["验证响应权限"]
    H --> I{"是否允许继续"}
    I -->|"是"| J["更新 Agent 状态"]
    J --> K["创建恢复任务"]
    K --> L["重新加载检查点"]
    L --> M["继续 Agent Loop"]
    I -->|"否"| N["标记任务取消或终止"]

    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:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style F fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#EAF3EC,stroke:#83A995,color:#315D49
    style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style L fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style M fill:#E5F0E9,stroke:#83A995,color:#315D49
    style N fill:#F7EAE7,stroke:#C98D7C,color:#754438