以下工具、脚本与状态均为教学示例,不涉及任何真实 API、供应商或生产数据。实验中的“模型输出”是预先写死的字符串,目的是把循环的解析与终止行为单独暴露出来,而不是评估模型能力。
ReAct 常被描述成一句提示词:让模型交替输出 Thought、Action、Observation。这个描述漏掉了真正决定系统行为的部分:谁来解析、谁来执行、谁来停止。模型只负责生成下一步的文本;解析器决定这段文本是否构成合法动作;执行器决定动作是否被允许、是否真的产生效果;终止逻辑决定循环什么时候结束。
这四件事只要有一件没有写清楚,ReAct 就会退化成“模型不断说话、系统不断重试”的循环。这一节用一个不依赖任何模型的执行器,把解析、执行和停止分开,再注入四种典型失败,观察它们各自在哪一层被拦住。
循环的三个契约
一个最小 ReAct 循环可以写成状态机:
$$
h_{t+1} = h_t \cdot \text{obs}(a_t), \quad a_t = \text{parse}(m_t), \quad m_t \sim \pi(\cdot \mid h_t)
$$
其中 $m_t$ 是模型在第 $t$ 步的输出,$\text{parse}$ 把它变成动作 $a_t$,$\text{obs}$ 执行动作并返回观测。这个式子看起来简单,但三个函数各自有独立的失败面:
| 契约 | 负责者 | 失败形态 | 典型后果 |
|---|---|---|---|
| 解析 | 运行时 | 缺字段、格式错、参数为空 | 动作没形成,循环空转 |
| 执行 | 运行时 + 工具 | 未知工具、异常、超时、权限拒绝 | 观测缺失或不可信 |
| 停止 | 运行时 | 没有 finish、达到步数/时间上限 | 成本线性增长 |
关键点是:模型输出不是动作。模型输出只是候选文本;经过解析和校验之后,它才成为动作。把这两者混为一谈,会让“模型说了要查订单”被当成“订单已经查过”。在 W2 代码修复和 W3 运维处置里,这个区别直接对应“建议执行”和“已经执行”。
另一个关键点是:Observation 必须由执行器写回,而不是由模型编造。如果提示词允许模型自己在下一轮写 Observation,轨迹就会混入未经执行的虚构观测。正确的做法是把工具返回值作为不可编辑的消息追加到历史里,模型只能读取,不能覆盖。
解析:一步文本的最小语法
实验采用三步语法:
Thought: <为什么做这一步>
Action: <工具名或 finish>
Action Input: <工具参数>
解析器只做三件事:找到三个字段、检查必填项、把 Action Input 当作原始字符串交给工具。它不判断参数语义,也不判断工具是否存在;那是执行层的职责。这样分层的好处是错误可归因:缺 Action 是解析错误,工具名不存在是执行错误,参数类型不对是工具错误。
真实系统通常用 JSON 或函数调用协议代替这种行式语法。格式可以换,但分层不应改变:解析层只回答“这是不是一个结构完整的动作”。如果把工具存在性、权限、参数校验全塞进解析层,错误分类会迅速退化成“解析失败”一个桶,后续统计和修复都无从下手。
执行与停止
执行器维护一个工具表。工具是普通函数:输入字符串,输出观测字符串,异常向上抛。执行器在工具边界捕获异常,把它翻译成 tool_error,而不是让异常穿透整个循环。这样一次工具故障只会终止当前运行,不会破坏轨迹记录。
停止条件至少有两类:
- 显式停止:解析出
finish,把最终答案写入结果。 - 运行时停止:达到步数上限、脚本耗尽、超时或预算耗尽。
实验只实现步数上限和脚本耗尽,因为这两者最容易确定性地复现。生产系统还需要时间、token、金额和外部取消信号;这些条件的共同点是:它们不能由模型自己决定。模型可以建议停止,但运行时必须保留强制停止的能力。
最小实验:四种中断
实验预置四段脚本:
happy:先搜索退款政策,再调用finish。parse_error:只有Thought和Action Input,缺少Action。tool_error:调用除法工具,参数为1,0,触发除零异常。loop:连续搜索六次,永不调用finish,步数上限设为 3。
# file: agp_lab/react_loop.py | write
# tier: 3
# verify: python3 -m unittest tests.test_react_loop
"""最小 ReAct 执行器:思考、行动、观察的闭环。
模型被抽象为一个确定性脚本:每一步输出一段文本,执行器从中解析
出 Action 与 Action Input,调用工具,把返回值作为 Observation 写回
历史,再进入下一步。终止只有两种合法方式:解析出 finish 动作,或
运行时的步数上限。
四种预设脚本分别演示正常完成、解析失败、工具异常和死循环。它们
对应生产系统里最容易被归错类的四种中断:模型没按格式输出、工具
实际报错、循环没有收敛,以及根本没走到终止条件。
"""
from __future__ import annotations
from dataclasses import dataclass
FINISH = "finish"
class ParseError(ValueError):
"""模型输出无法构成一步 ReAct。"""
@dataclass(frozen=True)
class ParsedStep:
thought: str
action: str
action_input: str
@dataclass(frozen=True)
class Result:
status: str
steps: tuple[tuple[str, str], ...]
answer: str | None
error: str | None
def tool_search(query: str) -> str:
"""在固定的小知识库里按子串查找,避免任何外部依赖。"""
index = (
("退款", "退款 3 个工作日到账"),
("发票", "发票为电子版"),
("密码", "重置链接 30 分钟内有效"),
)
for keyword, answer in index:
if keyword in query:
return answer
return "未找到"
def tool_divide(payload: str) -> str:
"""除法工具;参数格式错误或除零都会抛出异常,由执行器归类。"""
left, right = (part.strip() for part in payload.split(",", 1))
return str(float(left) / float(right))
TOOLS = {
"search": tool_search,
"divide": tool_divide,
}
def parse_step(text: str) -> ParsedStep:
"""从一步模型输出中解析 Thought、Action 与 Action Input。"""
thought: str | None = None
action: str | None = None
action_input: str | None = None
for line in text.splitlines():
stripped = line.strip()
if stripped.startswith("Thought:"):
thought = stripped[len("Thought:"):].strip()
elif stripped.startswith("Action Input:"):
action_input = stripped[len("Action Input:"):].strip()
elif stripped.startswith("Action:"):
action = stripped[len("Action:"):].strip()
if thought is None:
raise ParseError("缺少 Thought 行")
if action is None:
raise ParseError("缺少 Action 行")
return ParsedStep(thought, action, action_input or "")
def run_react(script: list[str], max_steps: int = 4) -> Result:
"""执行一段脚本化的 ReAct 轨迹,返回状态、历史与终止原因。"""
if max_steps < 1:
raise ValueError("max_steps 必须为正数")
history: list[tuple[str, str]] = []
for index, text in enumerate(script):
if index >= max_steps:
return Result(
"max_steps",
tuple(history),
None,
f"达到步数上限 {max_steps}",
)
try:
step = parse_step(text)
except ParseError as exc:
return Result("parse_error", tuple(history), None, str(exc))
if step.action == FINISH:
history.append((FINISH, step.action_input))
return Result("finished", tuple(history), step.action_input, None)
tool = TOOLS.get(step.action)
if tool is None:
return Result("unknown_tool", tuple(history), None, step.action)
if not step.action_input:
return Result("parse_error", tuple(history), None, "缺少 Action Input")
try:
observation = tool(step.action_input)
except Exception as exc: # 工具边界:把异常翻译成可归类的状态
detail = f"{type(exc).__name__}: {exc}"
return Result("tool_error", tuple(history), None, detail)
history.append((step.action, observation))
return Result("no_more_output", tuple(history), None, "脚本已耗尽")
def scenarios() -> list[tuple[str, list[str], int]]:
"""四个预设:正常、解析失败、工具异常、死循环。"""
return [
(
"happy",
[
"Thought: 需要查退款政策\nAction: search\nAction Input: 退款",
"Thought: 已有答案\nAction: finish\nAction Input: 退款 3 个工作日到账",
],
4,
),
(
"parse_error",
["Thought: 我先想想\nAction Input: 退款"],
4,
),
(
"tool_error",
["Thought: 算一下转化率\nAction: divide\nAction Input: 1,0"],
4,
),
(
"loop",
[
"Thought: 再查一次\nAction: search\nAction Input: 发票"
for _ in range(6)
],
3,
),
]
if __name__ == "__main__":
print(f"{'场景':<14}{'步数':>4} {'状态':<14}说明")
for name, script, limit in scenarios():
result = run_react(script, limit)
detail = result.answer if result.answer is not None else result.error
print(f"{name:<14}{len(result.steps):>4} {result.status:<14}{detail}")
运行:
cd private/labs/agp-lab
python3 -m agp_lab.react_loop
输出:
场景 步数 状态 说明
happy 2 finished 退款 3 个工作日到账
parse_error 0 parse_error 缺少 Action 行
tool_error 0 tool_error ZeroDivisionError: float division by zero
loop 3 max_steps 达到步数上限 3
四个状态对应四个不同的拦截点:
- finished:解析、执行、停止都正常。两步里包含一次工具调用和一次
finish。 - parse_error:在解析层就被拦住,工具一次都没执行。注意步数为 0:失败发生在动作形成之前。
- tool_error:解析成功、工具被调用,但执行抛出异常。步数仍为 0,因为失败的调用没有被记为成功观测。
- max_steps:解析和执行都正常,唯独没有停止。三步都真实发生了,成本也已经付出。
这张表最重要的读法是:不要把所有非成功都叫“模型失败”。解析失败是格式契约问题,工具异常是执行环境问题,达到上限是终止策略问题。三者的修复动作完全不同:改提示或解析器、修工具或加降级、调预算或改停止条件。
边界与失败模式
第一,工具副作用与观测丢失。 实验里的工具是纯函数,真实工具可能已经产生副作用,却在返回前超时。此时执行器看到的是 tool_error,但世界状态已经改变。重试前必须判断动作是否幂等;不幂等就要先查状态,而不是直接重放。
第二,解析成功不等于动作合法。 Action: deploy 可能格式完全正确,但当前没有审批、没有权限、没有满足前置条件。执行器必须有独立的准入检查,不能把“解析通过”当成“允许执行”。
第三,模型自写观测。 如果历史格式允许模型输出 Observation:,模型可能在下一轮补一个看起来合理的观测。执行器应只接受工具返回值作为观测,模型输出中的观测字段应被忽略或拒绝。
第四,步数上限不是万能的。 上限能止损,但不能保证有结果。达到上限时应该返回明确的部分结果和失败原因,而不是把最后一步的文本当答案。上层需要区分“完成”“部分完成”“未完成”三种语义。
第五,循环内的记忆污染。 失败的工具调用如果被原样写入历史,模型可能在下一轮把错误信息当成事实继续推理。执行器应把失败标记为失败,而不是把它包装成普通观测。
架构含义
ReAct 的工程质量主要不在提示词,而在运行时边界。四条要求可以直接落地:
- 解析与执行分层。 解析器只产出结构化的候选动作;执行器负责准入、调用、异常翻译和观测写回。
- 状态显式化。 每一步记录动作、观测、状态和错误码;循环状态不能只存在于消息数组里。
- 停止条件外置。 显式
finish之外,必须有步数、时间、token 和取消信号;任何一条触发都要有确定的返回语义。 - 工具契约可检查。 每个工具声明输入、输出、是否幂等、失败类型;执行器据此决定重试、降级还是终止。
在 W1 检索问答里,最常见的失败是解析和工具选择;在 W2 代码修复里,最常见的是工具副作用与重试;在 W3 运维处置里,最常见的是停止条件和审批边界。任务不同,优先级不同,但循环骨架是同一套。
判据表
| 判据 | 合格线 | 不合格的典型表现 |
|---|---|---|
| 解析分层 | 解析器不判断工具语义 | 解析失败和工具失败混为一类 |
| 观测来源 | 只有执行器能写观测 | 允许模型自写 Observation |
| 错误码 | 解析/工具/终止可区分 | 统一返回“运行失败” |
| 停止条件 | 显式停止 + 运行时上限 | 只靠模型自己停 |
| 幂等意识 | 非幂等工具不盲目重试 | 超时后直接重放 |
| 部分结果 | 有明确的部分完成语义 | 把最后一步文本当答案 |
小结
- ReAct 不是提示词模板,而是解析、执行、停止三个契约组成的运行时循环。
- 模型输出只是候选文本;解析和校验之后才是动作,工具返回值才是观测。
- 解析失败、工具异常、达到上限是三类不同问题,必须用不同错误码分开统计。
- 停止条件必须外置;步数上限能止损,但不能替代完成语义。
- 非幂等工具在超时后不能盲目重试;先查状态,再决定是否重放。
阅读导航:上一节:3.1 轨迹格式与可验证性 · 下一节:3.3 轨迹失败分类 。
常见错误与边界
- 把模型输出当动作。 未经解析和准入的文本不是动作;“说要做”和“已经做”必须分开。
- 允许模型自写观测。 观测只能由执行器写回;否则轨迹会混入未经执行的虚构结果。
- 把所有失败归为模型能力。 解析、工具、终止是三个独立的失败面,混在一起会让修复方向失焦。
- 只用步数上限做停止。 上限能止损,但不能产生完成语义;必须同时定义部分结果和失败返回。
- 超时后直接重试非幂等工具。 副作用可能已经发生;重试前必须先检查世界状态。
- 失败观测原样进历史。 错误信息不是事实;执行器应标记失败,避免模型把它当证据继续推理。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。