LangGraph ReAct代理模板

](https://github.com/webup/langgraph-up-react) ![LangGraph](https://github.com/langchain-ai/langgraph) ![Build](https://github.com/webup/langgraph-up-react/actions/workflows/unit-tests.yml) ![License](https://opensource.org/licenses/MIT) ![README CN](./README_CN.md) ![DeepWiki](https://deepwiki.com/webup/langgraph-up-react) ![Twitter](https://twitter.com/zhanghaili0610)

🎉 最新v0.2.0版本：完整的评估体系和多模型支持！检查发布说明对于所有新功能。

Graph view in LangGraph studio UI

核心逻辑，定义见 src/react_agent/graph.py，演示了一个灵活的ReAct代理，它迭代地推理用户查询并执行操作。该模板具有模块化架构，其中包含共享组件 src/common/，用于外部文档源的MCP集成，以及全面的测试套件。

⭐ 如果你觉得这个repo有用，请将其标记为星号！ 访问我们的网络研讨会系列获取教程和高级LangGraph开发技术。

特性

多提供商模型支持

SiliconFlow集成：完全支持开源模型（Qwen、GLM、DeepSeek等）的中国MaaS平台
Qwen模型：通过以下方式完成Qwen系列支持 langchain-qwq 套装，包括Qwen Plus、Qwen Turbo、QwQ-32B、QvQ-72B
开放人工智能：GPT-4o、GPT-4o-mini等。

- OpenAI兼容：通过自定义API密钥和基本URL支持OpenAI API格式的任何提供商

Anthropic：克劳德四行诗、克劳德3.5俳句等。

生产级代理商评价体系

双重评估框架：图形轨迹评估+多回合聊天模拟，用于综合代理测试
法学硕士作为法官的方法论：具有专业评估系统的特定场景评估标准
多模型基准测试：比较不同模型提供程序和配置的性能
LangSmith集成：通过历史分析和协作功能完成评估跟踪

代理工具集成生态系统

模型上下文协议（MCP）：运行时动态加载外部工具
DeepWiki MCP服务器：用于GitHub存储库文档访问和问答功能的可选MCP工具
网页搜索：内置传统的LangChain工具（Tavily）用于互联网信息检索

LangGraph v0.6功能

\[！注意\] LangGraph v0.6中的新功能: LangGraph上下文取代传统 config['configurable'] 图案。运行时上下文现在传递给 context 论点 invoke/stream，提供了一种更简洁、更直观的配置代理的方法。

上下文驱动配置：运行时上下文通过传递 context 参数而不是 config['configurable']
简化的API：更简洁的接口，用于将运行时配置传递给代理
向后兼容：从旧配置模式逐步迁移路径

LangGraph平台开发支持

本地开发服务器：完整的LangGraph平台开发环境
70+测试用例：单元、集成和端到端测试覆盖率，包括完整的DeepWiki工具加载和执行测试
ReAct循环验证：确保正确的工具模型交互

它做什么

ReAct代理人：

接受用户 怎么翻译 作为输入
查询原因并决定采取行动
使用可用工具执行所选操作
观察行动的结果
重复步骤2-4，直到它可以提供最终答案

该代理具有网络搜索功能和可选的DeepWiki MCP文档工具，但可以很容易地使用自定义工具进行扩展，以适应各种用例。

示例执行跟踪

查看这些LangSmith痕迹，了解代理在实践中的工作方式：

DeepWiki文档查询 -显示代理使用DeepWiki MCP工具查询GitHub存储库文档
Web搜索查询 -演示Tavily网络搜索集成和推理循环

入门指南

紫外线设置（推荐）

安装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

这将安装本地开发所需的一切，包括 ipykernel 因此，您可以在Jupyter笔记本中选择此环境。

复制示例环境文件并填写基本密钥：

cp .env.example .env

环境配置

编辑 .env 使用API密钥文件：

在您的 .env 文件：

# Required: Web search functionality
TAVILY_API_KEY=your-tavily-api-key

# Required: If using Qwen models (default)
DASHSCOPE_API_KEY=your-dashscope-api-key

# Recommended: SiliconFlow platform for multi-model support and evaluation
SILICONFLOW_API_KEY=your-siliconflow-api-key

# Optional: OpenAI model service platform keys
OPENAI_API_KEY=your-openai-api-key
# Optional: If using OpenAI-compatible service platforms
OPENAI_API_BASE=your-openai-base-url

# Optional: If using Anthropic models
ANTHROPIC_API_KEY=your-anthropic-api-key

# Optional: Regional API support for Qwen models  
REGION=international  # or 'cn' for China mainland (default)

# Optional: Always enable DeepWiki documentation tools
ENABLE_DEEPWIKI=true

初级搜索工具用途塔维利.创建API密钥这里.

模型配置

模板使用 qwen:qwen-flash 作为默认模型，定义于 src/common/context.py。您可以通过三种方式配置不同的模型：

运行时上下文 （建议用于程序化使用）
环境变量
LangGraph Studio助手配置

提供程序设置的API密钥

SiliconFlow（推荐用于评估）

SILICONFLOW_API_KEY=your-siliconflow-api-key

获取API密钥： SiliconFlow控制台 -支持Qwen、GLM、DeepSeek等开源模型

开放人工智能

OPENAI_API_KEY=your-openai-api-key

获取API密钥： OpenAI平台

Anthropic

ANTHROPIC_API_KEY=your-anthropic-api-key

获取API密钥： Anthropic 控制台

Qwen模型（默认）

DASHSCOPE_API_KEY=your-dashscope-api-key
REGION=international  # or 'cn' for China mainland

获取API密钥： DashScope控制台

OpenAI兼容提供商

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:
    """Your custom tool implementation."""
    return "Tool result"

# Add to the tools list in get_tools()

定义结构化输出

使用 AgentBaseModel 当您需要结构化响应（LLM工具输出或图形状态）时。它强制执行严格的类型，禁止未知字段，并默认支持别名驱动的序列化：

from pydantic import Field

from common import AgentBaseModel

class Answer(AgentBaseModel):
    display_name: str = Field(alias="displayName")
    score: float

result = Answer(display_name="Curie", score=0.98)
assert result.model_dump(by_alias=True) == {"displayName": "Curie", "score": 0.98}

将共享模式原语保留在 src/common/basemodel.py 因此，提供商集成 src/common/models/ 专注于模型客户端接线。

添加新的MCP工具

集成外部MCP服务器以获得更多功能：

配置MCP服务器 在 src/common/mcp.py:

MCP_SERVERS = {
    "deepwiki": {
        "url": "https://mcp.deepwiki.com/mcp",
        "transport": "streamable_http",
    },
    # Example: Context7 for library documentation
    "context7": {
        "url": "https://mcp.context7.com/sse",
        "transport": "sse",
    },
}

添加服务器功能:

async def get_context7_tools() -> List[Callable[..., Any]]:
    """Get Context7 documentation tools."""
    return await get_mcp_tools("context7")

在上下文中启用 -在中添加上下文标志和加载工具 get_tools() 功能：

# In src/common/tools.py
if context.enable_context7:
    tools.extend(await get_context7_tools())

\[！提示\] 上下文7示例：MCP配置已包含注释的Context7服务器设置。Context7提供了最新的库文档和示例——只需取消注释配置并添加上下文标志即可启用它。

模型配置方法

1.运行时上下文（推荐）

使用新的LangGraph v0.6上下文参数在运行时配置模型：

from common.context import Context
from react_agent import graph

# Configure model via context
result = await graph.ainvoke(
    {"messages": [("user", "Your question here")]},
    context=Context(model="openai:gpt-4o-mini")
)

2.环境变量

设置 MODEL 您的环境变量 .env 文件：

MODEL=anthropic:claude-3.5-haiku

3.LangGraph Studio助手配置

在LangGraph Studio中，通过以下方式配置模型助理管理。创建或更新具有不同模型配置的助手，以便在设置之间轻松切换。

支持的模型格式

模型字符串格式: provider:model-name （跟随LangChain init_chat_model 命名约定）

# OpenAI models
"openai:gpt-4o-mini"
"openai:gpt-4o"

# SiliconFlow models (Chinese MaaS platform)
"siliconflow:Qwen/Qwen3-8B"           # Qwen series efficient model
"siliconflow:THUDM/GLM-4-9B-0414"     # GLM series chat model
"siliconflow:THUDM/GLM-Z1-9B-0414"    # GLM reasoning-enhanced model

# Qwen models (with regional support)
"qwen:qwen-flash"          # Default model
"qwen:qwen-plus"           # Balanced performance
"qwen:qwq-32b-preview"     # Reasoning model
"qwen:qvq-72b-preview"     # Multimodal reasoning

# Anthropic models
"anthropic:claude-4-sonnet"
"anthropic:claude-3.5-haiku"

自定义提示

在中更新系统提示 src/common/prompts.py 或通过LangGraph Studio界面。

修改代理逻辑

调整ReAct循环 src/react_agent/graph.py:

添加新的图形节点
修改条件路由逻辑
添加中断或人在循环中的交互

配置选项

运行时配置在中管理 src/common/context.py:

模型选择
搜索结果限制
工具切换

发展

开发服务器

make dev        # Start LangGraph development server (uv run langgraph dev --no-browser)
make dev_ui     # Start with LangGraph Studio Web UI in browser

测试

make test                    # Run unit and integration tests (default)
make test_unit               # Run unit tests only
make test_integration        # Run integration tests  
make test_e2e               # Run end-to-end tests (requires running server)
make test_all               # Run all test suites

代码质量

make lint       # Run linters (ruff + mypy)
make format     # Auto-format code
make lint_tests # Lint test files only

发展特征

热重载：自动应用本地更改
状态编辑：编辑过去的状态并从特定点重新运行
线程管理：创建新线程或继续现有对话
LangSmith集成：详细的追踪和协作

建筑

该模板使用模块化架构：

src/react_agent/：核心代理图和状态管理
src/common/：共享组件（上下文、模型、工具、提示、MCP集成）
tests/：具有夹具和MCP集成覆盖的全面测试套件
langgraph.json：LangGraph Agent基本配置设置

关键部件：

src/common/mcp.py：外部文件来源的MCP客户管理
src/common/basemodel.py：通过以下方式集中Pydantic配置 AgentBaseModel 用于结构化工具输出
动态刀具加载：基于上下文配置的运行时工具选择
上下文系统：支持环境变量的集中配置

这种结构支持多个代理，并易于在不同实现之间重用组件。

🔬 代理评估系统

为什么评估很重要

代理评估对于生产级AI应用至关重要，因为它：

🎯 验证性能：确保代理在不同场景中正确工作，并适当使用工具
🛡️ 识别安全问题：通过对抗性测试发现潜在漏洞
📊 启用基准测试：提供客观指标来比较不同的模型和配置
🔄 推动改进：提供具体的性能指标来指导代理优化

双重评估框架

该模板采用双重方法提供了一个全面的评估体系：

🎯 图形轨迹评估

测试代理推理模式和工具使用决策：

# Run comprehensive graph trajectory evaluation
make eval_graph

# Test specific models
make eval_graph_qwen    # Qwen/Qwen3-8B model
make eval_graph_glm     # GLM-4-9B-0414 model

评估场景:

简单的问题：“法国的首都是哪里？”-测试基本事实的效率
需要搜索：“人工智能的最新消息是什么？”-测试工具使用和信息综合
多步推理：“可再生能源的优缺点是什么，最新进展是什么？”-测试复杂的分析任务

🔄 多回合聊天模拟

通过角色-角色交互测试对话能力：

# Start development server (required for multi-turn evaluation)
make dev

# Run multi-turn evaluation in another terminal
make eval_multiturn

# Test specific user personas
make eval_multiturn_polite   # Polite user persona
make eval_multiturn_hacker   # Adversarial user persona

角色场景:

写作助理 ×用户角色：专业电子邮件协作
客户服务 ×用户角色：帐户故障排除支持
面试官 ×用户角色：技术面试管理

多提供商模型测试

评估系统支持跨不同模型提供商的测试：

🌍 国际模式：OpenAI GPT-4o、人类克劳德等。
🇨🇳 中国模特：SiliconFlow平台（Qwen、GLM、DeepSeek型号）
🔄 比较分析：供应商之间的并行性能比较
💡 成本优化：为您的用例确定最具成本效益的模型

评估系统详细信息

该评估系统提供了一个全面的代理性能分析框架，其中包含详细的测试场景、评估方法和结果分析。

有关具体的评估结果、测试场景和使用说明，请参阅详细的评估系统文档。

快速开始评估

# Set up required environment variables
export SILICONFLOW_API_KEY="your_siliconflow_api_key"     # For model testing
export TAVILY_API_KEY="your_tavily_api_key"               # For search functionality
export LANGSMITH_API_KEY="your_langsmith_api_key"         # For evaluation tracking

# Run comprehensive evaluation suite
make evals

# Or run evaluations separately
make eval_graph       # Graph trajectory evaluation (runs independently)
make eval_multiturn   # Multi-turn chat evaluation (requires server)

# View release notes and version information
# Visit GitHub Releases page for all version release notes: https://github.com/webup/langgraph-up-react/releases

评估系统特征

🎯 法学硕士作为法官的方法论：特定场景的自定义评估标准
📊 专业报道：详细的分数提取和排名系统
🔍 轨迹归一化：JSON序列化兼容的轨迹处理
📈 LangSmith集成：完整的跟踪和历史分析
⚙️ 集中式配置：中的统一评估设置 config.py

有关详细的评估文件，请参阅： tests/evaluations/README.md

发展与社区

路线图和贡献

📋 ROADMAP.md -当前里程碑和未来计划
🐛 问题和PR欢迎 -通过以下方式帮助我们改进提出问题或提交pull请求
🤖 使用克劳德代码构建 -此模板是使用以下工具积极开发的克劳德代码

参与

我们鼓励社区捐款！无论是：

报告错误或建议功能
添加新工具或模型集成
改进文件
分享您的用例和模板

查看我们的路线图，了解我们下一步的工作以及您如何做出贡献。

了解更多

LangGraph文档 -框架指南和示例
朗史密斯 -追踪与协作平台
重新行动文件 -推理与行为的原创性研究
克劳德代码 -人工智能驱动的开发环境

致谢

这个项目建立在令人惊叹的开源项目和服务平台的肩膀上：

朗链官方项目

LangGraph -强大的代理图构建框架
LangChain -构建LLM应用程序的核心库
代理商评估 -提供法学硕士作为评判方法的代理评估框架
OpenEvals -开放式评估工具和方法
朗史密斯 -LLM应用程序跟踪和调试平台

LangChain社区整合

langchain硅流 -SiliconFlow模型集成，支持开源模型
langchain qwq -Qwen系列阿里云百联平台模型集成

MaaS平台服务

硅流 -提供开源模型的中国MaaS平台
阿里云百联（DashScope） -Qwen系列模型服务平台

查看所有版本更新：

感谢所有贡献者和开源社区！ 🙏

Agent MCP Langgraph

快速接入

详细介绍