内容
# LangGraph 代理模板
完整的基于 LangGraph 的 AI 代理构建启动模板，包含 MCP 集成、聊天界面和 LangSmith 可观察性。
## ✨ 功能特点
- **🤖 LangGraph ReAct 代理** - 具有硬编码提示的即用型代理
- **🔌 MCP 集成** - 模型上下文协议服务器支持（包括文件系统）
- **💬 代理聊天界面** - 基于 Next.js 的网页界面，用于代理交互
- **📊 LangSmith 跟踪** - 内置的可观察性和监控
- **🐳 Docker 就绪** - 带有热重载的容器化开发
- **⚡ 快速设置** - 一条命令启动所有功能
## 🚀 快速开始
### 1. 克隆和配置
```bash
git clone <your-repo>
cd <your-repo>
# 创建环境文件
cp .env.example .env
# 编辑 .env 并添加您的 API 密钥：
# ANTHROPIC_API_KEY=your_anthropic_api_key_here
# LANGSMITH_API_KEY=your_langsmith_api_key_here
```
### 2. 使用 Docker 启动（推荐）
```bash
# 启动代理和聊天界面
docker compose up -d
# 查看日志
docker compose logs -f
# 停止服务
docker compose down
```
**在以下地址访问聊天界面：http://localhost:40004** 🎉
## 🛠️ 自定义指南
### 添加您自己的 MCP 服务器
1. **MCP 配置选项**
系统默认使用 `agent/mcp_integration/servers.json`。要自定义而不影响模板：
```bash
# 在项目根目录创建您自己的 servers.json（被 gitignore）
cp agent/mcp_integration/servers.json servers.json
# 编辑 servers.json 以进行配置
```
**配置优先级：**
- 项目根目录中的 `servers.json`（如果存在）- 您的自定义配置
- `agent/mcp_integration/servers.json` - 默认模板配置
2. **编辑 MCP 配置**
```json
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
"transport": "stdio"
},
"your_server": {
"command": "your-command",
"args": ["your", "args"],
"transport": "stdio"
}
}
}
```
3. **添加环境变量**（如果需要）
```bash
# .env
YOUR_SERVER_TOKEN=your_token_here
```
### 自定义代理
1. **代理行为** - 编辑 `agent/prompts.py`
2. **代理状态** - 修改 `agent/state.py`
3. **代理逻辑** - 更新 `agent/graph.py`
### 修改聊天界面
聊天界面位于 `agent-chat-ui/`。对于开发和构建，请使用提供的容器。
### 添加审批工作流（可选）
模板使用直接工具执行以简化操作。如果您需要对写入操作进行审批：
1. **在 `agent/graph.py` 中创建审批包装类**
2. **在初始化时包装工具**，根据操作类型
3. **使用 LangGraph 中断**暂停执行以进行审批
4. **在您的界面或 CLI 中添加审批处理**
示例审批包装：
```python
from langgraph.types import interrupt
class ApprovalTool(BaseTool):
def _run(self, **kwargs):
if self._is_write_operation():
approval = interrupt({"type": "approval", "tool": self.name})
if not approval.get("approved"):
return "操作已取消"
return self.wrapped_tool.run(**kwargs)
```
## 📁 项目结构
```
/
├── agent/ # 核心代理实现
│ ├── graph.py # LangGraph 代理定义
│ ├── prompts.py # 系统提示（硬编码）
│ ├── config.py # 代理配置选项
│ └── mcp_integration/ # MCP 服务器配置
├── agent-chat-ui/ # Next.js 聊天界面
│ ├── Dockerfile # 聊天界面容器
│ └── .env # 预配置为 localhost
├── infra/ # 基础设施（LangSmith 等）
├── Dockerfile # 代理容器
├── docker-compose.yml # 开发环境，带有热重载（默认）
├── docker-compose.prod.yml # 生产环境 Docker 配置
└── langgraph.json # LangGraph 部署配置
```
## 🧪 开发
### 代码质量
```bash
docker compose exec agent black . && \
docker compose exec agent ruff check . && \
docker compose exec agent mypy .
```
### 评估
1. 创建 YAML 数据集（参见 `infra/langsmith/examples/sample_dataset.yaml` 中的示例）。
2. 在代理容器内运行评估：
```bash
docker compose exec agent python scripts/run_evaluation.py \
--dataset-file infra/langsmith/examples/sample_dataset.yaml \
--json
```
YAML 模式：
```yaml
dataset:
name: my-eval-dataset # 必需
description: 可选描述
judge_model: anthropic:claude-3-5-sonnet-latest
examples:
- inputs:
question: "2 + 2 是多少？"
outputs:
answer: "4"
```
## 📊 可观察性
该模板包含 LangSmith 集成，用于：
- **跟踪** - 每个代理运行都会自动跟踪
- **数据集** - 管理测试用例和评估
- **监控** - 跟踪性能和成本
在以下地址查看您的跟踪：https://smith.langchain.com
## 🚀 部署
### LangGraph 云
```bash
# 部署到 LangGraph 云
langgraph deploy
# 或使用包含的配置
langgraph deploy --config langgraph.json
```
### Docker 生产环境
```bash
# 生产环境构建和运行
docker compose -f docker-compose.prod.yml up -d
# 缩放服务
docker compose -f docker-compose.prod.yml up -d --scale agent=3
```
### 手动 Docker 构建
```bash
# 构建代理镜像
docker build -t my-agent .
# 构建聊天界面镜像
docker build -t my-chat-ui ./agent-chat-ui
# 使用自定义配置运行
docker run -p 40003:40003 --env-file .env my-agent
docker run -p 40004:40004 my-chat-ui
```
## 🤝 贡献
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求
## 📄 许可证
MIT 许可证 - 有关详细信息，请参见 LICENSE 文件。
## 🆘 支持
- 📖 **文档**：查看 `CLAUDE.md` 文件以获取开发上下文
- 🐛 **问题**：通过 GitHub 问题报告错误
- 💬 **讨论**：使用 GitHub 讨论提问
MCP 市场