从零构建 ReAct Agent：Gemini 加持的推理行动框架

你有没有遇到过这种情况：让大语言模型回答一个需要实时信息的问题，结果它一本正经地编了个错误答案？ReAct（Reasoning and Acting）模式就是为了解决这个痛点而生的。

arunpshankar/react-from-scratch 是一个专注于 ReAct 模式实践的教学型代码库，由 Google 工程师 Arun Shankar 创建，通过大量具体示例演示如何让 LLM 在推理过程中主动调用外部工具、获取真实世界信息，从而给出可靠答案。这个项目不是简单的 API 调用封装，而是一套完整的、可从零学习的 ReAct Agent 实现范本。

图1：ReAct Agent 核心工作流 — Think（推理）→ Act（行动）→ Observe（观察）循环迭代

背景：为什么需要 ReAct 模式？

传统 LLM 回答实时问题的困境在于：模型的知识有截止日期，它无法实时联网查询。ReAct 模式的核心思想来自 2022 年 Google 和普林斯顿大学发表的论文《ReAct: Synergizing Reasoning and Acting in Language Models》，其核心洞察是：推理（Reasoning）和行动（Acting）不应该分离，而应该交替进行、相互增强。

具体来说，ReAct Agent 在执行任务时会经历一个 Think → Act → Observe → Think → Act → Observe 的循环：Agent 先「思考」当前任务需要什么信息，然后选择一个工具去「行动」获取信息，将结果作为「观察」反馈给下一轮推理，直到积累足够信息给出最终答案。每一步的中间结果都会被完整记录，形成可审计的推理链路。

作者 Arun Shankar 是 Google 的工程师，他在 Medium 上撰写了配套文章，详细解释了 ReAct 模式的原理以及本项目的实现细节。这个项目的定位介于「教程」和「生产级参考」之间——代码量不大但逻辑完整，配有详细的注释和配套文档，非常适合想深入理解 Agent 内部机制的学习者。

核心架构：四步拆解 Agent 实现

从代码结构来看，本项目将 ReAct Agent 的实现拆解为以下几个关键模块：

1. 推理引擎（src/react/agent.py）

Agent 类的设计非常清晰。它维护一个消息列表（self.messages）记录完整的推理历史，每次迭代时从 prompt 模板加载当前状态，调用 Gemini 生成下一轮推理。模板（data/input/react.txt）采用结构化 JSON 格式，引导模型输出 thought（思考）和 action（行动）或 answer（最终答案）字段。

核心控制流通过 max_iterations=5 限制最大迭代次数，防止无限循环。每个工具（Tool）都是一个可调用对象（Callable），注册到 Agent 的工具字典中，由 tool.use(query) 方法统一执行并捕获异常。值得注意的是，Agent 支持输出完整的执行追踪（trace）到文件，方便调试和可视化。

2. 工具层（src/tools/）

项目内置了两个工具实现：

• SERP 工具（serp.py）：封装 SerpAPI 的 Google 搜索能力，接收查询字符串，返回 JSON 格式的搜索结果。需要用户在 credentials/key.yml 中配置 SerpAPI 的访问密钥。
• 维基百科工具（wiki.py）：使用 wikipediaapi 库查询维基百科，提取词条摘要并以结构化 JSON 格式返回（包含 query、title、summary 三个字段）。

图2：Think-Act-Observe 三阶段循环的直观图示

工具的选择通过 Pydantic 模型（Choice 类）由 LLM 自身决定——模型根据 query 的语义判断应该用 Google 搜索还是维基百科，这种「让模型决定工具」的机制是 ReAct 模式区别于硬编码路由的关键。

3. LLM 调用层（src/llm/gemini.py）

通过 Google Cloud Vertex AI 平台调用 Gemini 模型。代码中设置了：

• temperature=0.0：最大程度减少随机性，保证推理结果可复现
• max_output_tokens=8192：允许模型输出较长推理过程
• 所有安全类别均设置为 BLOCK_NONE：确保工具调用结果不会被安全过滤器意外阻断

4. 非 Agentic 路由（src/tools/manager.py）

除了 Agent 模式，项目还提供了一个「管理器」（Manager）模式，作为对比参考。Manager 模式通过程序化方式路由工具调用，而不是让 LLM 自主决策，适合对工具调用有精确控制需求的场景。这个设计很有教学价值——它展示了在 Agent 化之前，传统程序化方案的处理思路。

技术栈与依赖分析

依赖	版本	作用
google-cloud-aiplatform	1.67.1	Vertex AI 平台 SDK，Gemini 模型调用
wikipedia-api	0.7.1	维基百科查询
google-search-results	2.4.2	SerpAPI 封装
pyyaml	^6.0	配置文件解析
requests	^2.31.0	HTTP 请求
pydantic	（隐式）	数据模型验证

项目使用 Poetry 管理依赖，Python 版本要求 3.8+，依赖数量精简，无重型 ML 框架（如 PyTorch、TensorFlow），非常轻量。

上手体验：门槛在哪里？

优势：

• 代码结构清晰，注释详细，适合学习 ReAct 原理
• 教学导向，有配套 Medium 文章
• Prompt 模板可自由替换，方便实验不同模型

门槛：

• 需要申请 Google Cloud Platform 服务账户并下载 JSON 密钥文件
• 需要注册 SerpAPI 账号并获取 API Key
• 无 Docker 支持，无法开箱即用
• 不支持流式输出，调试需要看 trace 文件

局限与思考

1. 过度依赖外部 API：SerpAPI 是付费服务（免费额度有限），GCP 的 Vertex AI 调用也有成本，生产使用需要估算费用。
2. Prompt 模板硬编码：ReAct 的效果很大程度上取决于 prompt 质量，当前模板以纯文本形式存在，不支持热更新。
3. 工具集有限：目前仅支持 Google 搜索和维基百科，扩展新工具需要修改 agent.py 的注册逻辑。
4. 不支持多轮对话状态持久化：Agent 的 messages 列表在每次运行后不保留，无法基于历史会话继续对话。

行业意义

ReAct 模式是当前 AI Agent 实现的主流范式之一，LangChain、AutoGPT、AutoGen 等主流框架都借鉴了类似的思想。本项目的价值在于用最少的代码量、最直接的方式展示了 ReAct 的核心机制——没有任何隐藏的魔法，完整呈现了从 prompt 模板到工具调用的全链路。对于想从底层理解 Agent 运作原理的开发者，这是一个值得精读的参考实现。

项目当前 169 star、54 forks，作为一个教学导向的小型仓库，增长速度较为平稳。考虑到 Google 工程师的背景以及 ReAct 模式的持续火热，预计会吸引更多关注 LLM 应用开发的用户关注。

一句话总结：如果你想理解 AI Agent 的「思考-行动」循环是如何从零实现的，这个项目是当前最干净的入门级参考之一。