LangGraph MCP ReAct 智能体

一个基于 LangGraph 和 MCP（Model Context Protocol）的 ReAct（Reasoning and Acting）智能体实现，支持多种工具调用和复杂推理任务。

🌟 特性

🧠 ReAct 架构: 实现思考-行动-观察-完成的推理循环
🔧 MCP 工具集成: 支持标准化的工具协议，安全可靠
📊 多种工具: 内置计算器、文本处理、时间查询、数据分析、文件操作等工具
🔄 混合工具架构: 同时支持 MCP 工具和传统 Python 函数
🎯 状态管理: 基于 LangGraph 的状态图管理
🚀 高性能: 支持异步处理和并发执行
🛡️ 错误处理: 完善的错误处理和重试机制
📝 详细日志: 完整的执行过程记录

📁 项目结构

react_example/
├── src/                              # 源代码目录
│   ├── mcp_langgraph_react_agent.py  # 主智能体实现
│   ├── mcp_tools_client.py           # MCP 工具客户端
│   ├── mcp_tools_server.py           # MCP 工具服务器
│   └── model_controller.py           # LLM 控制器
├── docs/                             # 文档目录
│   ├── api_reference.md              # API 参考文档
│   └── tutorial.md                   # 详细教程
├── examples/                         # 示例代码
├── test/                            # 测试文件
├── requirements.txt                 # 项目依赖
└── README.md                        # 项目说明

🚀 快速开始

1. 环境准备

# 创建 conda 环境
conda create -n react python=3.10
conda activate react

# 安装依赖
cd ~/projects/react_example
pip install -r requirements.txt

重要说明

⚠️ 本项目必须遵循以下运行规则：

工作目录：必须在 ~/projects/react_example 目录下运行所有程序
运行方式：使用 python -m 方式运行模块，不要直接运行 .py 文件
导入方式：项目内部使用相对导入，确保模块间正确引用

# ✅ 正确的运行方式
cd ~/projects/react_example
python -m examples.quick_start
python -m test.test_agent

# ❌ 错误的运行方式
python examples/quick_start.py
python test/test_agent.py

2. 配置 API 密钥

# 设置 DeepSeek API 密钥
export DPSK_API_KEY="your_deepseek_api_key_here"

3. 基础使用

#!/usr/bin/env python3
# 文件: examples/quick_start.py

from src.model_controller import LLMController
from src.mcp_langgraph_react_agent import LangGraphMCPReActAgent

def main():
    # 创建 LLM 控制器
    llm = LLMController(backend="dpsk")
    
    # 创建智能体
    server_script = "src/mcp_tools_server.py"
    agent = LangGraphMCPReActAgent(
        llm_controller=llm,
        mcp_server_script=server_script,
        max_steps=8,
        temperature=0.7
    )
    
    try:
        # 解决问题
        question = "计算 (10+20)*3 的结果，然后分析文本 'Hello World' 的长度"
        answer = agent.solve(question)
        print(f"答案: {answer}")
    finally:
        # 清理资源
        agent.disconnect()

if __name__ == "__main__":
    main()

运行方式：

# 在项目根目录下运行
cd ~/projects/react_example
python -m examples.quick_start

4. 运行测试

# 测试 MCP 服务器
python src/mcp_tools_server.py

# 测试 MCP 客户端
python src/mcp_tools_client.py

# 测试完整智能体
python src/mcp_langgraph_react_agent.py

🛠️ 可用工具

MCP 工具

| 工具名称 | 功能描述 | 示例用法 | |---------|---------|----------| | calculator | 数学计算 | calculator[2+3*4] | | text_processor | 文本处理 | text_processor[{"text": "Hello", "operation": "length"}] | | time_query | 时间查询 | time_query[{"query_type": "current_time"}] | | data_analyzer | 数据分析 | data_analyzer[{"data": "1,2,3,4,5", "operation": "mean"}] | | file_operations | 文件操作 | file_operations[{"operation": "list"}] |

文本处理操作

length: 计算文本长度
upper: 转换为大写
lower: 转换为小写
reverse: 反转文本
word_count: 统计单词数量

数据分析操作

basic_stats: 基本统计（最大值、最小值、数量）
mean: 平均值
median: 中位数
std: 标准差
sum: 求和

🏗️ 技术架构

ReAct 推理循环

用户问题 → Think节点 → Act节点 → Observe节点 → Think节点 → ... → Finish节点 → 最终答案
              ↓         ↓          ↓
            思考过程   工具调用    结果分析

核心组件

LangGraphMCPReActAgent: 主智能体类，管理整个推理流程
MCPToolsManager: MCP 工具管理器，处理工具发现和调用
LLMController: LLM 控制器，支持多种模型后端
AgentState: 状态管理，跟踪推理过程中的所有信息

状态图节点

think: 思考节点，分析问题并制定计划
act: 行动节点，执行工具调用
observe: 观察节点，分析工具结果
finish: 完成节点，生成最终答案
error_handler: 错误处理节点

📚 文档

API 参考文档: 详细的 API 说明和参数介绍
教程文档: 从入门到高级的完整教程

🧪 测试

项目包含完整的测试套件：

# 运行所有测试（在项目根目录下）
cd ~/projects/react_example
python -m pytest test/ -v

# 运行特定测试
python -m pytest test.test_agent -v

# 运行覆盖率测试
python -m pytest --cov=src test/

🔧 高级用法

自定义工具

# 添加自定义工具
def weather_tool(location):
    """查询天气信息"""
    # 实现天气查询逻辑
    return f"{location}的天气：晴天，25°C"

# 注册工具
agent.add_legacy_tool("weather", weather_tool, "查询城市天气")

自定义提示词

class CustomReActAgent(LangGraphMCPReActAgent):
    def _generate_think_prompt(self, state):
        # 自定义思考提示词
        return f"作为专业助手，请分析问题：{state['question']}"

状态持久化

from langgraph.checkpoint.memory import MemorySaver

# 添加检查点支持
memory = MemorySaver()
agent.graph = agent.graph.compile(checkpointer=memory)

🐛 故障排除

常见问题

MCP 服务器连接失败

# 检查服务器脚本
python src/mcp_tools_server.py

API 密钥错误

# 设置环境变量
export DPSK_API_KEY="your_api_key"

依赖包缺失

# 重新安装依赖
pip install -r requirements.txt

调试模式

import logging
logging.basicConfig(level=logging.DEBUG)

# 启用详细日志
agent = LangGraphMCPReActAgent(llm, server_script, verbose=True)

🤝 贡献指南

Fork 项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开 Pull Request

📋 开发计划

[ ] 支持更多 LLM 后端（OpenAI、Claude、Gemini）
[ ] 添加图像处理工具
[ ] 实现工具组合和链式调用
[ ] 支持多智能体协作
[ ] 添加 Web UI 界面
[ ] 性能优化和缓存机制

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

LangGraph - 状态图框架
MCP - 模型上下文协议
FastMCP - MCP 服务器实现
DeepSeek - LLM 服务提供商

📞 联系方式

如有问题或建议，请通过以下方式联系：

提交 Issue: GitHub Issues
邮箱: csjsa@zju.edu.cn

⭐ 如果这个项目对你有帮助，请给它一个星标！

MCP Servers