fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/brainstorms/2026-06-05-agentkit-archite...

8.4 KiB
Raw Blame History

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 变慢 反思和优化增加延迟 可配置关闭，异步执行