# Agent 架构演进路线

**更新日期**：2026-07-05  
**状态**：后续演进设计，不代表当前已实现  
**参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`

## 1. 为什么需要演进路线

旧版 `agent-architecture.md` 包含很多生产级设想：专科 SubAgent、Skill 体系、进程隔离、回退路由、MCP 工具协议化、进化引擎。它们不应作为当前 MVP 事实写入主架构，但可以作为后续扩展路线。

当前原则：

- 当前文档只声明已经可运行或明确落地的能力。
- 演进路线记录未来方向和触发条件。
- 每个演进项必须有可验证收益，不能只因为“架构更炫”就拆。

## 2. 演进总图

```mermaid
flowchart TD
    MVP["Current MVP: Planner + Executor + Verifier"] --> Split{"Executor 是否过载?"}
    Split -->|是| SubAgents["专科 SubAgent"]
    Split -->|否| Keep["继续强化通用 Executor"]

    SubAgents --> Skills["Skill / Playbook 体系"]
    Skills --> Fallback["回退路由"]
    Fallback --> Isolation["进程或 Pod 隔离"]

    MVP --> ToolGrowth{"工具数量和来源是否增长?"}
    ToolGrowth -->|是| MCP["MCP / Tool Server 协议化"]
    ToolGrowth -->|否| ToolCallbacks["继续使用 @Tool / ToolCallback"]

    MVP --> EvalGrowth{"评测数据是否足够?"}
    EvalGrowth -->|是| Evolution["Prompt / Skill 进化引擎"]
    EvalGrowth -->|否| Baseline["先扩大 baseline"]
```

## 3. 专科 SubAgent

### 触发条件

- Executor prompt 变得臃肿，难以同时覆盖接口、数据库、缓存、网络等场景。
- 不同故障类型需要明显不同的工具权限。
- Trace 显示某些场景经常走错排查路径。
- 评测集已经能衡量拆分前后的收益。

### 候选 SubAgent

| SubAgent | 场景 | 工具倾向 |
|---|---|---|
| `ExternalApiSubAgent` | 错误码、接口参数、第三方调用失败 | `lookup_knowledge`, logs, trace |
| `DatabaseSubAgent` | 连接池、慢 SQL、死锁、数据库不可用 | metrics, logs, knowledge |
| `CacheSubAgent` | Redis 超时、热点 key、内存风险 | metrics, logs, knowledge |
| `GenericDiagnosisSubAgent` | 兜底诊断 | 全量只读证据工具 |

### 不立即拆分的原因

- 当前 MVP 的工具规模还可由通用 Executor 管理。
- 过早拆分会增加 Prompt、评测和 trace 分析成本。
- 没有足够分类评测前，拆分可能只是移动复杂度。

## 4. Skill / Playbook 体系

旧版设计中的 Skill 可以在当前项目中演进为可版本化的诊断 Playbook。

```text
fault_category
  -> playbook
      -> required evidence
      -> tool sequence
      -> stop condition
      -> report template
      -> evaluation checks
```

优先落地方向：

- AIOps 告警处理 Playbook。
- 支付超时 Playbook。
- MySQL 连接池风险 Playbook。
- Redis timeout Playbook。

落地前提：

- 每个 Playbook 至少有 3-5 个 eval case。
- Playbook 失败时可以回退到通用 Executor。
- Trace 中能标记使用了哪个 Playbook 和哪个版本。

## 5. 回退路由

当前 Chat 已有低置信补证据和 REJECT 降级输出。后续如果引入 SubAgent，可扩展为：

```text
Specialized SubAgent
  -> failed / low confidence
  -> another specialized SubAgent
  -> GenericDiagnosisSubAgent
  -> degraded answer with confirmed facts only
```

回退依据：

- 工具连续失败。
- Verifier `REJECT`。
- Verifier `LOW_CONFID` 且补证据失败。
- Agent 输出缺失关键报告字段。

## 6. 进程隔离

当前所有 Agent 在同一 JVM 内运行。生产级隔离可以考虑：

```text
API service
  -> Supervisor service
  -> Planner service
  -> SubAgent services
  -> Verifier service
```

触发条件：

- 某类 Agent 需要独立扩缩容。
- 某类工具依赖不稳定，可能拖垮主应用。
- 不同 Agent 需要不同权限和网络访问策略。
- 单 JVM 内资源隔离不足。

MVP 阶段暂不拆分进程，优先保证 trace、评测和工具边界清晰。

## 7. MCP / Tool Server 协议化

当前工具主要通过 `@Tool`、`methodTools` 和 `ToolCallbackProvider` 暴露。工具数量增加后，可演进为：

```text
Agent
  -> Tool registry
  -> MCP / tool server
      -> log server
      -> metrics server
      -> knowledge server
      -> ticket/change server
```

收益：

- 工具独立部署。
- 新工具上线不必重发主应用。
- 不同 Agent 可获得不同工具子集。
- 工具调用协议统一，更利于审计。

风险：

- 调用链更长。
- 权限和超时治理更复杂。
- 本地开发和 Demo 成本上升。

## 8. 进化引擎

旧版文档提到从诊断中学习。当前可以拆成更务实的步骤：

1. 先扩大 diagnosis eval 和 RAG eval。
2. 从失败 trace 中标注 bad case。
3. 将高频失败沉淀为 Playbook 或 Prompt 规则。
4. 对 Prompt 版本做离线对比。
5. 足够稳定后再考虑线上 A/B。

不建议 MVP 直接做自动 Prompt 自优化。没有可靠评测和回滚机制时，自动优化更容易引入不可解释变化。

## 9. 演进优先级

| 优先级 | 项目 | 原因 |
|---|---|---|
| P0 | 扩大 eval baseline | 没有评测，拆任何架构都难以证明收益 |
| P1 | Playbook 化高频故障 | 可控、可解释、比拆 SubAgent 更轻 |
| P1 | 完整 evidence block | 提升 Verifier 和 Trace 质量 |
| P2 | 专科 SubAgent | 等问题类型和工具权限差异足够明显 |
| P2 | AIOps LLM Verifier | 规则门禁不足时再引入 |
| P3 | MCP 工具协议化 | 工具来源复杂后再做 |
| P3 | 进程隔离 | 生产负载和权限隔离需要明确后再做 |