670 lines
26 KiB
Markdown
670 lines
26 KiB
Markdown
---
|
||
title: "feat: AgentKit v2 Phase 1 — 核心引擎升级 + 服务化"
|
||
type: feat
|
||
status: active
|
||
date: 2026-06-05
|
||
origin: docs/plans/2026-06-05-002-design-agentkit-v2-architecture.md
|
||
execution_posture: tdd
|
||
---
|
||
|
||
## Summary
|
||
|
||
实现 AgentKit v2 的 Phase 1：将当前"LLM 调用封装"升级为"真正的智能体平台"。核心改造包括 ReAct 推理引擎、LLM 统一网关、Skill 技能系统、意图路由器、质量门禁/输出标准化、以及 FastAPI 服务化。同时明确 GEO 项目如何通过 HTTP API 使用 AgentKit。
|
||
|
||
## Problem Frame
|
||
|
||
当前 agentkit 的 Agent 本质上是"配置驱动的 LLM 调用封装"——收到任务后渲染 Prompt、调用 LLM、返回结果，没有推理-行动循环，没有自主 Tool 选择，没有意图识别，没有产出质量管理。GEO 项目通过 import 内部类使用 agentkit，耦合度高，无法独立部署和扩缩容。
|
||
|
||
v2 的目标是让 agentkit 成为**可独立部署的通用 Agent 平台**，GEO 项目通过 HTTP API 调用。
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
追溯至架构设计文档的 11 条需求，Phase 1 覆盖：
|
||
|
||
| 需求 | Phase 1 覆盖 | 实现方式 |
|
||
|------|-------------|---------|
|
||
| R1. 通用 Agent 框架 | ✅ | ReAct Engine + Skill System |
|
||
| R2. 多 Agent 协同编排 | ⚠️ 保留现有 | Pipeline + Handoff 不变 |
|
||
| R3. 运行时自由增减 | ✅ | AgentKit Server API + AgentPool |
|
||
| R4. LLM 统一管理+用量 | ✅ | LLM Gateway |
|
||
| R5. 知识库连接 | ⚠️ 保留现有 | SemanticMemory 适配器不变 |
|
||
| R6. 产出质量管理 | ✅ | Quality Gate + Output Standardizer |
|
||
| R7. 记忆系统 | ⚠️ 保留现有 | 三层记忆不变，增加自动注入 |
|
||
| R8. 能力自我进化 | ⚠️ 保留现有 | EvolutionMixin 不变 |
|
||
| R9. Skill + MCP | ✅ | Skill System + MCP Bridge |
|
||
| R10. 意图识别 | ✅ | Intent Router（关键词 + LLM） |
|
||
| R11. 标准化输出 | ✅ | Output Standardizer |
|
||
|
||
---
|
||
|
||
## Key Technical Decisions
|
||
|
||
KTD1. **ReAct Engine 使用 Function Calling**：LLM 通过 Function Calling 自主决定调用哪个 Tool，而非文本解析。不支持 Function Calling 的模型降级为文本解析模式。理由：Function Calling 是业界标准（OpenAI/Anthropic/DeepSeek 均支持），比文本解析更可靠。
|
||
|
||
KTD2. **LLM Gateway 替换 llm_client 注入**：当前 ConfigDrivenAgent 接受 `llm_client: Any`，v2 改为注入 `llm_gateway: LLMGateway`。LLMGateway 内部管理 Provider、路由、计量。理由：统一管理 API Key 和用量统计，消除 llm_client 的 `Any` 类型问题。
|
||
|
||
KTD3. **SkillConfig 向后兼容 AgentConfig**：SkillConfig 扩展 AgentConfig（增加 intent、quality_gate、execution_mode），现有 8 个 YAML 配置无需修改即可运行。理由：降低迁移成本，GEO 项目可以渐进式迁移。
|
||
|
||
KTD4. **AgentKit Server 基于 FastAPI**：复用现有 MCPServer 的 FastAPI 基础，新增 Agent/Skill/Task/LLM 管理 API。理由：项目已有 FastAPI 依赖，无需引入新框架。
|
||
|
||
KTD5. **Intent Router 先实现关键词 + LLM 两级**：Embedding 路由推迟到 Phase 4。理由：关键词匹配覆盖 60-70% 场景，LLM 兜底覆盖剩余，Embedding 需要额外的向量服务依赖。
|
||
|
||
KTD6. **GEO 集成采用双模式过渡**：v2 同时支持 import 模式（向后兼容）和 HTTP API 模式。GEO 项目可以按自己的节奏迁移。理由：8 个 YAML 配置 + 3 个 custom_handler 不能一次性切换。
|
||
|
||
---
|
||
|
||
## High-Level Technical Design
|
||
|
||
### 请求处理流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant GEO as GEO Backend
|
||
participant API as AgentKit Server
|
||
participant Router as Intent Router
|
||
participant Pool as AgentPool
|
||
participant React as ReAct Engine
|
||
participant GW as LLM Gateway
|
||
participant Tool as Tool/MCP
|
||
participant QG as Quality Gate
|
||
|
||
GEO->>API: POST /api/v1/tasks {input_data}
|
||
API->>Router: route(input_data, skills)
|
||
Router->>Router: 关键词匹配 / LLM 分类
|
||
Router-->>API: matched_skill
|
||
API->>Pool: get_or_create_agent(skill)
|
||
Pool-->>API: agent
|
||
API->>React: execute(task, skill, tools)
|
||
loop ReAct Loop (max_steps)
|
||
React->>GW: chat(messages, tools=schemas)
|
||
GW->>GW: 路由 + 限流 + 计量
|
||
GW-->>React: LLMResponse
|
||
alt has_tool_calls
|
||
React->>Tool: safe_execute(**args)
|
||
Tool-->>React: tool_result
|
||
else final_answer
|
||
React-->>API: raw_output
|
||
end
|
||
end
|
||
API->>QG: validate(output, skill)
|
||
QG-->>API: QualityResult
|
||
alt not passed && can_retry
|
||
API->>React: retry with feedback
|
||
end
|
||
API-->>GEO: StandardOutput {data, metadata}
|
||
```
|
||
|
||
### 模块依赖关系
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph New["v2 新增模块"]
|
||
RE[ReActEngine]
|
||
LG[LLMGateway]
|
||
IR[IntentRouter]
|
||
QG[QualityGate]
|
||
OS[OutputStandardizer]
|
||
SS[SkillSystem]
|
||
SV[AgentKitServer]
|
||
AP[AgentPool]
|
||
end
|
||
|
||
subgraph Existing["v1 保留模块"]
|
||
BA[BaseAgent]
|
||
TR[ToolRegistry]
|
||
MM[Memory System]
|
||
EV[Evolution System]
|
||
OR[Orchestrator]
|
||
MC[MCP Server/Client]
|
||
end
|
||
|
||
SV --> AP
|
||
SV --> IR
|
||
SV --> QG
|
||
SV --> OS
|
||
AP --> BA
|
||
AP --> SS
|
||
AP --> LG
|
||
BA --> RE
|
||
BA --> MM
|
||
RE --> LG
|
||
RE --> TR
|
||
IR --> SS
|
||
IR --> LG
|
||
QG --> OS
|
||
SS --> TR
|
||
SS --> MC
|
||
BA --> EV
|
||
BA --> OR
|
||
```
|
||
|
||
---
|
||
|
||
## Output Structure
|
||
|
||
```
|
||
src/agentkit/
|
||
├── __init__.py # 扩展导出
|
||
├── core/
|
||
│ ├── base.py # 重构：集成 ReAct + LLM Gateway
|
||
│ ├── config_driven.py # 重构：SkillConfig + 兼容 AgentConfig
|
||
│ ├── react.py # 新增：ReAct 推理引擎
|
||
│ ├── agent_pool.py # 新增：Agent 实例池
|
||
│ └── ... (protocol, dispatcher, registry, exceptions, standalone 不变)
|
||
├── llm/ # 新增：LLM 统一网关
|
||
│ ├── __init__.py
|
||
│ ├── gateway.py # LLMGateway 主类
|
||
│ ├── protocol.py # LLMRequest/LLMResponse/LLMProvider 协议
|
||
│ ├── providers/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── openai.py # OpenAI 兼容 Provider
|
||
│ │ └── tracker.py # UsageTracker
|
||
│ └── config.py # LLM 配置加载
|
||
├── skills/ # 新增：Skill 技能系统
|
||
│ ├── __init__.py
|
||
│ ├── base.py # Skill + SkillConfig
|
||
│ ├── registry.py # SkillRegistry
|
||
│ └── loader.py # Skill YAML 加载
|
||
├── router/ # 新增：意图路由
|
||
│ ├── __init__.py
|
||
│ └── intent.py # IntentRouter
|
||
├── quality/ # 新增：质量管理
|
||
│ ├── __init__.py
|
||
│ ├── gate.py # QualityGate
|
||
│ └── output.py # OutputStandardizer
|
||
├── server/ # 新增：AgentKit Server
|
||
│ ├── __init__.py
|
||
│ ├── app.py # FastAPI 应用
|
||
│ ├── routes/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── agents.py # /api/v1/agents
|
||
│ │ ├── tasks.py # /api/v1/tasks
|
||
│ │ ├── skills.py # /api/v1/skills
|
||
│ │ ├── llm.py # /api/v1/llm
|
||
│ │ └── health.py # /api/v1/health
|
||
│ └── client.py # Python SDK Client
|
||
├── tools/ # 保留不变
|
||
├── memory/ # 保留不变
|
||
├── evolution/ # 保留不变
|
||
├── orchestrator/ # 保留不变
|
||
├── mcp/ # 保留不变
|
||
└── prompts/ # 保留不变
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Units
|
||
|
||
### U1. LLM Gateway — 协议层 + Provider 实现
|
||
|
||
**Goal:** 建立 LLM 统一调用协议，实现 OpenAI 兼容 Provider 和用量追踪。
|
||
|
||
**Requirements:** R4
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- `src/agentkit/llm/__init__.py`（新建）
|
||
- `src/agentkit/llm/protocol.py`（新建）
|
||
- `src/agentkit/llm/gateway.py`（新建）
|
||
- `src/agentkit/llm/providers/__init__.py`（新建）
|
||
- `src/agentkit/llm/providers/openai.py`（新建）
|
||
- `src/agentkit/llm/providers/tracker.py`（新建）
|
||
- `src/agentkit/llm/config.py`（新建）
|
||
- `tests/unit/test_llm_protocol.py`（新建）
|
||
- `tests/unit/test_llm_gateway.py`（新建）
|
||
- `tests/unit/test_llm_provider.py`（新建）
|
||
- `tests/unit/test_usage_tracker.py`（新建）
|
||
|
||
**Approach:**
|
||
|
||
1. 定义 LLM 协议：`LLMProvider`（抽象基类）、`LLMRequest`、`LLMResponse`、`TokenUsage`、`ToolCall`
|
||
2. 实现 `OpenAICompatibleProvider`：支持 OpenAI/DeepSeek/Anthropic（均兼容 OpenAI API 格式），包括 Function Calling
|
||
3. 实现 `LLMGateway`：Provider 注册、模型别名解析、降级策略、调用转发
|
||
4. 实现 `UsageTracker`：记录每次调用的 agent_name、model、tokens、cost、latency
|
||
5. 实现 `LLMConfig`：从 YAML 加载 Provider 配置、模型别名、降级策略
|
||
|
||
**Patterns to follow:** 现有 Tool 系统的抽象模式（ABC + 具体实现 + Registry）
|
||
|
||
**Test scenarios:**
|
||
|
||
test_llm_protocol.py:
|
||
- LLMRequest 构建包含 messages、model、tools
|
||
- LLMResponse 包含 content、usage、tool_calls
|
||
- TokenUsage 计算 total_tokens
|
||
- ToolCall 包含 id、name、arguments
|
||
|
||
test_llm_gateway.py:
|
||
- chat() 调用转发到正确的 Provider
|
||
- 模型别名解析为实际模型名
|
||
- 降级策略：主模型失败时切换到备用模型
|
||
- 不存在的模型别名抛出异常
|
||
- chat() 记录用量到 UsageTracker
|
||
|
||
test_llm_provider.py:
|
||
- OpenAICompatibleProvider.chat() 返回 LLMResponse
|
||
- Function Calling：返回包含 tool_calls 的响应
|
||
- 非 Function Calling：返回纯文本响应
|
||
- API 错误时抛出 LLMError
|
||
- 流式响应（基础支持，后续增强）
|
||
|
||
test_usage_tracker.py:
|
||
- record() 记录 agent_name、model、tokens、cost
|
||
- get_usage() 按 agent_name 过滤
|
||
- get_usage() 按时间范围过滤
|
||
- get_usage() 汇总 total_tokens 和 total_cost
|
||
- 空记录返回零值
|
||
|
||
**Verification:** `pytest tests/unit/test_llm_*.py -v` 全部通过
|
||
|
||
---
|
||
|
||
### U2. ReAct Engine — 推理-行动循环
|
||
|
||
**Goal:** 实现 ReAct 推理-行动循环，让 Agent 能自主推理、选择 Tool、根据中间结果调整策略。
|
||
|
||
**Requirements:** R1, R9
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/core/react.py`（新建）
|
||
- `tests/unit/test_react_engine.py`（新建）
|
||
- `tests/integration/test_react_loop.py`（新建）
|
||
|
||
**Approach:**
|
||
|
||
1. 实现 `ReActEngine`：核心循环（Think → Act → Observe），支持 Function Calling 和文本解析两种模式
|
||
2. 实现 `ReActStep`：记录每一步的 action、tool_name、arguments、result、tokens
|
||
3. 实现 `ReActResult`：包含 output、trajectory、total_steps、total_tokens
|
||
4. 停止条件：LLM 不再调用 Tool / 达到 max_steps / Quality Gate 通过
|
||
5. 降级模式：当 LLM 不支持 Function Calling 时，解析文本输出中的 Tool 调用
|
||
|
||
**Execution note:** TDD — 先写 ReAct 循环的测试（mock LLM Gateway），验证循环逻辑正确，再集成到 Agent。
|
||
|
||
**Test scenarios:**
|
||
|
||
test_react_engine.py:
|
||
- 单步完成：LLM 直接返回最终答案，不调用 Tool
|
||
- 两步完成：LLM 先调用 Tool，再返回最终答案
|
||
- 多步推理：3 步 ReAct 循环，每步调用不同 Tool
|
||
- 达到 max_steps 时返回当前最佳结果
|
||
- Tool 调用失败时，LLM 收到错误信息并调整策略
|
||
- Function Calling 模式：LLM 返回 tool_calls
|
||
- 文本解析模式：LLM 返回文本中包含 Tool 调用指令
|
||
- 空工具列表时直接生成答案
|
||
- 轨迹记录：每步的 action、tool_name、result 正确记录
|
||
|
||
test_react_loop.py:
|
||
- 完整 ReAct 循环：检索知识 → 生成内容 → 返回结果
|
||
- Quality Gate 集成：质量不合格时反馈给 ReAct 循环重试
|
||
- 记忆集成：轨迹存储到 WorkingMemory
|
||
|
||
**Verification:** `pytest tests/unit/test_react_engine.py tests/integration/test_react_loop.py -v` 全部通过
|
||
|
||
---
|
||
|
||
### U3. Skill System — 技能定义与注册
|
||
|
||
**Goal:** 实现 Skill 技能系统，将当前 AgentConfig 扩展为 SkillConfig，支持意图识别配置和质量门禁。
|
||
|
||
**Requirements:** R9, R10
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/skills/__init__.py`（新建）
|
||
- `src/agentkit/skills/base.py`（新建）
|
||
- `src/agentkit/skills/registry.py`（新建）
|
||
- `src/agentkit/skills/loader.py`（新建）
|
||
- `tests/unit/test_skill_config.py`（新建）
|
||
- `tests/unit/test_skill_registry.py`（新建）
|
||
- `tests/unit/test_skill_loader.py`（新建）
|
||
|
||
**Approach:**
|
||
|
||
1. `SkillConfig` 继承 `AgentConfig`，扩展字段：intent（keywords + description + examples）、quality_gate（required_fields + min_word_count + max_retries）、execution_mode（react/direct/custom）、max_steps
|
||
2. `Skill` 类：封装 SkillConfig + 对应的 Tool 列表 + PromptTemplate
|
||
3. `SkillRegistry`：注册/注销/查询/热更新 Skill
|
||
4. `SkillLoader`：从 YAML 目录批量加载 Skill
|
||
5. 向后兼容：现有 AgentConfig YAML 无需修改，SkillLoader 自动补充默认值
|
||
|
||
**Patterns to follow:** 现有 ToolRegistry 的注册/查询模式
|
||
|
||
**Test scenarios:**
|
||
|
||
test_skill_config.py:
|
||
- SkillConfig 从 YAML 加载，包含 intent 和 quality_gate
|
||
- SkillConfig 从旧版 AgentConfig YAML 加载，自动补充默认值
|
||
- execution_mode 默认为 react
|
||
- intent.keywords 为空时不报错
|
||
- quality_gate.max_retries 默认为 0
|
||
- 向后兼容：旧版 YAML 无 intent 字段时 intent 默认为空
|
||
|
||
test_skill_registry.py:
|
||
- register() 注册 Skill
|
||
- unregister() 注销 Skill
|
||
- get() 按 name 获取 Skill
|
||
- list_skills() 返回所有已注册 Skill
|
||
- update_skill() 热更新 Skill 配置
|
||
- 重复注册覆盖旧配置
|
||
|
||
test_skill_loader.py:
|
||
- 从目录批量加载 YAML
|
||
- 跳过无效 YAML 文件并记录警告
|
||
- 空目录返回空列表
|
||
- 加载后自动注册到 SkillRegistry
|
||
|
||
**Verification:** `pytest tests/unit/test_skill_*.py -v` 全部通过
|
||
|
||
---
|
||
|
||
### U4. Intent Router — 意图识别与路由
|
||
|
||
**Goal:** 实现两级意图路由（关键词匹配 + LLM 分类），将用户输入路由到最合适的 Skill。
|
||
|
||
**Requirements:** R10
|
||
|
||
**Dependencies:** U1, U3
|
||
|
||
**Files:**
|
||
- `src/agentkit/router/__init__.py`（新建）
|
||
- `src/agentkit/router/intent.py`（新建）
|
||
- `tests/unit/test_intent_router.py`（新建）
|
||
|
||
**Approach:**
|
||
|
||
1. `IntentRouter`：两级路由策略
|
||
- Level 1：关键词匹配（零成本）— 遍历 Skill 的 intent.keywords，匹配输入数据中的文本
|
||
- Level 2：LLM 分类（兜底）— 构建 Skill 列表描述，让 LLM 选择最匹配的 Skill
|
||
2. `RoutingResult`：包含 matched_skill、method（keyword/llm）、confidence
|
||
3. 关键词匹配逻辑：对 input_data 中的所有字符串值进行关键词匹配
|
||
4. LLM 分类 Prompt：列出所有 Skill 的 name + description + examples，让 LLM 返回 Skill name
|
||
|
||
**Test scenarios:**
|
||
|
||
test_intent_router.py:
|
||
- 关键词匹配：输入包含 Skill 的 intent.keywords 中的词，返回匹配
|
||
- 关键词匹配：输入不包含任何关键词，返回 None
|
||
- LLM 分类：关键词匹配失败后，LLM 正确分类
|
||
- LLM 分类：LLM 返回不存在的 Skill name，抛出异常
|
||
- 单个 Skill 时直接返回
|
||
- 空 Skill 列表抛出异常
|
||
- RoutingResult 包含 method 和 confidence
|
||
- 关键词匹配的 confidence 为 1.0
|
||
- LLM 分类的 confidence 由 LLM 返回
|
||
|
||
**Verification:** `pytest tests/unit/test_intent_router.py -v` 全部通过
|
||
|
||
---
|
||
|
||
### U5. Quality Gate + Output Standardizer
|
||
|
||
**Goal:** 实现产出质量管理和标准化输出，确保 Agent 输出符合 Skill 定义的 Schema 和质量要求。
|
||
|
||
**Requirements:** R6, R11
|
||
|
||
**Dependencies:** U3
|
||
|
||
**Files:**
|
||
- `src/agentkit/quality/__init__.py`（新建）
|
||
- `src/agentkit/quality/gate.py`（新建）
|
||
- `src/agentkit/quality/output.py`（新建）
|
||
- `tests/unit/test_quality_gate.py`（新建）
|
||
- `tests/unit/test_output_standardizer.py`（新建）
|
||
|
||
**Approach:**
|
||
|
||
1. `QualityGate`：多维度质量检查
|
||
- 必填字段检查
|
||
- 数值范围检查（min_word_count 等）
|
||
- JSON Schema 校验
|
||
- 自定义校验函数（dotted path 导入）
|
||
2. `QualityResult`：包含 passed、checks 列表、can_retry
|
||
3. `OutputStandardizer`：Schema 校验 + 字段类型标准化 + 元数据添加
|
||
4. `StandardOutput`：包含 skill_name、data、metadata（version、produced_at、quality_score）
|
||
|
||
**Test scenarios:**
|
||
|
||
test_quality_gate.py:
|
||
- 所有必填字段存在时 passed=True
|
||
- 缺少必填字段时 passed=False
|
||
- min_word_count 检查：字数不足时 passed=False
|
||
- JSON Schema 校验通过
|
||
- JSON Schema 校验失败
|
||
- max_retries > 0 时 can_retry=True
|
||
- max_retries = 0 时 can_retry=False
|
||
- 自定义校验函数返回 True/False
|
||
- 自定义校验函数不存在时跳过
|
||
|
||
test_output_standardizer.py:
|
||
- 标准化输出包含 skill_name 和 metadata
|
||
- metadata 包含 version 和 produced_at
|
||
- 字段类型标准化（字符串 → 整数等）
|
||
- 空 output_schema 时不做 Schema 校验
|
||
- quality_score 计算正确
|
||
|
||
**Verification:** `pytest tests/unit/test_quality_*.py tests/unit/test_output_standardizer.py -v` 全部通过
|
||
|
||
---
|
||
|
||
### U6. Agent 重构 — 集成 ReAct + LLM Gateway + Skill
|
||
|
||
**Goal:** 重构 BaseAgent 和 ConfigDrivenAgent，集成 ReAct Engine、LLM Gateway、Skill System、Memory 自动注入。
|
||
|
||
**Requirements:** R1, R4, R7, R8, R9
|
||
|
||
**Dependencies:** U1, U2, U3, U4, U5
|
||
|
||
**Files:**
|
||
- `src/agentkit/core/base.py`（修改）
|
||
- `src/agentkit/core/config_driven.py`（修改）
|
||
- `src/agentkit/__init__.py`（修改：扩展导出）
|
||
- `tests/unit/test_base_agent_v2.py`（新建）
|
||
- `tests/integration/test_agent_v2_lifecycle.py`（新建）
|
||
|
||
**Approach:**
|
||
|
||
1. **BaseAgent 重构**：
|
||
- 新增 `llm_gateway` 属性（替代外部 llm_client）
|
||
- 新增 `skill` 属性（当前激活的 Skill）
|
||
- `execute()` 方法集成 Quality Gate：质量不合格时反馈给 ReAct 循环
|
||
- Memory 自动注入：`on_task_start` 时从 Memory 加载上下文到 Prompt
|
||
- Evolution 自动集成：`on_task_complete` 时自动触发反思（如果 EvolutionMixin 已混入）
|
||
2. **ConfigDrivenAgent 重构**：
|
||
- 构造函数接受 `llm_gateway` 替代 `llm_client`（保持 `llm_client` 向后兼容）
|
||
- `handle_task()` 改为调用 ReAct Engine（当 execution_mode=react 时）
|
||
- 保留 `llm_generate`/`tool_call`/`custom` 模式作为 `direct` 执行模式
|
||
3. **向后兼容**：
|
||
- 现有 YAML 配置无需修改
|
||
- `llm_client` 参数仍然接受（自动包装为 LLMGateway）
|
||
- `ConfigDrivenAgent(config, tool_registry, llm_client, custom_handlers)` 签名不变
|
||
|
||
**Execution note:** TDD — 先写 Agent v2 的集成测试（期望行为），再重构代码使测试通过。
|
||
|
||
**Test scenarios:**
|
||
|
||
test_base_agent_v2.py:
|
||
- Agent 注入 LLM Gateway 后可通过 ReAct 执行任务
|
||
- Agent 注入 Skill 后 handle_task 使用 Skill 的 Prompt 和 Tool
|
||
- Memory 自动注入：on_task_start 时从 Memory 加载上下文
|
||
- Quality Gate 集成：质量不合格时自动重试
|
||
- 向后兼容：llm_client 参数自动包装为 LLM Gateway
|
||
- Agent 无 LLM Gateway 时降级为直接模式
|
||
|
||
test_agent_v2_lifecycle.py:
|
||
- 完整生命周期：创建 → 注入 Skill → 启动 → 执行 ReAct 任务 → 返回标准化结果 → 停止
|
||
- 多 Skill Agent：同一个 Agent 持有多个 Skill，Intent Router 自动选择
|
||
- Memory 在任务执行中自动存取
|
||
- Evolution 在任务完成后自动反思
|
||
|
||
**Verification:** `pytest tests/unit/test_base_agent_v2.py tests/integration/test_agent_v2_lifecycle.py -v` 全部通过，且现有 380 个测试不回归
|
||
|
||
---
|
||
|
||
### U7. AgentKit Server — FastAPI 服务化
|
||
|
||
**Goal:** 实现 AgentKit Server，提供 REST API 供 GEO 项目通过 HTTP 调用。
|
||
|
||
**Requirements:** R3
|
||
|
||
**Dependencies:** U1, U3, U6
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/__init__.py`（新建）
|
||
- `src/agentkit/server/app.py`（新建）
|
||
- `src/agentkit/server/routes/__init__.py`（新建）
|
||
- `src/agentkit/server/routes/agents.py`（新建）
|
||
- `src/agentkit/server/routes/tasks.py`（新建）
|
||
- `src/agentkit/server/routes/skills.py`（新建）
|
||
- `src/agentkit/server/routes/llm.py`（新建）
|
||
- `src/agentkit/server/routes/health.py`（新建）
|
||
- `src/agentkit/server/client.py`（新建）
|
||
- `src/agentkit/core/agent_pool.py`（新建）
|
||
- `tests/unit/test_agent_pool.py`（新建）
|
||
- `tests/unit/test_server_routes.py`（新建）
|
||
- `tests/integration/test_server_e2e.py`（新建）
|
||
|
||
**Approach:**
|
||
|
||
1. `AgentKitServer`：FastAPI 应用，包含所有路由
|
||
2. `AgentPool`：管理 Agent 实例的创建/删除/查询/热更新
|
||
3. API 路由：
|
||
- `POST /api/v1/agents` — 创建 Agent（指定 Skill 配置）
|
||
- `GET /api/v1/agents` — 列出所有 Agent
|
||
- `GET /api/v1/agents/{name}` — 获取 Agent 详情
|
||
- `DELETE /api/v1/agents/{name}` — 删除 Agent
|
||
- `POST /api/v1/tasks` — 提交任务（Intent Router 自动路由）
|
||
- `GET /api/v1/tasks/{id}` — 查询任务状态
|
||
- `POST /api/v1/skills` — 注册 Skill
|
||
- `GET /api/v1/skills` — 列出所有 Skill
|
||
- `GET /api/v1/llm/usage` — 查询用量统计
|
||
- `GET /api/v1/health` — 健康检查
|
||
4. `AgentKitClient`：Python SDK，封装 HTTP 调用
|
||
5. 任务执行：同步模式（等待结果返回）+ 异步模式（返回 task_id，轮询查询）
|
||
|
||
**Test scenarios:**
|
||
|
||
test_agent_pool.py:
|
||
- create_agent() 创建并启动 Agent
|
||
- remove_agent() 停止并移除 Agent
|
||
- get_agent() 返回已创建的 Agent
|
||
- list_agents() 返回所有 Agent 信息
|
||
- 重复创建同名 Agent 覆盖旧实例
|
||
|
||
test_server_routes.py:
|
||
- POST /api/v1/agents 创建 Agent 返回 201
|
||
- GET /api/v1/agents 返回 Agent 列表
|
||
- GET /api/v1/agents/{name} 返回 Agent 详情
|
||
- DELETE /api/v1/agents/{name} 返回 204
|
||
- POST /api/v1/tasks 提交任务返回结果
|
||
- POST /api/v1/skills 注册 Skill 返回 201
|
||
- GET /api/v1/llm/usage 返回用量统计
|
||
- GET /api/v1/health 返回 {"status": "ok"}
|
||
|
||
test_server_e2e.py:
|
||
- 完整流程：注册 Skill → 创建 Agent → 提交任务 → 获取结果
|
||
- Intent Router 自动路由到正确 Skill
|
||
- LLM 用量统计正确记录
|
||
- 删除 Agent 后提交任务返回 404
|
||
|
||
**Verification:** `pytest tests/unit/test_agent_pool.py tests/unit/test_server_routes.py tests/integration/test_server_e2e.py -v` 全部通过
|
||
|
||
---
|
||
|
||
### U8. GEO 集成 — 适配层 + 使用文档
|
||
|
||
**Goal:** 更新 GEO 项目的适配层，支持 v2 API，明确 GEO 如何使用 AgentKit。
|
||
|
||
**Requirements:** R3, R6
|
||
|
||
**Dependencies:** U7
|
||
|
||
**Files:**
|
||
- `geo/backend/app/agent_framework/adapter.py`（修改）
|
||
- `geo/backend/app/agent_framework/__init__.py`（修改）
|
||
- `geo/backend/app/agent_framework/agents/configs/*.yaml`（可选修改：增加 v2 字段）
|
||
|
||
**Approach:**
|
||
|
||
1. **adapter.py 更新**：
|
||
- 新增 `get_agentkit_client()` 函数：返回 AgentKitClient 实例
|
||
- 新增 `create_agents_via_api()` 函数：通过 HTTP API 创建 Agent
|
||
- 保留 `create_agents_from_configs()` 函数：向后兼容
|
||
- 新增 `submit_task_via_api()` 函数：通过 HTTP API 提交任务
|
||
2. **GEO 使用方式**：
|
||
- 方式 A（推荐）：启动 AgentKit Server → GEO 通过 AgentKitClient 调用
|
||
- 方式 B（兼容）：GEO 直接 import agentkit 内部类（向后兼容）
|
||
3. **YAML 配置迁移**（可选）：
|
||
- 现有 YAML 无需修改即可运行
|
||
- 可选增加 `intent` 和 `quality_gate` 字段以启用新功能
|
||
|
||
**Test scenarios:**
|
||
- adapter.py 的 `get_agentkit_client()` 返回有效客户端
|
||
- `create_agents_via_api()` 通过 API 创建 Agent
|
||
- `submit_task_via_api()` 通过 API 提交任务并获取结果
|
||
- 向后兼容：`create_agents_from_configs()` 仍然可用
|
||
- 现有 8 个 YAML 配置无需修改即可加载
|
||
|
||
**Verification:** GEO 项目的 agent_framework 模块可正常导入和使用
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
### In Scope
|
||
|
||
- LLM Gateway（协议 + Provider + 用量追踪）
|
||
- ReAct Engine（推理-行动循环 + Function Calling）
|
||
- Skill System（SkillConfig + SkillRegistry + SkillLoader）
|
||
- Intent Router（关键词 + LLM 两级路由）
|
||
- Quality Gate + Output Standardizer
|
||
- Agent 重构（集成 ReAct + LLM Gateway + Skill）
|
||
- AgentKit Server（FastAPI + AgentPool + API 路由）
|
||
- AgentKitClient（Python SDK）
|
||
- GEO 适配层更新
|
||
|
||
### Deferred for Later
|
||
|
||
- Embedding 路由（Phase 4）
|
||
- Budget Controller + Rate Limiter（Phase 4）
|
||
- 流式输出 SSE（Phase 4）
|
||
- MCP SSE 流式响应（Phase 4）
|
||
- MCP Client 自动发现（Phase 4）
|
||
- EpisodicMemory pgvector cosine distance 实现
|
||
- AgentTool 轮询改为事件驱动
|
||
- Pipeline 事件驱动替代轮询
|
||
- MIPROv2 多目标 Prompt 优化
|
||
- Bayesian Optimization 策略调优
|
||
- CI/CD 配置
|
||
|
||
### Outside This Project's Identity
|
||
|
||
- GEO 前端 Agent 管理界面
|
||
- A2A Protocol 支持
|
||
- 非 Python 语言的 SDK
|
||
|
||
---
|
||
|
||
## Risks & Dependencies
|
||
|
||
| Risk | Impact | Mitigation |
|
||
|------|--------|------------|
|
||
| ReAct 循环 token 消耗高 | 成本增加 | max_steps 限制（默认 5）+ 小模型路由 + 关键词预路由减少 LLM 调用 |
|
||
| Function Calling 不是所有模型都支持 | 兼容性 | 降级到文本解析模式（解析 LLM 输出中的 Tool 调用指令） |
|
||
| Agent 重构导致 GEO 回归 | 业务中断 | 向后兼容层 + 全量测试（380+ 现有测试 + 新测试） |
|
||
| LLM Gateway 增加调用延迟 | 性能 | Provider 连接池 + 异步调用 + 超时控制 |
|
||
| 服务化增加运维复杂度 | 部署 | 提供 docker-compose 配置 + 健康检查 + 日志标准化 |
|
||
|
||
---
|
||
|
||
## System-Wide Impact
|
||
|
||
- **GEO 项目**：需要更新 adapter.py，可选择切换到 HTTP API 模式
|
||
- **现有测试**：380 个测试必须全部通过，不允许回归
|
||
- **依赖**：新增 `fastapi`、`uvicorn`（已在 MCP 可选依赖中）、`httpx`（已有）
|
||
- **Python 版本**：保持 `>=3.11`
|
||
- **部署**：需要新增 AgentKit Server 的 docker-compose 配置
|