深入理解 Agent Loop：从 ReAct 到现代 AI Agent 的核心引擎

每一个运行中的 AI Agent，背后都在执行同一个循环。这个循环决定了 Agent 能否正确理解任务、调用工具、处理结果，并在多轮迭代中自主完成任务。它就是 Agent Loop——智能体的核心引擎。

2025 年下半年到 2026 年，Anthropic 发布了 Claude Agent SDK（前身 Claude Code SDK），OpenAI 推出了 Agents SDK，Google Cloud 发布了 agentic AI 架构设计指南。这些框架和指南不约而同地指向同一个核心概念：Agent Loop。

本文将从 2022 年的 ReAct 论文讲起，拆解 Agent Loop 的演进脉络，再结合 Claude Agent SDK 和 OpenAI Agents SDK 的实际实现，还原这个"核心引擎"的完整运行机制。

本文大纲
- ReAct：Agent Loop 的理论起源
- 从论文到工程：Agent Loop 的通用架构
- Claude Agent SDK 的 Agent Loop 实现
- OpenAI Agents SDK 的 Agent Loop 实现
- 两种 SDK 的对比
- 生产环境中的关键工程问题
- 从单 Agent 到多 Agent：Loop 的扩展

ReAct：Agent Loop 的理论起源

2022 年 10 月，Google Research 和普林斯顿大学发表了论文 "ReAct: Synergizing Reasoning and Acting in Language Models"（Yao et al., 2022）。这篇论文提出了一个简单但影响深远的思路：让 LLM 交替生成推理轨迹（Thought）和行动指令（Action），再从环境中获取观察结果（Observation），形成一个闭环。

这就是 ReAct 的核心循环：

Thought → Action → Observation → Thought → Action → Observation → ...

具体来说：

Thought：LLM 生成一段推理文本，分析当前状态，决定下一步做什么
Action：LLM 输出一个结构化的动作指令（比如搜索某个关键词、调用某个 API）
Observation：外部环境执行动作并返回结果，LLM 将结果作为下一轮输入

ReAct 的价值在于，它解决了此前两种方法的各自缺陷：

方法	代表	优势	劣势
纯推理（Reason-only）	Chain-of-Thought	逻辑清晰	无法与外部环境交互，容易"幻觉"
纯行动（Act-only）	直接调用工具	能获取外部信息	缺乏规划，动作盲目
ReAct	Thought + Action	推理引导行动，行动验证推理	实现更复杂

论文中的实验表明，在 HotpotQA（多跳问答）和 FEVER（事实验证）等任务上，ReAct 显著优于纯 CoT 或纯 Act 方法。

从论文到工程：Agent Loop 的通用架构

ReAct 论文为 Agent Loop 奠定了理论基础，但工程实现需要解决更多问题。一个生产级 Agent Loop 的通用架构如下：

MERMAID_BLOCK_0

这个架构包含五个阶段：

接收输入（Receive）：获取用户提示、System Prompt、工具定义和历史对话
状态评估（Evaluate）：LLM 分析当前状态，决定下一步行动
工具调用（Execute）：执行 LLM 请求的一个或多个工具
结果收集（Collect）：将工具执行结果反馈给 LLM
循环或终止：重复步骤 2-4，直到 LLM 认为任务完成并返回纯文本结果

从 ReAct 的 "Thought-Action-Observation" 三元组，到这个五阶段架构，本质上是将论文中的概念映射到了工程实现中。

Claude Agent SDK 的 Agent Loop 实现

Anthropic 在 2025 年底将 "Claude Code SDK" 更名为 "Claude Agent SDK"，标志着从"代码辅助工具"到"通用 Agent 框架"的定位转变。其 Agent Loop 实现是目前最接近 Claude Code 本身运行逻辑的版本。

执行流程

Claude Agent SDK 的 Loop 是这样运转的：

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio

async def run_agent():
    async for message in query(
        prompt="修复 auth 模块中的测试失败",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
            max_turns=30,
            effort="high",
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(f"完成: {message.result}")
                print(f"花费: ${message.total_cost_usd:.4f}")
            else:
                print(f"终止原因: {message.subtype}")

asyncio.run(run_agent())

一个典型的执行过程是这样的：

Turn 1：Claude 调用 Bash 运行 npm test，获得测试失败信息（3 个失败用例）
Turn 2：Claude 调用 Read 读取 auth.ts 和 auth.test.ts，分析代码逻辑
Turn 3：Claude 调用 Edit 修复代码，然后调用 Bash 重新运行测试，全部通过
Final Turn：Claude 返回纯文本结果，不含工具调用，Loop 结束

这里的关键概念是 Turn。一个 Turn 是一次完整的"LLM 输出 → 工具执行 → 结果反馈"循环。多个 Turn 串联起来就构成了整个 Agent 的执行过程。

消息类型

Claude Agent SDK 在 Loop 运行过程中 yield 出五种消息类型：

消息类型	触发时机	内容
`SystemMessage`	会话初始化、上下文压缩后	会话元数据、压缩边界标记
`AssistantMessage`	每次 Claude 响应后	文本内容和工具调用请求
`UserMessage`	工具执行完成后	工具返回的结果数据
`StreamEvent`	开启 partial messages 时	实时流式文本和工具输入
`ResultMessage`	Loop 结束时	最终结果、token 用量、花费、session ID

工具系统

工具是 Agent Loop 的"手和脚"。没有工具，LLM 只能输出文本。Claude Agent SDK 提供了丰富的内建工具：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "分析项目中所有 API 端点的认证方式",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Bash", "WebSearch"],
    settingSources: ["project"],
    maxTurns: 20,
    effort: "high"
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
    console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
  }
}

除了内建工具，还可以通过 MCP Server 连接外部服务（数据库、浏览器、第三方 API），或定义 Custom Tool 扩展能力。

上下文窗口管理

Agent Loop 的一个核心挑战是上下文窗口管理。随着 Turn 数增加，对话历史不断累积，System Prompt、工具定义、每一轮的工具输入和输出都在消耗 token。

Claude Agent SDK 提供了自动压缩（Automatic Compaction）机制：当上下文接近窗口上限时，SDK 自动将旧消息压缩为摘要，保留最近的关键信息。压缩时会触发 SystemMessage（subtype 为 compact_boundary），通知应用层。

对于长期运行的 Agent，还有几个策略可以保持上下文精简：

Subagent 委托：每个 Subagent 拥有独立上下文，只将最终结果返回给主 Agent
精简工具集：每个工具定义都消耗上下文空间，按需加载
调整 effort 级别：对简单任务使用 "low"，减少推理 token 消耗

OpenAI Agents SDK 的 Agent Loop 实现

OpenAI 的 Agents SDK 采用了一条不同的技术路线。它的核心执行入口是 Runner.run()，围绕 Agent、Handoff、Guardrails 三个核心概念构建。

执行流程

from agents import Agent, Runner

agent = Agent(
    name="代码审查助手",
    instructions="你是一个专业的代码审查员。阅读代码，指出潜在问题。",
    tools=[read_file, search_code, lint_check]
)

result = Runner.run(agent, input="审查 src/auth.py 的安全性")
print(result.final_output)

Runner.run() 的执行循环：

将用户输入和 Agent 配置（instructions + tools）发送给 LLM
LLM 返回响应，可能包含工具调用
执行工具，将结果追加到对话历史
重复步骤 2-3，直到 LLM 返回纯文本结果或触发 Handoff
返回最终结果

Handoff 机制

OpenAI Agents SDK 的独特设计是 Handoff（交接）。当一个 Agent 发现自己无法处理某个任务时，可以将控制权交给另一个 Agent：

from agents import Agent, Runner

triage_agent = Agent(
    name="分诊 Agent",
    instructions="判断用户问题是技术问题还是账单问题，然后交给对应 Agent。",
    handoffs=[tech_support_agent, billing_agent]
)

result = Runner.run(triage_agent, input="我的 API key 无法使用")

Handoff 本质上是 Agent Loop 的"跳转"——当前 Agent 的 Loop 暂停，新 Agent 接管上下文继续执行。这使得多个 Agent 可以在同一个请求中协作，而不需要复杂的路由逻辑。

Guardrails 安全护栏

OpenAI Agents SDK 在 Loop 的入口和出口处加入了 Guardrails：

from agents import Agent, InputGuardrail, GuardrailFunction

async def check_input_safety(ctx, agent, input):
    # 检查输入是否包含敏感信息或注入攻击
    if contains_pii(input):
        return GuardrailResult(tripwire_triggered=True, output="输入包含敏感信息")
    return GuardrailResult(tripwire_triggered=False)

agent = Agent(
    name="安全 Agent",
    input_guardrails=[InputGuardrail(guardrail_function=check_input_safety)],
    output_guardrails=[output_check]
)

Guardrails 在 Agent Loop 之外运行，不影响 LLM 的上下文，但可以在 Loop 开始前拦截不安全的输入，或在 Loop 结束后过滤不合规的输出。

两种 SDK 的对比

维度	Claude Agent SDK	OpenAI Agents SDK
核心循环	Turn-based，显式的消息流	Runner.run()，隐式循环
多 Agent	Subagent 委托（独立上下文）	Handoff 交接（上下文传递）
工具管理	内建工具 + MCP + Custom Tool	自定义 Tool + Function Calling
安全控制	Permission Mode + Hooks	Guardrails（Input/Output）
上下文管理	自动压缩 + 手动压缩	依赖外部管理
可观测性	StreamEvent + Hooks 回调	Tracing span
执行控制	max_turns + max_budget_usd	max_turns + handoff 链
effort 调整	5 级 effort（low → max）	无直接等价物

两种 SDK 的设计哲学差异明显。Claude Agent SDK 倾向于"给开发者最大的控制力"——你可以监听每一条消息、拦截每一个工具调用、精确控制 token 花费。OpenAI Agents SDK 更倾向于"简洁的抽象"——Runner.run() 封装了整个循环，Handoff 让多 Agent 协作变得更直观。

生产环境中的关键工程问题

将 Agent Loop 从 demo 搬到生产环境，需要解决一系列工程问题。

成本控制

Agent Loop 的最大风险是成本失控。一个开放式任务（"改进这个代码库"）可能触发几十个 Turn，每个 Turn 都在消耗 token。

Claude Agent SDK 提供了两层防护：

options = ClaudeAgentOptions(
    max_turns=30,          # 限制最大 Turn 数
    max_budget_usd=0.50,   # 限制最大花费
)

当触发限制时，ResultMessage 的 subtype 会标记为 error_max_turns 或 error_max_budget_usd，应用层可以据此决定是恢复执行还是终止任务。

错误恢复

Agent Loop 中的工具调用可能失败——网络超时、API 限流、文件不存在。Claude Agent SDK 的做法是将工具错误作为 UserMessage 反馈给 LLM，让 LLM 自行决定重试或换策略。这是一个务实的设计：LLM 通常能理解错误信息并做出合理调整。

对于更严重的错误（API 故障、请求取消），ResultMessage.subtype 会标记为 error_during_execution。

权限控制

在生产环境中，不能让 Agent 随意执行命令。Claude Agent SDK 提供了精细的权限控制：

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],  # 只允许只读操作
    disallowed_tools=["Bash", "Write", "Edit"],  # 禁止写操作
    permission_mode="default",  # 未列出的工具需要审批
)

permission_mode 决定了未列出的工具如何处理："default" 要求审批，"acceptEdits" 自动批准文件编辑，"bypassPermissions" 跳过所有检查（仅限隔离环境）。

Hooks 拦截点

Hooks 是 Agent Loop 中的"检查站"，在应用进程中运行，不消耗上下文 token：

Hook	触发时机	典型用途
`PreToolUse`	工具执行前	验证参数、拦截危险命令
`PostToolUse`	工具执行后	审计输出、触发副作用
`UserPromptSubmit`	提交 Prompt 时	注入额外上下文
`Stop`	Agent 完成时	验证结果、保存状态
`PreCompact`	上下文压缩前	归档完整对话记录

PreToolUse Hook 可以短路整个 Loop：如果回调返回拒绝，工具不会执行，LLM 收到拒绝消息后会尝试其他方式。

从单 Agent 到多 Agent：Loop 的扩展

单个 Agent Loop 足以处理大多数任务。但当任务复杂度高、需要多领域专业知识时，多 Agent 架构更高效。

Subagent 模式（Claude Agent SDK）

MERMAID_BLOCK_1

每个 Subagent 启动时拥有独立的上下文窗口，不继承主 Agent 的对话历史。执行完毕后，只有最终结果作为工具调用的返回值回到主 Agent 的上下文中。这意味着主 Agent 的上下文只增加了一段摘要，而非完整的 Subagent 对话过程。

Handoff 模式（OpenAI Agents SDK）

MERMAID_BLOCK_2

Handoff 的特点是上下文传递：当 Triage Agent 把请求交给 Tech Support 时，Tech Support 接手当前的对话上下文继续执行。这和 Subagent 的"独立上下文 + 结果返回"形成了鲜明对比。

如何选择

任务可并行分解 → Subagent 模式（多个 Subagent 并行处理不同子任务）
任务需要流水线处理 → Handoff 模式（一个 Agent 处理完交给下一个）
需要最小化主 Agent 上下文 → Subagent 模式
需要保持对话连贯性 → Handoff 模式

Agent Loop 不是万能的

Anthropic 在 "Building Effective Agents" 一文中明确指出：大多数场景下，简单的 workflow 比复杂的 agentic loop 更合适。Agent Loop 适用于那些无法预先定义完整执行路径的任务——需要根据中间结果动态调整策略的场景。

对于可以明确步骤的流程（数据管道、固定审批流、模板化内容生成），使用确定性 workflow 更稳定、更可预测。只有当任务需要"判断-行动-观察-再判断"的迭代循环时，Agent Loop 才真正发挥价值。

这个判断标准看似简单，实际上决定了整个系统的架构方向：workflow 是"你告诉系统怎么做"，Agent Loop 是"你告诉系统做什么，让它自己决定怎么做"。

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/
每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。

posted @ 2026-06-10 15:50 iTech 阅读(181) 评论(0) 收藏举报

刷新页面返回顶部

iTech's Blog

AI人工智能时代 www.theaiera.cn

深入理解 Agent Loop：从 ReAct 到现代 AI Agent 的核心引擎

深入理解 Agent Loop：从 ReAct 到现代 AI Agent 的核心引擎

ReAct：Agent Loop 的理论起源

从论文到工程：Agent Loop 的通用架构

Claude Agent SDK 的 Agent Loop 实现

执行流程

消息类型

工具系统

上下文窗口管理

OpenAI Agents SDK 的 Agent Loop 实现

执行流程

Handoff 机制

Guardrails 安全护栏

两种 SDK 的对比

生产环境中的关键工程问题

成本控制

错误恢复

权限控制

Hooks 拦截点

从单 Agent 到多 Agent：Loop 的扩展

Subagent 模式（Claude Agent SDK）

Handoff 模式（OpenAI Agents SDK）

如何选择

Agent Loop 不是万能的

公告