223 lines
8.4 KiB
Markdown
223 lines
8.4 KiB
Markdown
# AgentKit 架构完善需求文档
|
||
|
||
**Created:** 2026-06-05
|
||
**Status:** active
|
||
**Topic:** agentkit-architecture-gap-analysis
|
||
**Type:** feature
|
||
|
||
---
|
||
|
||
## 问题框架
|
||
|
||
当前 AgentKit 已实现 12 个核心模块、37 个源文件、6,470 行代码、535 个测试通过。但存在 4 个关键缺口，如果不补齐，框架不能称为"生产就绪的标准 Agent 开发架构"。
|
||
|
||
**目标**：将 AgentKit 从"功能完整但缺少生产级特性"提升为"可直接用于生产的标准 Agent 框架"。
|
||
|
||
---
|
||
|
||
## 当前架构状态
|
||
|
||
### 已完整实现（10 个模块）
|
||
|
||
| 模块 | 核心能力 | 测试覆盖 |
|
||
|------|---------|---------|
|
||
| **BaseAgent** | 生命周期、状态机、并发控制、钩子 | ✅ |
|
||
| **ConfigDrivenAgent** | 4 种任务模式（react/llm/tool/custom） | ✅ |
|
||
| **ReAct Engine** | Think-Act-Observe 循环、Function Calling、文本解析 | ✅ |
|
||
| **LLM Gateway** | Provider 注册、模型路由、Fallback 链、用量追踪 | ✅ |
|
||
| **Skill System** | SkillConfig、SkillRegistry、SkillLoader、向后兼容 | ✅ |
|
||
| **Intent Router** | 关键词匹配 + LLM 分类两级路由 | ✅ |
|
||
| **Quality Gate** | 4 维度检查（必填/字数/Schema/自定义）+ 自动重试 | ✅ |
|
||
| **Output Standardizer** | Schema 验证 + 类型归一化 + 元数据 | ✅ |
|
||
| **Tool System** | FunctionTool、AgentTool、MCPTool、组合模式 | ✅ |
|
||
| **MCP** | Server + Transport（HTTP/SSE）+ Client | ✅ |
|
||
| **Orchestrator** | PipelineEngine（DAG + 并行）+ HandoffManager | ✅ |
|
||
| **Server** | FastAPI + REST API + Python SDK + AgentPool | ✅ |
|
||
|
||
### 存在缺口（4 个）
|
||
|
||
| 缺口 | 当前状态 | 缺失内容 | 严重度 |
|
||
|------|---------|---------|--------|
|
||
| **A. Evolution 集成** | 代码完整，未集成 | Reflector/PromptOptimizer/ABTester 未接入 Agent 生命周期 | 中 |
|
||
| **B. 服务化安全** | 无认证无限流 | API Key 认证 + 速率限制 + CORS 修复 + SSRF 防护 | 高 |
|
||
| **C. 流式输出** | 不支持 | SSE streaming + ReAct 事件流 + 客户端流式消费 | 中 |
|
||
| **D. 异步任务** | Placeholder | 异步执行 + 状态轮询 + WebSocket 推送 | 高 |
|
||
|
||
### 已知小问题
|
||
|
||
| 问题 | 位置 | 状态 |
|
||
|------|------|------|
|
||
| pgvector 向量检索未实现 | `episodic.py:99` | 降级方案可用（时间衰减） |
|
||
| custom_handler 缺少白名单 | `config_driven.py` | 已在 Phase 1 审查中标识 |
|
||
| CORS 配置不当 | `server/app.py` | `allow_origins=["*"]` + `allow_credentials=True` 冲突 |
|
||
|
||
---
|
||
|
||
## 需求
|
||
|
||
### R1. API Key 认证
|
||
所有 Server API 端点（除健康检查外）必须验证 API Key。通过 `X-API-Key` 请求头传递，密钥从环境变量 `AGENTKIT_API_KEY` 读取。
|
||
|
||
### R2. 速率限制
|
||
Server 必须限制请求频率，防止 LLM 成本耗尽。默认每分钟 60 次请求（可配置），超过时返回 429 Too Many Requests。
|
||
|
||
### R3. CORS 修复
|
||
修复 `allow_origins=["*"]` + `allow_credentials=True` 冲突。生产环境应限制具体域名。
|
||
|
||
### R4. Callback URL SSRF 防护
|
||
TaskDispatcher 的 callback URL 必须验证：只允许 http/https 协议，拒绝内网 IP。
|
||
|
||
### R5. 异步任务执行
|
||
`POST /api/v1/tasks` 必须支持异步模式：提交后返回 task_id，后台执行任务。
|
||
|
||
### R6. 任务状态追踪
|
||
`GET /api/v1/tasks/{task_id}` 必须返回真实状态：PENDING / RUNNING / COMPLETED / FAILED。
|
||
|
||
### R7. 任务结果存储
|
||
异步任务的结果必须存储（Redis 或内存），供状态查询和结果获取。
|
||
|
||
### R8. LLM 流式输出
|
||
LLM Gateway 必须支持 streaming 模式，逐 chunk 返回 LLM 响应。
|
||
|
||
### R9. ReAct 事件流
|
||
ReAct Engine 必须支持 streaming 事件输出，让用户实时看到 Think/Act/Observe 进展。
|
||
|
||
### R10. SSE 流式端点
|
||
Server 必须提供 SSE 端点（`/api/v1/tasks/stream`），支持长时间任务的实时进展推送。
|
||
|
||
### R11. Evolution 集成到 Agent 生命周期
|
||
BaseAgent 必须在 `on_task_complete()` 后自动调用 Reflector 反思，触发 PromptOptimizer 和 ABTester。
|
||
|
||
### R12. Evolution 配置化
|
||
Agent 应可通过 YAML 配置启用/禁用 Evolution 功能（`evolution: { enabled: true, reflect_after_task: true }`）。
|
||
|
||
---
|
||
|
||
## 成功标准
|
||
|
||
1. **安全**：无 API Key 的请求返回 401，超过速率限制返回 429
|
||
2. **异步**：提交任务后 100ms 内返回 task_id，后台异步执行
|
||
3. **流式**：ReAct 循环的每个 step（Think/Act/Observe）实时推送给客户端
|
||
4. **进化**：Agent 完成任务后自动生成反思记录，可触发 Prompt 优化
|
||
5. **测试**：所有新增功能有对应测试，总测试数 600+
|
||
|
||
---
|
||
|
||
## 范围边界
|
||
|
||
**本需求包含**：
|
||
- B：服务化安全（R1-R4）
|
||
- D：异步任务（R5-R7）
|
||
- C：流式输出（R8-R10）
|
||
- A：Evolution 集成（R11-R12）
|
||
|
||
**本需求不包含**：
|
||
- GEO 项目的任何改动
|
||
- 新的 LLM Provider 实现（如 Anthropic SDK 原生支持）
|
||
- 前端 UI 开发
|
||
- 生产环境部署配置（K8s、Prometheus 监控等）
|
||
- pgvector 向量检索实现（已有降级方案）
|
||
|
||
---
|
||
|
||
## 关键决策
|
||
|
||
### KTD1：认证采用 API Key 方案（非 JWT/OAuth）
|
||
**理由**：AgentKit Server 是内部服务间调用场景，API Key 足够简单有效。JWT/OAuth 增加复杂度但无明显收益。
|
||
|
||
### KTD2：速率限制采用内存计数器（非 Redis）
|
||
**理由**：单实例部署下内存计数器足够。多实例场景后续可升级为 Redis 滑动窗口。
|
||
|
||
### KTD3：异步任务使用 Redis 存储状态
|
||
**理由**：AgentKit 已有 Redis 依赖（WorkingMemory），复用最简单。内存模式作为降级方案。
|
||
|
||
### KTD4：流式输出使用 SSE（非 WebSocket）
|
||
**理由**：SSE 单向推送足够（服务端 → 客户端），实现比 WebSocket 简单，HTTP 兼容性好。
|
||
|
||
### KTD5：Evolution 采用可选集成
|
||
**理由**：不是所有场景都需要自我进化。通过 YAML 配置 `evolution.enabled: false` 可关闭。
|
||
|
||
---
|
||
|
||
## 实现顺序
|
||
|
||
```
|
||
Phase B（安全） → Phase D（异步任务） → Phase C（流式输出） → Phase A（Evolution）
|
||
```
|
||
|
||
### Phase B：服务化安全（4 个实施单元）
|
||
|
||
#### U1. CORS 修复 + API Key 认证中间件
|
||
- 修改 `src/agentkit/server/app.py`
|
||
- 新建 `src/agentkit/server/middleware.py`
|
||
- 实现 `APIKeyAuthMiddleware`
|
||
|
||
#### U2. 速率限制中间件
|
||
- 添加到 `src/agentkit/server/middleware.py`
|
||
- 实现 `RateLimiter`（固定窗口计数器）
|
||
- 可配置：`rate_limit_per_minute`
|
||
|
||
#### U3. Callback URL SSRF 防护
|
||
- 修改 `src/agentkit/core/dispatcher.py`
|
||
- 实现 `_validate_callback_url()` 函数
|
||
|
||
#### U4. custom_handler 模块前缀白名单
|
||
- 修改 `src/agentkit/core/config_driven.py`
|
||
- 添加 `_ALLOWED_HANDLER_PREFIXES` 白名单
|
||
|
||
### Phase D：异步任务（3 个实施单元）
|
||
|
||
#### U5. 任务状态存储
|
||
- 新建 `src/agentkit/server/task_store.py`
|
||
- 支持 Redis 和内存两种后端
|
||
- TaskState: PENDING / RUNNING / COMPLETED / FAILED
|
||
|
||
#### U6. 异步任务执行
|
||
- 修改 `src/agentkit/server/routes/tasks.py`
|
||
- `POST /api/v1/tasks` 改为异步提交
|
||
- 返回 `{"task_id": "...", "status": "PENDING"}`
|
||
|
||
#### U7. 状态查询 + 结果获取
|
||
- 修改 `GET /api/v1/tasks/{task_id}` 返回真实状态
|
||
- 新增 `GET /api/v1/tasks/{task_id}/result` 获取结果
|
||
|
||
### Phase C：流式输出（3 个实施单元）
|
||
|
||
#### U8. LLM Gateway 流式支持
|
||
- 修改 `src/agentkit/llm/gateway.py`
|
||
- 新增 `stream()` 方法，SSE chunk-by-chunk
|
||
- 修改 `OpenAICompatibleProvider` 支持 `stream=True`
|
||
|
||
#### U9. ReAct Engine 事件流
|
||
- 修改 `src/agentkit/core/react.py`
|
||
- 新增 `execute_streaming()` 方法
|
||
- 每个 Think/Act/Observe step 发出事件
|
||
|
||
#### U10. SSE 流式端点
|
||
- 新增 `src/agentkit/server/routes/streaming.py`
|
||
- `POST /api/v1/tasks/stream` SSE 端点
|
||
- Client SDK 支持流式消费
|
||
|
||
### Phase A：Evolution 集成（2 个实施单元）
|
||
|
||
#### U11. Evolution 生命周期钩子
|
||
- 修改 `src/agentkit/core/base.py`
|
||
- `on_task_complete()` 后自动调用 Reflector
|
||
- 通过 EvolutionMixin 集成
|
||
|
||
#### U12. Evolution 配置化
|
||
- 修改 `AgentConfig` 添加 `evolution` 字段
|
||
- 修改 `SkillConfig` 继承 evolution 配置
|
||
- YAML 配置示例
|
||
|
||
---
|
||
|
||
## 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|------|------|------|
|
||
| 流式输出改动大 | ReAct Engine 需要重构 | 保持原有同步接口不变，新增 streaming 接口 |
|
||
| 异步任务需要 Redis | 测试环境可能没有 Redis | 提供内存降级方案 |
|
||
| API Key 认证破坏现有测试 | 测试需要传递 API Key | 测试环境设置环境变量 |
|
||
| Evolution 集成后 Agent 变慢 | 反思和优化增加延迟 | 可配置关闭，异步执行 |
|