《AI Agent 技术原理与架构·决策、记忆与学习》3.2 ReAct:思考—行动—观察的闭环

ReAct 不是一个提示词模板,而是一个带解析、执行与终止约束的运行时循环。本节用脚本化的模型输出实现最小执行器,分别注入解析失败、未知工具、工具异常和死循环,观察四种中断分别在哪一层被捕获,并给出把解析、工具与终止分开统计的循环设计判据。

以下工具、脚本与状态均为教学示例,不涉及任何真实 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、金额和外部取消信号;这些条件的共同点是:它们不能由模型自己决定。模型可以建议停止,但运行时必须保留强制停止的能力。

最小实验:四种中断

实验预置四段脚本:

  1. happy:先搜索退款政策,再调用 finish。
  2. parse_error:只有 Thought 和 Action Input,缺少 Action。
  3. tool_error:调用除法工具,参数为 1,0,触发除零异常。
  4. 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 的工程质量主要不在提示词,而在运行时边界。四条要求可以直接落地:

  1. 解析与执行分层。 解析器只产出结构化的候选动作;执行器负责准入、调用、异常翻译和观测写回。
  2. 状态显式化。 每一步记录动作、观测、状态和错误码;循环状态不能只存在于消息数组里。
  3. 停止条件外置。 显式 finish 之外,必须有步数、时间、token 和取消信号;任何一条触发都要有确定的返回语义。
  4. 工具契约可检查。 每个工具声明输入、输出、是否幂等、失败类型;执行器据此决定重试、降级还是终止。

在 W1 检索问答里,最常见的失败是解析和工具选择;在 W2 代码修复里,最常见的是工具副作用与重试;在 W3 运维处置里,最常见的是停止条件和审批边界。任务不同,优先级不同,但循环骨架是同一套。

判据表

判据合格线不合格的典型表现
解析分层解析器不判断工具语义解析失败和工具失败混为一类
观测来源只有执行器能写观测允许模型自写 Observation
错误码解析/工具/终止可区分统一返回“运行失败”
停止条件显式停止 + 运行时上限只靠模型自己停
幂等意识非幂等工具不盲目重试超时后直接重放
部分结果有明确的部分完成语义把最后一步文本当答案

小结

  • ReAct 不是提示词模板,而是解析、执行、停止三个契约组成的运行时循环。
  • 模型输出只是候选文本;解析和校验之后才是动作,工具返回值才是观测。
  • 解析失败、工具异常、达到上限是三类不同问题,必须用不同错误码分开统计。
  • 停止条件必须外置;步数上限能止损,但不能替代完成语义。
  • 非幂等工具在超时后不能盲目重试;先查状态,再决定是否重放。

阅读导航:上一节:3.1 轨迹格式与可验证性 · 下一节:3.3 轨迹失败分类 。

常见错误与边界

  1. 把模型输出当动作。 未经解析和准入的文本不是动作;“说要做”和“已经做”必须分开。
  2. 允许模型自写观测。 观测只能由执行器写回;否则轨迹会混入未经执行的虚构结果。
  3. 把所有失败归为模型能力。 解析、工具、终止是三个独立的失败面,混在一起会让修复方向失焦。
  4. 只用步数上限做停止。 上限能止损,但不能产生完成语义;必须同时定义部分结果和失败返回。
  5. 超时后直接重试非幂等工具。 副作用可能已经发生;重试前必须先检查世界状态。
  6. 失败观测原样进历史。 错误信息不是事实;执行器应标记失败,避免模型把它当证据继续推理。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图