Agent Flow

AI 智能体引擎 — 双版本 ReAct Agent 对照实现 (从手写推理循环到 LangGraph 编排的工程实践)

---

🏗️ 项目架构

agent-flow/
├── app/
│   ├── main.py                  # FastAPI 入口（端口 8001）
│   ├── config.py                # 配置（从 .env 读取）
│   ├── api/
│   │   └── routes_agent.py      # 双版本 Agent 执行路由
│   ├── core/
│   │   ├── agent_runner.py      # 手写原生 ReAct 推理决策循环
│   │   ├── langchain_agent.py   # LangGraph 结构化工具调用 Agent
│   │   ├── llm_client.py        # LLM 大模型调用封装
│   │   ├── prompts.py           # 核心 System Prompt 构建
│   │   └── state.py             # Agent 状态定义
│   ├── tools/
│   │   ├── registry.py          # 工具注册中心（动态注册与注入）
│   │   ├── rag_search.py        # RAG 企业知识库检索工具
│   │   └── base.py              # 基础工具抽象类
│   └── schemas/
│       └── agent.py             # 请求/响应 Pydantic Schema

---

⚡ 核心亮点

1. 手写原生 ReAct 循环（展示核心原理解析力）

• 无框架依赖：摆脱 LangChain 依赖，从零手写 Thought → Action → Observation 推理闭环，真实演绎 Agent 决策过程。
• 文本决策解析：手写高效的正则表达式，精准捕捉和解析 LLM 生成的决策行动（Action）与工具参数。
• 执行退避保护：设置最大迭代步数限制（Max Steps = 10），当发生决策漂移或陷入无限循环时，能够安全捕获异常，并优雅退避为大语言模型直答模式，确保线上服务的高可用性。

2. LangGraph 状态图对照实现（展示前沿框架应用力）

• 状态流编排：基于 LangGraph 定义精确的状态图，将 Agent 推理过程解耦为节点 (Nodes) 与条件边 (Conditional Edges)。
• 结构化工具调用 (Structured Tool-calling)：使用 LLM 兼容的结构化 Function-calling 语法代替纯文本解析，识别率与容错率大幅提升。
• 状态追踪与回放：图形化编排自然支持会话状态的持久化、回滚与推理链路重放。

3. 双端点架构对照设计

通过暴露两个截然不同的 API 接口，清晰展示了从手写基础原理到工业级图编排框架的演进深度：

• POST /api/v1/agent/run：指向原生文本 ReAct 执行器。
• POST /api/v1/agent/langchain/run：指向 LangGraph 节点图执行器。

4. 动态工具注册系统

• 装饰器零改动注册：采用装饰器模式实现工具的定义与注册。当开发 RAG 知识库检索、外部计算器或 API 工具时，仅需使用 @register_tool 进行声明。
• 动态 Prompt 生成：系统运行时会自动提取工具的 Docstring 和 Pydantic Schema，将其动态注入到 Agent 的 System Prompt 中。
• 开闭原则工程实践：新增或删除工具不需要修改 Agent 执行器的核心推理代码，极具工程扩展性。

---

🚀 快速开始

1. 配置文件

Copy-Item .env.example .env
# 编辑 .env 文件，填入您的 API Key 和 RAG 检索引擎服务地址

2. 安装环境

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

3. 启动服务（默认监听端口 8001）

uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

---

📡 API 使用说明

1. 路由接口

接口地址	方法	功能描述
/health	GET	健康检查接口
/api/v1/agent/run	POST	调用手写版文本 ReAct Agent
/api/v1/agent/langchain/run	POST	调用 LangGraph 编排版 Agent

2. 请求报文示例

{
  "query": "帮我查询关于向量库检索的优化方法",
  "session_id": "session_uuid_12345",
  "max_steps": 6
}

---

⚙️ 环境变量配置说明

变量键名	功能描述	默认值
LLM_API_KEY	大语言模型 API 密钥 (必填)	无
LLM_BASE_URL	API 转发或直连地址	https://api.openai.com/v1
LLM_MODEL	Agent 调用的决策模型	gpt-4o
RAG_ENGINE_URL	关联的 rag-engine 服务地址	http://localhost:8000
MAX_STEPS	允许 Agent 迭代的最大思考次数限制	6