xAgentic - 智能对话系统

xAgentic 是一个基于 LangGraph 的智能对话系统，集成了规划执行、代码生成、搜索工具和 MCP (Model Context Protocol) 支持。该系统采用前后端分离架构，提供流式对话体验和强大的任务执行能力。

🚀 主要功能

核心特性

• 智能规划执行: 基于 LangGraph 的循环式规划执行器，能够将复杂任务分解为可执行的步骤
• 流式对话: 实时流式响应，提供流畅的对话体验
• 代码执行: 集成安全的 Python 代码执行环境，支持代码生成和运行
• 搜索集成: 集成 Tavily 搜索 API，提供实时信息检索能力
• MCP 支持: 支持 Model Context Protocol，可扩展工具和功能
• 多模型支持: 支持 Azure OpenAI、阿里云百炼等多种 LLM 提供商
• 记忆管理: 集成 LangMem 进行对话记忆管理

技术架构

• 后端: FastAPI + LangGraph + LangChain
• 前端: Express.js + 静态 HTML/JS
• AI 框架: LangGraph 状态图 + LangChain 工具链
• 部署: Docker 支持，一键启动脚本

📁 项目结构

xAgentic/
├── xAgentic-backend/          # 后端服务
│   ├── api/                   # API 路由
│   │   ├── chat.py           # 聊天 API
│   │   └── mcp.py            # MCP 管理 API
│   ├── cfg/                  # 配置管理
│   │   ├── config.py         # 配置类
│   │   └── setting.py        # 设置管理
│   ├── graph/                # LangGraph 状态图
│   │   └── plan_executor_graph.py  # 规划执行图
│   ├── llm_provider/         # LLM 提供商
│   ├── mcp_/                 # MCP 客户端和管理
│   ├── memory/               # 记忆管理
│   ├── prompt/               # 提示词模板
│   ├── services/             # 服务管理
│   ├── tools/                # 工具集
│   │   ├── code_tools.py     # 代码执行工具
│   │   ├── search_tools.py   # 搜索工具
│   │   └── time_tools.py     # 时间工具
│   ├── utils/                # 工具函数
│   ├── main.py               # 主入口
│   └── pyproject.toml        # Python 依赖
├── xAgentic-frontend/        # 前端服务
│   ├── public/               # 静态文件
│   │   └── index.html        # 主页面
│   ├── server.js             # Express 服务器
│   └── package.json          # Node.js 依赖
├── start.sh                  # 一键启动脚本
└── README.md                 # 项目说明

🛠️ 安装和配置

环境要求

• Python 3.11+
• Node.js 16+
• 有效的 API 密钥（Azure OpenAI、阿里云百炼、Tavily 等）

1. 克隆项目

git clone <repository-url>
cd xAgentic

2. 配置环境变量

复制示例配置文件并填入你的 API 密钥：

cp xAgentic-backend/sample.env xAgentic-backend/.env

编辑 .env 文件，配置以下参数：

# 服务器配置
HOST=0.0.0.0
PORT=8080

# Azure OpenAI配置
AZURE_OPENAI_API_KEY=your_azure_openai_key
AZURE_OPENAI_ENDPOINT=your_azure_endpoint
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# 阿里云百炼 API KEY
DASHSCOPE_API_KEY=your_dashscope_key

# 模型配置
FAST_LLM=dashscope:qwen-plus
STRATEGIC_LLM=dashscope:qwen-max
CODING_LLM=dashscope:qwen3-coder-plus
EMBEDDING=dashscope:text-embedding-v4

# Tavily 搜索 API
TAVILY_API_KEY=your_tavily_key

# LangSmith 配置（可选）
LANGSMITH_API_KEY=your_langsmith_key
LANGSMITH_PROJECT=xagentic
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_TRACING_V2=true

3. 安装依赖

后端依赖

cd xAgentic-backend
pip install -e .

前端依赖

cd xAgentic-frontend
npm install

🚀 启动服务

方式一：一键启动（推荐）

chmod +x start.sh
./start.sh

方式二：手动启动

启动后端

cd xAgentic-backend
python main.py

启动前端

cd xAgentic-frontend
npm start

访问地址

• 前端界面: http://localhost:3000
• 后端 API: http://localhost:8080
• API 文档: http://localhost:8080/docs

💡 使用说明

基本对话

1. 打开浏览器访问 http://localhost:3000
2. 在输入框中输入你的问题或任务
3. 系统会自动进行规划并执行相应步骤
4. 查看流式响应和详细的执行过程

支持的任务类型

• 代码生成和执行: 生成 Python 代码并安全执行
• 信息搜索: 实时搜索最新信息
• 数据分析: 处理和分析数据
• 文件操作: 读取、写入和操作文件
• 复杂任务规划: 将复杂任务分解为多个步骤执行

MCP 工具扩展

系统支持通过 MCP (Model Context Protocol) 扩展功能：

1. 在 MCP 配置页面添加新的工具服务器
2. 配置工具的参数和权限
3. 重启服务以加载新工具

🔧 API 接口

聊天接口

POST /api/chat/stream
Content-Type: application/json

{
  "message": "你的问题或任务",
  "conversation_history": ["历史对话"],
  "mcp_configs": [{"tool": "配置"}]
}

健康检查

GET /health

MCP 配置管理

GET /api/mcp/configs          # 获取 MCP 配置
POST /api/mcp/configs         # 更新 MCP 配置

🏗️ 架构详解

规划执行流程

1. 任务分析: 分析用户输入，理解任务需求
2. 制定计划: 将复杂任务分解为可执行的步骤
3. 循环执行:
   • 检查当前步骤的不确定性
   • 如需要，向用户确认
   • 执行步骤并收集结果
4. 生成回复: 整合所有步骤结果，生成最终回复

状态管理

系统使用 LangGraph 的状态图管理对话状态：

• messages: 对话消息历史
• execution_plan: 执行计划
• current_step: 当前执行步骤
• step_results: 步骤执行结果
• final_response: 最终回复

工具集成

• 代码工具: 基于 langchain-sandbox 的安全代码执行
• 搜索工具: Tavily API 集成
• 时间工具: 时间相关操作
• MCP 工具: 可扩展的工具协议

🔒 安全特性

• 代码沙箱: 使用 Pyodide 沙箱安全执行 Python 代码
• 输入验证: Pydantic 模型验证所有输入
• 错误处理: 完善的异常处理和日志记录
• CORS 配置: 安全的跨域请求配置

📊 监控和日志

• 统一日志: 基于 Python logging 的统一日志系统
• LangSmith 集成: 可选的链路追踪和监控
• 健康检查: 服务状态监控接口
• 错误日志: 详细的错误记录和调试信息

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

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

🆘 常见问题

Q: 如何更换 LLM 提供商？

A: 修改 .env 文件中的模型配置，支持 Azure OpenAI、阿里云百炼等。

Q: 如何添加自定义工具？

A: 可以通过 MCP 协议添加自定义工具，或在 tools/ 目录下添加新的工具模块。

Q: 代码执行是否安全？

A: 是的，系统使用 Pyodide 沙箱环境，限制网络访问和文件系统操作。

Q: 如何调试问题？

A: 查看 logs/ 目录下的日志文件，或启用 LangSmith 追踪。

📞 支持

如有问题或建议，请：

1. 查看 Issues 页面
2. 创建新的 Issue 描述问题
3. 提供详细的错误日志和环境信息

---

xAgentic - 让 AI 对话更智能，让任务执行更高效！