---
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 配置
