基于 ReAct 架构的智能体最小实现

ReAct = Reasoning + Acting（推理与行动交错），与前端框架 React 无关。

项目介绍

这是一个用 Python 写的 ReAct 风格智能体：针对你指定的本地项目目录，让大模型在循环里交替进行「推理 → 调用工具 → 读回真实结果」，直到产出 <final_answer>。依赖少、单文件入口清晰，适合用来理解 Agent 主循环和工具调用，再对照论文或接入更重的编排框架。

Minimal · Loop · Agent

关键词	在本仓库里的含义
Minimal	单入口 agent.py、少量依赖（openai、click、python-dotenv），用 XML 标签解析模型输出，便于对照论文与调试，而非堆框架。
Loop	固定主循环：模型输出 → 解析 <action> → 工具执行 → <observation> 回灌 → 再请求模型，直到出现 <final_answer>。
Agent	在指定项目目录内通过工具与环境交互（读改文件、终端、按需拉网页），用真实观察闭环，而不是一次性生成答案。

---

做什么

在「思考 → 调工具 → 观察 → 再思考」里完成任务：提示里会带上该目录下的文件列表；工具包括 read_file、write_to_file、run_terminal_command、fetch_url。执行 run_terminal_command 前会询问 Y/N，其余工具直接执行。

和常见产品的关系

ReAct 的本质是推理与外部操作交错，并用真实观察闭环。同类思路见于带工具的对话产品（ChatGPT / Copilot / Claude 等）、编码 Agent（Cursor、Copilot Agent 等），以及 LangChain/LangGraph、CrewAI 等框架。本仓库用 XML 解析步骤；线上多用 Function Calling 或编排，循环思想一致。

架构（摘要）

• 入口：uv run agent.py <项目目录> → 读任务 → ReActAgent.run。
• 模型：OpenAI 兼容接口调 Gemini（默认 gemini-2.5-flash，可用环境变量 GEMINI_MODEL 覆盖），密钥 GEMINI_API_KEY。
• 提示：prompt_template.py 注入工具列表、OS、目录文件列表；模型输出 <thought>、<action> 或 <final_answer>，工具结果以 <observation> 写入对话。
• 主循环：见下图。

flowchart TD
  T[用户任务] --> M[模型: thought + action 或 final_answer]
  M --> D{含 final_answer?}
  D -->|是| E[结束]
  D -->|否| P[解析 action]
  P --> X[执行工具]
  X --> O[observation 追加到消息]
  O --> M

Loading

等价文字流：

用户任务 → 模型(thought + action / final_answer) → 工具 → observation → … → final_answer

运行

1. 安装 uv。
2. 在本目录创建 .env：GEMINI_API_KEY=你的密钥（可选 GEMINI_MODEL=...）。若改用 OpenRouter 等，需在 agent.py 中修改 base_url 与密钥读取方式。
3. 执行：

uv run agent.py snake

将 snake 换成任意项目目录路径即可。