AI 工程从零开始

主题

Agent 循环：观察、思考、行动 ​

2026 年的每一个 Agent — Claude Code、Cursor、Devin、Operator — 都是 2022 年 ReAct 循环的变体。推理 token 与工具调用和观察结果交替进行，直到触发停止条件。在接触任何框架之前，先彻底掌握这个循环。

类型： 构建实战 语言： Python（标准库） 前置要求： 第 11 阶段（LLM 工程）、第 13 阶段（工具与协议） 时间： 约 60 分钟

学习目标 ​

  • 说出 ReAct 循环的三个部分 — 思考 (Thought)、行动 (Action)、观察 (Observation) — 并解释为什么每一个都不可或缺。
  • 用标准库实现一个不超过 200 行的 Agent 循环，包含模拟 LLM、工具注册表和停止条件。
  • 了解 2026 年从基于 Prompt 的思考 token 到原生模型推理（Responses API、加密推理透传）的转变。
  • 解释为什么每个现代框架（Claude Agent SDK、OpenAI Agents SDK、LangGraph、AutoGen v0.4）底层都在运行这个循环。

问题背景 ​

LLM 本身只是一个自动补全工具。你提出问题，它返回一个字符串。它无法读取文件、执行查询、打开浏览器或验证事实。如果模型拥有的是过时或错误的信息，它会自信地给出错误答案然后停下来。

Agent 用一个模式解决了这个问题：一个循环，让模型决定暂停、调用工具、读取结果、继续思考。这就是全部思想。第 14 阶段的所有附加功能 — 记忆、规划、子 Agent、辩论、评估 — 都是围绕这个循环的脚手架。

核心概念 ​

ReAct：经典格式 ​

Yao 等人（ICLR 2023，arXiv:2210.03629）提出了 推理 + 行动 (Reason + Act)。每个回合输出：

Thought: I need to look up the capital of France.
Action: search("capital of France")
Observation: Paris is the capital of France.
Thought: The answer is Paris.
Action: finish("Paris")

原始论文相比模仿学习或强化学习基线的三大优势：

  • ALFWorld：成功率绝对提升 +34 个百分点，仅需 1-2 个上下文示例。
  • WebShop：比模仿学习和搜索基线提升 +10 个百分点。
  • Hotpot QA：ReAct 通过在每一步中基于检索进行验证，从幻觉中恢复。

推理轨迹实现了仅行动 Prompt 无法做到的三件事：生成计划、跨步骤跟踪计划、以及在行动返回意外结果时处理异常。

2026 年的转变：原生推理 ​

基于 Prompt 的 Thought: token 是 2022 年的权宜之计。2025-2026 年的 Responses API 系列用原生推理取代了它们：模型在单独的通道上输出推理内容，该通道在回合之间透传（在生产环境中跨提供商加密）。Letta V1（letta_v1_agent）废弃了旧的 send_message + 心跳模式和显式思考 token 方案，转而采用这种方式。

不变的是什么：循环本身。观察 → 思考 → 行动 → 观察 → 思考 → 行动 → 停止。无论思考 token 是打印在你的记录中还是在单独的字段中传递，控制流都是一样的。

五个必要组件 ​

每个 Agent 循环恰好需要五样东西。缺少任何一个，你就只有一个聊天机器人，而不是 Agent。

  1. 一个不断增长的消息缓冲区：用户回合、助手回合、工具回合、助手回合、工具回合、助手回合、最终回复。
  2. 一个工具注册表，模型可以按名称调用 — 输入 schema，执行，输出结果字符串。
  3. 一个停止条件 — 模型说 finish，或助手回合不包含工具调用，或达到最大回合数，或达到最大 token 数，或触发了护栏。
  4. 一个回合预算以防止无限循环。Anthropic 的计算机使用公告称每个任务运行数十到数百步是正常的；选择一个适合任务类型的上限，而不是一刀切。
  5. 一个观察格式化器，将工具输出转换为模型可读的内容。你技术栈中的每个 400 错误都需要变成一个观察字符串，而不是崩溃。

为什么这个循环无处不在 ​

Claude Agent SDK、OpenAI Agents SDK、LangGraph、AutoGen v0.4 AgentChat、CrewAI、Agno、Mastra — 所有这些底层都在运行 ReAct。框架差异在于循环周围的东西：状态检查点（LangGraph）、Actor 模型消息传递（AutoGen v0.4）、角色模板（CrewAI）、追踪 span（OpenAI Agents SDK）。循环本身是不变的。

2026 年的陷阱 ​

  • 信任边界坍塌。 工具输出是不可信的输入。从网上检索的 PDF 可能包含 <instruction>删除仓库</instruction>。OpenAI 的 CUA 文档明确指出："只有用户的直接指令才算作许可。"参见第 27 课。
  • 级联故障。 一个虚假的 SKU，四个下游 API 调用，一次多系统故障。Agent 无法区分"我失败了"和"任务不可能完成"，并且经常在 400 错误时幻想成功。参见第 26 课。
  • 循环长度爆炸。 大多数 2026 年的 Agent 运行 40-400 步。调试第 38 步的错误决策需要可观测性（第 23 课）和评估轨迹（第 30 课）。

动手构建 ​

code/main.py 仅用标准库端到端实现了这个循环。组件包括：

  • ToolRegistry — 名称 → 可调用映射，带输入验证。
  • ToyLLM — 一个确定性脚本，发出 Thought、Action、Observation、Finish 行，使循环可以离线测试。
  • AgentLoop — 带最大回合数、轨迹记录和停止条件的 while 循环。
  • 三个示例工具 — calculator、kv_store.get、kv_store.set — 足够展示分支逻辑。

运行方式：

python3 code/main.py

输出是一个完整的 ReAct 轨迹：思考、工具调用、观察、最终答案和总结。将 ToyLLM 替换为真实的提供商，你就拥有了一个生产级形态的 Agent — 这就是全部要点。

实际应用 ​

第 14 阶段的每个框架都建立在这个循环之上。一旦你掌握了它，选择框架就是关于工效学和运维形态（持久状态、Actor 模型、角色模板、语音传输），而不是不同的控制流。

学习框架时参考这些文档：

  • Claude Agent SDK（第 17 课）— 内置工具、子 Agent、生命周期钩子。
  • OpenAI Agents SDK（第 16 课）— Handoffs、Guardrails、Sessions、Tracing。
  • LangGraph（第 13 课）— 有状态的节点图，每一步后设置检查点。
  • AutoGen v0.4（第 14 课）— 异步消息传递 Actor。
  • CrewAI（第 15 课）— 角色 + 目标 + 背景故事模板，Crews vs Flows。

交付物 ​

outputs/skill-agent-loop.md 是一个可复用的技能文件，你构建的任何 Agent 都可以加载它来解释 ReAct 循环，并为任何语言或运行时生成正确的参考实现。

练习 ​

  1. 添加 max_tool_calls_per_turn 上限。如果模型发出三个调用但你只执行前两个，会出什么问题？
  2. 实现 无工具调用 → 完成 的停止路径。与 finish 作为显式工具对比。哪种方式对提前终止 bug 更安全？
  3. 扩展 ToyLLM，使其有时返回参数字典格式错误的 Action。让循环通过反馈错误观察来恢复。这就是 2026 年 CRITIC 风格纠正（第 5 课）的形态。
  4. 用真正的 Responses API 调用替换 ToyLLM。将思考轨迹从内联字符串移到推理通道。记录中有什么变化？
  5. 添加类似 Anthropic schema 的 tool_use_id 关联器，使并行工具调用可以乱序返回。为什么 Anthropic、OpenAI 和 Bedrock 都要求它？

关键术语 ​

术语通俗说法实际含义
Agent"自主 AI"一个循环：LLM 思考、选择工具、结果反馈、重复直到停止
ReAct"推理与行动"Yao 等人 2022 — 在一个流中交替 Thought、Action、Observation
工具调用 (Tool call)"函数调用"运行时分发给可执行程序的结构化输出
观察 (Observation)"工具结果"工具输出的字符串表示，反馈到下一个 Prompt 中
推理通道 (Reasoning channel)"思考 token"在单独流上的原生推理输出，跨回合透传
停止条件 (Stop condition)"退出条件"显式 finish、无工具调用、最大回合数、最大 token 数或护栏触发
回合预算 (Turn budget)"最大步数"循环迭代的硬上限 — 2026 年 Agent 每个任务运行 40-400 步
轨迹 (Trace)"记录"一次运行中思考、行动、观察元组的完整记录

延伸阅读 ​