基于 LangGraph 构建的 ReAct 智能体 模板，专为本地开发者设计，与 LangGraph Studio 无缝协作。ReAct 智能体是简洁的原型智能体，可以灵活扩展支持多种工具。
🎉 最新 v0.2.0 版本：完整的评估系统和多模型支持！查看 发布说明 了解所有新功能详情。
核心逻辑定义在 src/react_agent/graph.py 中，展示了一个灵活的 ReAct 智能体，能够迭代地推理用户查询并执行操作。模板采用模块化架构，在 src/common/ 中包含共享组件，集成 MCP 外部文档源，并提供完整的测试套件。
如果此项目对您有帮助，请点个 ⭐ Star，万分感谢！ 同时，您还可以访问我们的 B 站空间 获取教程和 LangGraph 高级开发技巧。
掌握 Agent 技术先机！从掌握 LangGraph 开始！我们的新书《LangGraph实战》现已出版，点击查看详情 ❤️
欢迎您扫描下方二维码加入我们的技术讨论群：
- 硅基流动 SiliconFlow: 完整的中国大模型云平台集成，支持 Qwen、GLM、DeepSeek 等国产开源模型
- 通义千问系列模型: 通过
langchain-qwq包提供 Qwen 系列模型支持，包括 Qwen-Plus、Qwen-Turbo、QwQ-32B、QvQ-72B - OpenAI 兼容: 支持 GPT-4o、GPT-4o-mini 等模型，以及任何 OpenAI API 格式的提供商
- 双重评估框架: 图轨迹评估 + 多轮对话仿真，全方位测试智能体性能
- LLM-as-Judge 方法论: 基于场景特定评判标准的专业评估系统
- 硅基流动模型评估: 使用国产开源模型进行智能体性能基准测试，提供多种 10B 以下模型便于测试评估
- LangSmith 集成: 完整的评估跟踪和历史分析系统
- 模型上下文协议（MCP，Model Context Protocol）: 运行时动态外部工具加载
- DeepWiki MCP 服务器: 可选加载的 MCP 工具，用于 GitHub 仓库文档访问和问答功能
- Web 搜索: 内置传统的 LangChain 工具（Tavily），用于互联网信息的检索
Note
LangGraph v0.6 新功能: LangGraph Context 替代了传统的 config['configurable'] 模式。运行时上下文现在通过 invoke/stream 的 context 参数传递，提供了更清洁、更直观的智能体配置方式。
- 上下文驱动配置: 通过
context参数传递运行时上下文，而不是config['configurable'] - 简化的 API: 为智能体传递运行时配置提供更清洁的接口
- 向后兼容: 从旧配置模式的渐进迁移路径
- 本地开发服务器: 完整的 LangGraph Platform 开发环境
- 70+ 测试用例: 单元、集成和端到端测试覆盖，完整测试 DeepWiki 工具加载和执行
- ReAct 循环验证: 确保正确的工具-模型交互
- 使用 Claude Code 开发: 本模板使用先进的 AI 开发环境构建
- 持续迭代: 我们将持续完善和添加新模板
- 社区驱动: 为不同场景的 LangGraph 开发提供更多选择
ReAct 智能体的工作流程：
- 接收用户查询作为输入
- 推理需要执行什么操作来回答查询
- 使用可用工具执行选定的操作
- 观察操作结果
- 重复步骤 2-4 直到能够提供最终答案
智能体内置 Web 搜索功能和可选的 DeepWiki MCP 文档工具，可轻松扩展以支持各种用例的自定义工具。
查看这些 LangSmith 追踪记录，了解智能体的实际工作原理：
- DeepWiki 文档查询 - 展示智能体使用 DeepWiki MCP 工具查询 GitHub 仓库文档
- Web 搜索查询 - 演示 Tavily Web 搜索集成和推理循环
- 安装 uv（如果尚未安装）：
curl -LsSf https://astral.sh/uv/install.sh | sh- 克隆仓库：
git clone https://github.com/webup/langgraph-up-react.git
cd langgraph-up-react- 安装依赖（包括开发依赖）：
uv sync --dev- 复制示例环境文件并填入必要的 API 密钥：
cp .env.example .env- 编辑
.env文件，添加您的 API 密钥：
# 必需：阿里云百炼平台模型
REGION=cn # 或 'international' 使用国内端点（默认）
# 必需：搜索功能所需
TAVILY_API_KEY=your_tavily_api_key
# 必需：如使用通义千问模型（默认）
DASHSCOPE_API_KEY=your_dashscope_api_key
# 推荐：硅基流动大模型云平台（用于评估和多模型支持）
SILICONFLOW_API_KEY=your_siliconflow_api_key
# 可选：OpenAI 模型服务平台密钥
OPENAI_API_KEY=your_openai_key
# 可选：如使用兼容 OpenAI 模型接口的服务平台
OPENAI_API_BASE=your_openai_base
# 可选：始终启用 DeepWiki 文档工具
ENABLE_DEEPWIKI=true主要搜索工具使用 Tavily。在 此处 创建 API 密钥。
模板使用 qwen:qwen-flash 作为默认模型，定义在 src/common/context.py 中。您可以通过三种方式配置不同的模型：
- 运行时上下文（编程使用推荐）
- 环境变量
- LangGraph Studio 助手配置
使用新的 LangGraph v0.6 上下文参数在运行时配置模型：
from common.context import Context
from react_agent import graph
# 通过上下文配置模型
result = await graph.ainvoke(
{"messages": [("user", "您的问题")]},
context=Context(model="openai:gpt-4o-mini")
)在 .env 文件中设置 MODEL 环境变量：
MODEL=anthropic:claude-3.5-haiku在 LangGraph Studio 中，通过 Assistant 配置模型。创建或更新具有不同模型配置的助手，以便在不同设置之间轻松切换。
模型字符串格式：提供商:模型名称（遵循 LangChain init_chat_model 命名约定）
# OpenAI 模型
"openai:gpt-4o-mini"
"openai:gpt-4o"
# 硅基流动模型（国产开源模型云平台）
"siliconflow:Qwen/Qwen3-8B" # Qwen 系列高效模型
"siliconflow:THUDM/GLM-4-9B-0414" # GLM 系列对话模型
"siliconflow:THUDM/GLM-Z1-9B-0414" # GLM 推理增强模型
# 通义千问模型（支持区域配置）
"qwen:qwen-flash" # 默认模型
"qwen:qwen-plus" # 平衡性能
"qwen:qwq-32b-preview" # 推理模型
"qwen:qvq-72b-preview" # 多模态推理
# Anthropic 模型
"anthropic:claude-4-sonnet"
"anthropic:claude-3.5-haiku"SILICONFLOW_API_KEY=your-siliconflow-api-key获取 API 密钥：硅基流动控制台 - 支持 Qwen、GLM、DeepSeek 等国产开源模型
DASHSCOPE_API_KEY=your-dashscope-api-key
REGION=cn # 或 'international' 使用国际端点获取 API 密钥：DashScope 控制台
OPENAI_API_KEY=your-openai-api-key获取 API 密钥：OpenAI 平台
ANTHROPIC_API_KEY=your-anthropic-api-key获取 API 密钥：Anthropic 控制台
OPENAI_API_KEY=your-provider-api-key
OPENAI_API_BASE=https://your-provider-api-base-url/v1支持 SiliconFlow、Together AI、Groq 和其他 OpenAI 兼容 API。
在 src/common/tools.py 中扩展智能体功能：
async def my_custom_tool(input: str) -> str:
"""自定义工具描述。"""
# 您的工具逻辑
return "工具输出"当需要返回结构化响应（例如工具输出或图状态）时，请使用 AgentBaseModel。它默认启用严格类型检查、禁止未知字段，并支持字段别名序列化：
from pydantic import Field
from common import AgentBaseModel
class Answer(AgentBaseModel):
display_name: str = Field(alias="displayName")
score: float
result = Answer(display_name="居里", score=0.98)
assert result.model_dump(by_alias=True) == {"displayName": "居里", "score": 0.98}共享的 schema 基类请放在 src/common/basemodel.py 中，以保持 src/common/models/ 目录专注于模型客户端集成。
集成外部 MCP 服务器以获得更多功能：
- 配置 MCP 服务器，在
src/common/mcp.py中：
MCP_SERVERS = {
"deepwiki": {
"url": "https://mcp.deepwiki.com/mcp",
"transport": "streamable_http",
},
# 示例：Context7 库文档服务
"context7": {
"url": "https://mcp.context7.com/sse",
"transport": "sse",
},
}- 添加服务器函数：
async def get_context7_tools() -> List[Callable[..., Any]]:
"""获取 Context7 文档工具。"""
return await get_mcp_tools("context7")- 在上下文中启用 - 添加上下文标志并在
get_tools()函数中加载工具：
# 在 src/common/tools.py 中
if context.enable_context7:
tools.extend(await get_context7_tools())Tip
Context7 示例：MCP 配置中已包含注释的 Context7 服务器设置。Context7 提供最新的库文档和示例 - 只需取消注释配置并添加上下文标志即可启用。
编辑 src/common/prompts.py 中的默认系统提示。
make dev # 启动 LangGraph 开发服务器（uv run langgraph dev --no-browser)
make dev_ui # 启动带 LangGraph Studio Web UI 界面的服务器make test # 运行单元和集成测试（默认）
make test_unit # 仅运行单元测试
make test_integration # 运行集成测试
make test_e2e # 运行端到端测试（需要运行服务器）
make test_all # 运行所有测试套件make lint # 运行 linter（ruff + mypy）
make format # 使用 ruff 自动格式化代码- 可视化图结构: 查看智能体的执行流程
- 实时调试: 逐步执行和状态检查
- 交互式测试: 直接在 Studio 中测试智能体
模板采用模块化架构：
src/react_agent/: 核心智能体图和状态管理src/common/: 共享组件（上下文、模型、工具、提示、MCP 集成）tests/: 完整测试套件，包含 fixtures 和 MCP 集成覆盖langgraph.json: LangGraph Agent 的各项基础配置
关键组件：
src/common/mcp.py: 外部文档源的 MCP 客户端管理- 动态工具加载: 基于上下文配置的运行时工具选择
- 上下文系统: 支持环境变量的集中化配置
此架构支持多智能体和不同实现间的轻松组件重用。
智能体评估是生产级 AI 应用的关键环节，它能够：
- 🎯 验证性能: 确保智能体在不同场景下的推理和工具使用能力
- 🛡️ 安全检测: 通过对抗性测试发现潜在的安全边界问题
- 📊 基准对比: 量化不同模型和配置的性能差异
- 🔄 持续改进: 为智能体优化提供客观的性能指标
本模板提供业界领先的综合评估系统，采用双重评估方法论：
测试智能体的推理模式和工具使用决策：
# 运行所有模型和场景的图轨迹评估
make eval_graph
# 测试特定硅基流动模型
make eval_graph_qwen # Qwen/Qwen3-8B 模型
make eval_graph_glm # GLM-4-9B-0414 模型评估场景：
- 简单问题: "法国的首都是什么？" - 测试基础事实的效率回答
- 搜索必需: "人工智能的最新新闻是什么？" - 测试工具使用和信息综合
- 多步推理: "可再生能源的优缺点和最新发展是什么？" - 测试复杂分析任务
测试对话能力和角色适应性：
# 启动开发服务器（多轮评估需要）
make dev
# 在另一个终端运行多轮评估
make eval_multiturn
# 测试特定用户角色
make eval_multiturn_polite # 礼貌用户角色
make eval_multiturn_hacker # 对抗性用户角色角色场景：
- 写作助手 × 用户角色：专业邮件撰写协作
- 客服代表 × 用户角色：账户问题解决支持
- 面试官 × 用户角色：技术面试流程管理
使用中国领先的大模型云平台进行评估：
- 🇨🇳 国产模型: 使用 Qwen/Qwen3-8B、GLM-4-9B-0414 等国产开源模型
- 🏅 先进评估器: GLM-Z1-9B-0414 推理模型作为 LLM 评判器
- 🧪 丰富选择: 提供多种 10B 以下开源模型，便于开展评估测试实验
评估系统提供了完整的智能体性能分析框架，包含详细的测试场景、评估方法论和结果分析。
要了解具体的评估结果、测试场景和使用方法，请参阅详细的评估系统文档。
# 设置必需的环境变量
export SILICONFLOW_API_KEY="your_siliconflow_api_key"
export TAVILY_API_KEY="your_tavily_api_key"
export LANGSMITH_API_KEY="your_langsmith_api_key"
# 运行综合评估套件
make evals
# 或分别运行各类评估
make eval_graph # 图轨迹评估（独立运行）
make eval_multiturn # 多轮对话评估（需要服务器）访问 GitHub Releases 页面查看所有版本发布说明：https://github.com/webup/langgraph-up-react/releases
Tip
硅基流动 API 密钥: 在 硅基流动控制台 获取 API 密钥，支持 Qwen、GLM、DeepSeek 等多种国产开源模型。
- 🎯 LLM-as-Judge 方法论: 场景特定的自定义评判标准
- 📊 专业报告系统: 详细的评分提取和排名系统
- 🔍 轨迹标准化: 兼容 JSON 序列化的轨迹处理
- 📈 LangSmith 集成: 全面的跟踪和历史分析
- ⚙️ 集中化配置:
config.py中的统一评估设置
详细评估文档请参见：tests/evaluations/README.md
- 📋 ROADMAP.md - 当前里程碑和未来规划
- 🐛 欢迎 Issues 和 PR - 通过 提交 issue 或提交 pull request 帮助我们改进
- 🤖 使用 Claude Code 开发 - 本模板使用 Claude Code 积极开发维护
我们鼓励社区贡献！无论是：
- 报告 bug 或建议新功能
- 添加新工具或模型集成
- 改进文档
- 分享您的用例和模板
查看我们的路线图，了解下一步工作计划以及如何参与贡献。
- LangGraph 文档 - 框架指南和示例
- 通义千问模型文档 - 模型 API 和使用指南
- MCP 协议 - 了解模型上下文协议
- ReAct 论文 - 原始研究论文
- Claude Code - AI 驱动的开发环境
本项目的构建离不开以下优秀的开源项目和服务平台：
- LangGraph - 强大的智能体图构建框架
- LangChain - 构建 LLM 应用的核心库
- AgentEvals - 智能体评估框架，提供 LLM-as-Judge 方法论
- OpenEvals - 开放评估工具和方法
- LangSmith - LLM 应用跟踪和调试平台
- langchain-siliconflow - 硅基流动模型集成，提供国产开源模型支持
- langchain-qwq - 阿里云百炼平台模型集成，支持通义千问系列
- 硅基流动 (SiliconFlow) - 提供国产开源模型的 MaaS 平台（中国用户 10B 以下模型永久免费）
- 阿里云百炼 (DashScope) - 通义千问系列模型服务平台
查看所有版本更新详情：📋 GitHub Releases
感谢所有贡献者和开源社区的支持！🙏