内容
# LangGraph 生产骨架
用于部署具有状态的多轮 AI 代理的企业级框架。该骨架提炼了在 5 家财富公司内部 AI 基础设施中开发和验证的工程模式，为更广泛的开发者社区提供通用解决方案。
## 概述
在笔记本电脑或周末原型中构建 LangGraph 代理非常简单。但是，要为数十万名员工提供可靠的服务，并具备多轮记忆、实时流媒体、并行工具执行和零停机部署，则需要根本不同的方法。该项目提供了这一基础。
代码库解决了 LangGraph 优秀的文档示例与生产系统所需的工程严谨性之间的差距。它不是教程，而是实际运行的架构。
该项目中的模式直接解决了这一差距：
- **具有状态的多轮代理**，在会话之间保持连贯的对话上下文，使知识工作者能够与 AI 系统进行扩展的、富有成效的对话，而不是孤立的单次查询
- **通过 MCP（模型上下文协议）实现可插拔的外部工具集成**，允许组织在无需重写代理的情况下将其连接到现有的数据基础设施
- **与提供商无关的 LLM 接口**，允许组织根据数据主权、成本和功能要求选择其 AI 提供商，而无需绑定到单个供应商的 SDK 模式
- **具有适当 SSE 处理的实时流媒体**，即使对于复杂的多步骤推理任务，也能提供响应式用户体验
## 架构亮点
### 具有持久检查点的状态图
代理被实现为 LangGraph `StateGraph`，具有可插拔的检查点。在开发过程中，内存中的 `MemorySaver` 不需要外部依赖。在生产环境中，`MongoDBSaver` 提供了持久状态，可以在服务器重启后生存，并支持跨多个实例的水平扩展。
每个对话都由 `thread_id` 键控，允许同一服务器为数千个同时在线用户维护独立、隔离的上下文。
### 自动对话摘要
一个关键的生产问题被大多数示例省略：无边界的上下文增长。该系统实现了一个滚动摘要节点，当对话历史超过可配置的阈值时触发。较旧的消息被压缩成摘要后注入系统，保持推理成本可控而不丢失对话连续性。
### MCP 工具集成
代理使用模型上下文协议在启动时从外部服务器加载工具。这种架构允许工具开发团队在独立于代理部署的情况下发布和更新工具。MCP 客户端支持 bearer token 身份验证，并在服务器不可用时平滑降级。
### 与提供商无关的 LLM 层
所有 LLM 调用都通过单个 `make_llm()` 工厂路由，该工厂通过 `OPENAI_BASE_URL` 接受任何与 OpenAI 兼容的端点。这支持 OpenAI、Azure OpenAI、Anthropic Claude（通过代理）、Google Gemini（通过代理）和通过 Ollama 的本地模型。切换提供商需要更改两个环境变量，而无需修改应用程序代码。
### 生产安全的消息净化
`_safe_messages()` 函数解决了生产环境中常见但在教程中缺失的一类错误：孤立的 `ToolMessage` 条目、具有无对应结果的工具调用的 `AIMessage` 记录，以及溢出上下文窗口的过大工具输出。这些情况在实际使用模式中自然出现，如果没有显式处理，则会导致静默失败或 API 错误。
## 快速入门
```bash
git clone https://github.com/bhaskar511939/langgraph-boilerplate-kit
cd langgraph-boilerplate-kit
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env — 设置 OPENAI_API_KEY
python server.py
```
访问 `http://localhost:8000/docs` 以获取交互式 API。
## API
```
POST /api/v1/chat/ask
{
"query": "我可以得到什么帮助？",
"user_id": "user-123",
"model": "gpt-4o" // 可选
}
```
响应：`text/event-stream` — 每个事件都是一个具有 `{type, stage, message, timestamp}` 的 JSON 对象。
## 项目结构
```
langgraph-skeleton/
├── agent/
│ ├── graph.py # StateGraph 定义和编译
│ ├── state.py # 共享 TypedDict 状态
│ ├── llm.py # 与提供商无关的 LLM 工厂
│ ├── events.py # 统一的流事件契约
│ ├── stream_events.py # astream_events() 处理管道
│ ├── checkpointers/ # 内存（默认）和 MongoDB 后端
│ ├── nodes/ # 模型、工具、汇总、路由节点
│ └── tools/ # 内置工具 + MCP 加载器
├── api/
│ ├── app.py # 具有生命周期的 FastAPI 应用程序
│ ├── sse.py # SSE 序列化
│ ├── routes/ # /ask 和 /health 端点
│ ├── schemas/ # Pydantic 请求/响应模型
│ └── services/ # 聊天服务流编排
├── config/ # 环境变量设置
├── prompts/ # Markdown 系统提示（可编辑）
├── utils/ # 日志记录和输入验证
└── tests/ # 集成测试
```
## 扩展此骨架
- **添加工具**：在 `agent/tools/builtin.py` 中使用 `@tool` 定义函数
- **添加 MCP 服务器**：在 `agent/tools/mcp_config.py` 中添加条目
- **切换 LLM 提供商**：在 `.env` 中设置 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`
- **使用持久内存**：设置 `MEMORY_BACKEND=mongodb` 和 `MONGODB_URI`
- **自定义代理**：编辑 `prompts/system.md`
## 许可证
MIT
