内容
# AgentForge
**生产级企业AI智能体平台** — 设计、部署、编排和操作多智能体系统，具有团队在生产环境中期望的可靠性、可观察性和治理模式。
构建为涵盖端到端AI工程生命周期的全栈参考实现：从LLM路由和智能体运行时，到持久工作流、工具集成、内存、评估和实时可观察性。
---
## 为什么选择AgentForge？
大多数AI演示停留在聊天机器人包装。AgentForge更进一步 — 它模拟了**实际团队如何交付智能体系统**：
| 挑战 | AgentForge方法 |
|-----------|---------------------|
| 智能体在运行中失败 | **Temporal**持久工作流在重启后存活；运行在崩溃或人为延迟后恢复 |
| 智能体行为不可见 | **OpenTelemetry + Langfuse**跟踪，带有实时WebSocket流式传输到仪表板 |
| 工具执行不安全 | 权限层、人机审批、模式验证和审计跟踪 |
| 提示/模型漂移 | 版本提示，带有差异、标签和A/B路由；运行固定确切版本 |
| 无法衡量质量 | 评估框架，带有数据集、LLM评委、回归门控和模型比较 |
| 供应商锁定 | 跨OpenAI、Anthropic、Gemini和Ollama的统一**模型网关**，带有备用方案 |
| 集成扩展 | **MCP（模型上下文协议）**支持 — 从任何兼容服务器发现和调用工具 |
---
## 核心能力
### 智能体运行时
- 创建、版本化和发布智能体定义，带有模型配置、工具、内存和防护措施
- 将智能体编译为**LangGraph** ReAct循环，带有预算限制、最大步骤防护和审批门控
- 用于部署前测试智能体的交互式**游乐场**
### 多智能体编排
- **计划器 → 工作器 → 聚合器**模式，用于将复杂目标分解为任务DAG
- 并行扩展、顺序管道和主管路由
- 人机审批检查点，可以暂停运行数小时，并通过API信号恢复
### 可视化工作流构建器
- 用于编排智能体、LLM、工具、路由器、地图和审批节点的拖拽式工作流设计器（**React Flow**）
- 工作流编译为**Temporal**定义，用于持久、长时间运行的执行
### 工具注册表和MCP集成
- 统一的**原生**、**HTTP**和**MCP**工具调用路径
- 输入和输出的JSON模式验证
- 带有stdio、SSE和HTTP传输的自动发现的MCP服务器注册
- 权限模型：`safe`、`requires_approval`、`dangerous`
### 内存系统
- **短期**对话缓冲区（Redis）
- **长期**语义内存（Qdrant向量存储）
- 可插拔的嵌入器、重新排序、令牌预算召回和异步摘要
### 提示注册表
- 版本提示模板，带有Jinja渲染
- 基于标签的路由（`production`、`challenger`）和加权A/B测试
- 发布前差异视图和渲染预览
### 评估框架
- 带有手动导入或生产跟踪收集的数据集管理
- 评估器：启发式、LLM评委、基于代码和人为评分
- 通过Celery进行并行评估运行，带有回归门控和模型/智能体比较矩阵
### 可观察性和分析
- 带有每个LLM调用和工具调用的成本和延迟的分布式跟踪
- 通过WebSocket（Redis pub/sub）实时运行流式传输
- 运行量、成本、延迟和审批指标的分析仪表板
### 企业基础
- 多租户身份验证（JWT、组织、API密钥、基于角色的访问）
- 速率限制、幂等密钥和令牌/成本预算
- 调度运行（cron、间隔、Webhook触发器）
- Docker Compose全栈部署
---
## 用例
AgentForge设计用于可靠性、审计性和人为监督至关重要的场景：
| 用例 | AgentForge如何帮助 |
|----------|---------------------|
| **客户支持自动化** | 带有内存的智能体回忆先前交互；危险操作（退款、账户更改）需要人为审批 |
| **研究和分析管道** | 计划器分解研究目标；工作器智能体并行搜索、总结和聚合 |
| **内部副驾驶** | 连接MCP服务器（GitHub、Slack、数据库）作为工具；用权限层管理访问 |
| **文档处理工作流** | 可视化工作流构建器链接提取 → 分类 → 路由 → 审批步骤，带有完整的可追溯性 |
| **模型/提示实验** | 提示版本控制 + 评估框架比较质量、成本和延迟，然后再推广到生产环境 |
| **定时报告智能体** | cron触发的运行生成和交付报告，带有持久执行和故障恢复 |
| **合规敏感自动化** | 不变的版本固定、人机审批跟踪和每个决策的可追溯性重放 |
---
## 架构
AgentForge遵循**六边形（端口和适配器）架构** — 领域逻辑是框架无关的，基础设施是可交换的，每个有界上下文都是一个可分离的Python包。
```
┌─────────────────────────────────────────────────────────────────┐
│ Next.js 仪表板（智能体、工作流、运行、评估、分析） │
└────────────────────────────┬────────────────────────────────────┘
│ REST + WebSocket
┌────────────────────────────▼────────────────────────────────────┐
│ API网关（FastAPI）— 认证、速率限制、路由、WS中心 │
└──┬──────────┬──────────┬──────────┬──────────┬─────────────────┘
│ │ │ │ │
智能体 执行 工作流 工具注册 提示/评估
运行时 引擎 引擎 + MCP / 内存
│ │ │ │ │
└──────────┴──── LangGraph + 模型网关 ─┘
│
┌──────────────┼──────────────┐
│ │ │
Temporal Celery Postgres
（持久） （异步作业） Qdrant + Redis
```
**关键设计决策：**
- **Temporal**用于持久、有状态的智能体运行（在重启后存活，支持人机等待）
- **Celery**用于即发即弃的后台工作（嵌入、评估扩展、通知）
- **模块化单体** — 有界上下文作为包，可在无需代码更改的情况下部署为单独的容器
- **异步贯穿始终** — 异步SQLAlchemy、httpx和LangGraph节点
完整系统设计：[docs/01-ARCHITECTURE.md](docs/01-ARCHITECTURE.md)
---
## 技术栈
| 层 | 技术 |
|-------|-------------|
| **后端** | Python 3.12+、FastAPI、Pydantic、SQLAlchemy（异步）、Alembic |
| **智能体框架** | LangGraph、LangChain |
| **编排** | Temporal、Celery |
| **LLM提供者** | OpenAI、Anthropic、Gemini、Ollama（统一网关） |
| **数据库** | PostgreSQL、Redis、Qdrant |
| **前端** | Next.js、React、TypeScript、TanStack Query、React Flow、Tailwind CSS |
| **可观察性** | OpenTelemetry、Langfuse |
| **工具** | MCP SDK、Docker Compose、uv、pytest |
---
## 展示的技能
该项目是一个作品集，针对**AI工程师**和**机器学习平台**职位。它展示了：
- **LLM应用架构** — 模型路由、流媒体、备用方案、成本核算和预算强制执行
- **智能体设计模式** — ReAct循环、多智能体计划/工作器编排、工具使用和内存集成
- **生产工程** — 持久工作流、人机闸门、多租户、身份验证和速率限制
- **RAG和内存系统** — 向量检索、嵌入管道、对话缓冲区和摘要
- **MCP和工具集成** — 模式验证的工具注册表，支持行业标准协议
- **评估和质量** — LLM作为评委、回归门控和系统化的模型/提示比较
- **可观察性** — 分布式跟踪、实时流媒体和成本/延迟分析
- **全栈交付** — API设计、WebSocket实时更新和精致的操作仪表板
- **软件架构** — 清洁/六边形架构、领域驱动的有界上下文和异步Python
---
## 快速入门
### 先决条件
Docker、Python 3.12+、Node.js 18+、[uv](https://github.com/astral-sh/uv)
### 在本地运行
```bash
# 1. 环境
cp .env.example .env
# 2. 基础设施
docker compose up -d postgres redis qdrant temporal temporal-ui
# 3. Python依赖项
pip install uv && uv sync --all-packages
# 4. 数据库迁移
uv run alembic -c migrations/alembic.ini upgrade head
# 5. API服务器
cd apps/gateway && uv run uvicorn main:app --reload --port 8000
# 6. 前端（新终端）
cd apps/web && npm install && npm run dev
```
打开 **http://localhost:3000** — 注册账户、创建智能体并在游乐场运行。
### 全栈（所有服务）
```bash
docker compose up
```
### 开发命令
```bash
make test # 单元测试
make migrate # alembic升级
make seed # 演示用户 + 示例数据
```
---
## 服务
| 服务 | 端口 | 描述 |
|---------|------|-------------|
| API网关 | 8000 | REST API + WebSocket流媒体 |
| 前端 | 3000 | Next.js操作仪表板 |
| Temporal UI | 8080 | 工作流检查器 |
| PostgreSQL | 5432 | 记录系统 |
| Redis | 6379 | 缓存、发布/订阅、Celery代理 |
| Qdrant | 6333 | 向量内存存储 |
---
## 文档
| 文档 | 主题 |
|-----|-------|
| [01-架构](docs/01-ARCHITECTURE.md) | 系统设计、服务边界、数据流 |
| [05-智能体](docs/05-AGENTS.md) | 智能体生命周期、ReAct循环、多智能体模式 |
| [06-工作流引擎](docs/06-WORKFLOW-ENGINE.md) | 可视化工作流构建器和编译 |
| [07-内存](docs/07-MEMORY.md) | 短期、长期和情景记忆 |
| [08-工具](docs/08-TOOLS.md) | 工具注册表、权限、MCP集成 |
| [09-提示](docs/09-PROMPTS.md) | 提示版本控制、标签、A/B路由 |
| [10-评估](docs/10-EVALUATION.md) | 数据集、评估器、回归门控 |
| [11-跟踪](docs/11-TRACING.md) | OpenTelemetry、Langfuse、实时流媒体 |
| [13-路线图](docs/13-ROADMAP.md) | 实现里程碑和未来工作 |
---
## 项目结构
```
agentforge/
├── apps/
│ ├── gateway/ # FastAPI API网关
│ ├── web/ # Next.js仪表板
│ ├── agent_worker/ # Temporal工作器
│ └── celery_worker/ # 后台任务工作器
├── packages/
│ ├── agents/ # 智能体运行时和LangGraph编译器
│ ├── execution/ # 运行编排引擎
│ ├── model_gateway/ # 统一LLM提供者抽象
│ ├── tools/ # 工具注册表 + MCP客户端
│ ├── memory/ # Redis + Qdrant内存服务
│ ├── prompts/ # 提示版本控制和路由
│ ├── workflows/ # 可视化工作流编译器
│ ├── evaluation/ # 评估数据集和运行器
│ └── ... # 认证、核心、计划器、调度器
├── docs/ # 架构和设计文档
├── migrations/ # Alembic数据库迁移
└── tests/ # 单元和端到端测试
```
---
## 许可证
MIT
