一、为什么 Agent 需要循环执行
传统程序通常按照预先定义的流程执行,程序知道下一步应该做什么,执行完毕后便返回结果。
Agent 则不同。它需要根据当前任务状态、模型推理结果和工具执行反馈,动态决定下一步行动。
例如,一个自动分析数据并生成报告的 Agent,可能需要:
- 理解用户提出的分析目标。
- 判断是否需要查询数据库。
- 调用数据库工具获取数据。
- 分析查询结果。
- 发现数据不足,继续调用其他工具。
- 整合分析结果。
- 判断是否满足任务目标。
- 生成最终报告。
执行过程中,下一步操作往往取决于上一步的结果,因此无法完全依赖固定的线性流程。
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 正在执行一个复杂的数据分析任务:
- 已经查询了多个数据源。
- 已经完成数据清洗。
- 已经生成中间分析结果。
- 正准备调用工具生成报告。
- 此时服务器突然重启。
如果所有状态都保存在进程内存中,重启之后 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 从最近检查点恢复
典型恢复过程:
- 查询任务当前状态。
- 获取最近一个有效检查点。
- 验证检查点数据完整性。
- 检查状态 Schema 版本。
- 加载状态快照。
- 检查尚未完成的工具调用。
- 恢复 Agent Loop。
- 继续执行后续步骤。
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。
更实际的工程方案是:
- 使用持久化调用记录。
- 为业务操作生成稳定的幂等键。
- 使用外部系统支持的幂等接口。
- 对超时操作查询执行结果。
- 对无法确认的操作进入人工核查。
- 定期对账,修复状态不一致。
最终追求的是业务效果上的可控幂等,而不是简单地保证网络请求只发送一次。
十、并发执行与状态一致性
当 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