215 lines
7.5 KiB
Markdown
215 lines
7.5 KiB
Markdown
# Agent 编排架构
|
||
|
||
**更新日期**：2026-07-05
|
||
**状态**：当前可运行架构
|
||
**参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`
|
||
|
||
## 1. 设计定位
|
||
|
||
旧版 Agent 架构把系统描述为 Supervisor、Planner、SubAgent、Verifier 的团队协作。当前 MVP 保留这个核心思想，但实现更收敛：
|
||
|
||
- Chat 链路使用固定顺序工作流：`Planner -> Executor -> Verifier`。
|
||
- AIOps 链路使用 `SupervisorAgent` 调度 `Planner + Executor`，最终由规则评估器做轻量验证。
|
||
- 当前没有拆分 ExternalApiSubAgent、InternalErrorSubAgent、DatabaseSubAgent；这些作为后续演进方向保留。
|
||
- 证据工具不直接散落在各个 Agent 里，而是通过 Spring AI ToolCallback / `@Tool` 统一暴露。
|
||
|
||
## 2. 当前 Agent 全景
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Chat["Chat diagnosis"]
|
||
ChatIn["POST /api/chat"] --> ChatService["ChatService"]
|
||
ChatService --> ChatPlanner["chat_planner"]
|
||
ChatPlanner --> ChatExecutor["chat_executor"]
|
||
ChatExecutor --> ChatTools["evidence tools"]
|
||
ChatTools --> ChatExecutor
|
||
ChatExecutor --> ChatVerifier["chat_verifier"]
|
||
ChatVerifier --> ChatDecision{"PASS / LOW_CONFID / REJECT"}
|
||
ChatDecision --> ChatAnswer["final answer"]
|
||
end
|
||
|
||
subgraph AiOps["AIOps diagnosis"]
|
||
AiOpsIn["POST /api/ai_ops"] --> AiOpsService["AiOpsService"]
|
||
AiOpsService --> Supervisor["ai_ops_supervisor"]
|
||
Supervisor --> AiOpsPlanner["planner_agent"]
|
||
Supervisor --> AiOpsExecutor["executor_agent"]
|
||
AiOpsPlanner --> AiOpsExecutor
|
||
AiOpsExecutor --> AiOpsTools["Prometheus / logs / lookup_knowledge"]
|
||
AiOpsTools --> AiOpsReport["alert report"]
|
||
AiOpsReport --> AiOpsRule["AiOpsRuleEvaluationService"]
|
||
end
|
||
|
||
subgraph Trace["Trace persistence"]
|
||
Session["diagnosis_session"]
|
||
Step["agent_step"]
|
||
Invocation["tool_invocation"]
|
||
SelfEval["self_evaluation"]
|
||
end
|
||
|
||
ChatService --> Session
|
||
ChatPlanner --> Step
|
||
ChatExecutor --> Step
|
||
ChatVerifier --> Step
|
||
ChatTools --> Invocation
|
||
ChatDecision --> SelfEval
|
||
|
||
AiOpsService --> Session
|
||
AiOpsPlanner --> Step
|
||
AiOpsExecutor --> Step
|
||
AiOpsTools --> Invocation
|
||
AiOpsRule --> SelfEval
|
||
```
|
||
|
||
## 3. Chat 编排
|
||
|
||
Chat 复杂诊断采用 `SequentialAgent`，顺序固定：
|
||
|
||
```text
|
||
chat_planner
|
||
-> chat_executor
|
||
-> lookup_knowledge / query_logs / query_metrics / date_time
|
||
-> chat_verifier
|
||
-> reads tool_trace_summary
|
||
-> outputs verifier JSON
|
||
```
|
||
|
||
关键行为：
|
||
|
||
| 角色 | 当前职责 | 输出 |
|
||
|---|---|---|
|
||
| `chat_planner` | 拆解问题，注入知识域地图和对话历史，给出排查方向 | `planner_plan` |
|
||
| `chat_executor` | 按计划调用证据工具，组合工具返回形成诊断答复 | `executor_feedback` |
|
||
| `chat_verifier` | 只基于已有证据校验 Executor 答案，不做新检索 | `verifier_output` |
|
||
|
||
Chat 链路最多支持两轮验证：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant C as ChatService
|
||
participant P as chat_planner
|
||
participant E as chat_executor
|
||
participant T as tools
|
||
participant V as chat_verifier
|
||
participant S as diagnosis_session
|
||
|
||
C->>P: 原始问题 + history + retry_context
|
||
P-->>C: planner_plan
|
||
C->>E: planner_plan + 上下文
|
||
E->>T: 调用证据工具
|
||
T-->>E: 证据结果
|
||
E-->>C: executor_feedback
|
||
C->>V: executor_final_answer + tool_trace_summary
|
||
V-->>C: PASS / LOW_CONFID / REJECT
|
||
C->>S: 写入 verifier_evaluation
|
||
alt LOW_CONFID 且允许补证据
|
||
C->>P: retry_context: 仅补缺失证据
|
||
else PASS 或 REJECT
|
||
C-->>S: 保存最终 answer
|
||
end
|
||
```
|
||
|
||
决策语义：
|
||
|
||
| Verdict | 行为 |
|
||
|---|---|
|
||
| `PASS` | 输出 Executor 答案 |
|
||
| `LOW_CONFID` | 如果分数低于阈值且仍有轮次，构造 `retry_context` 补证据；否则输出低置信提示 |
|
||
| `REJECT` | 输出降级答复，只保留已确认信息和下一步建议 |
|
||
|
||
## 4. AIOps 编排
|
||
|
||
AIOps 使用 `SupervisorAgent` 调度两个子 Agent：
|
||
|
||
```text
|
||
ai_ops_supervisor
|
||
-> planner_agent
|
||
-> executor_agent
|
||
-> final report
|
||
-> AiOpsRuleEvaluationService
|
||
```
|
||
|
||
与 Chat 的差异：
|
||
|
||
- AIOps 的输入可能是结构化告警 payload。
|
||
- payload 模式会进入 `PAYLOAD_TARGETED`，最终报告必须聚焦输入告警。
|
||
- 无 payload 时进入 `AUTO_DISCOVERY`，先通过告警工具发现活跃告警。
|
||
- 当前 AIOps 不使用 LLM Verifier，而使用轻量规则评估器写入 `self_evaluation.aiops_rule_evaluation`。
|
||
|
||
## 5. 工具边界
|
||
|
||
当前 Executor 可用工具来自两类：
|
||
|
||
```text
|
||
methodTools
|
||
-> dateTimeTools
|
||
-> lookupKnowledgeTool
|
||
-> queryMetricsTools
|
||
-> queryLogsTools when mock enabled
|
||
|
||
ToolCallbackProvider
|
||
-> framework-discovered tools
|
||
```
|
||
|
||
工具调用必须写入 `tool_invocation`。其中 `lookup_knowledge` 额外记录：
|
||
|
||
- L0/L1 命中数量。
|
||
- 检索层。
|
||
- relevance level。
|
||
- retrieved domains。
|
||
- dedup reason。
|
||
|
||
## 6. Skill / Playbook 流程
|
||
|
||
当前 Skill 是诊断流程编排提示，不是事实证据来源。Planner 只能看到 `SkillRegistry.listAll()` 暴露的 name/description 元数据；Executor 才能通过 Spring AI Alibaba 官方 `SkillsAgentHook` 使用 `read_skill` 读取完整 `SKILL.md`。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Registry["SkillRegistry<br/>active skill metadata"] --> PlannerHook["PlannerSkillMetadataHook"]
|
||
PlannerHook --> Planner["Planner<br/>metadata only"]
|
||
Planner --> Plan["planner_plan<br/>selected_skill + steps"]
|
||
|
||
Registry --> ExecutorHook["SkillsAgentHook"]
|
||
ExecutorHook --> ReadSkill["read_skill"]
|
||
Plan --> Executor["Executor"]
|
||
Executor --> ReadSkill
|
||
ReadSkill --> SkillBody["SKILL.md workflow"]
|
||
SkillBody --> Executor
|
||
Executor --> EvidenceTools["lookup_knowledge / logs / metrics"]
|
||
EvidenceTools --> ToolTrace["tool_invocation evidence"]
|
||
Executor --> Verifier["Verifier"]
|
||
ToolTrace --> Verifier
|
||
```
|
||
|
||
| 角色 | Skill 可见性 | 工具权限 |
|
||
|---|---|---|
|
||
| Planner | 只看 skill name / description，并输出 `selected_skill` | 不暴露 `read_skill` |
|
||
| Executor | 读取 Planner 选中的 skill 正文 | 暴露官方 `read_skill` 和证据工具 |
|
||
| Verifier | 不看 skill catalog，也不读 skill 正文 | 只读取 `tool_trace_summary` |
|
||
|
||
## 7. 与旧版设计的差异
|
||
|
||
| 旧版设想 | 当前实现 |
|
||
|---|---|
|
||
| Supervisor + Planner + 多个专科 SubAgent + Verifier | Chat: Planner + Executor + Verifier；AIOps: Supervisor + Planner + Executor |
|
||
| ExternalApiSubAgent / InternalErrorSubAgent / DatabaseSubAgent | 暂未拆分，能力通过通用 Executor + 工具 + Prompt 约束实现 |
|
||
| 每个 SubAgent 专属工具集 | 当前 Executor 持有统一证据工具集合 |
|
||
| Verifier 支持 PASS / REVISE / REJECT | 当前 Chat Verifier 输出 PASS / LOW_CONFID / REJECT |
|
||
| Skill 驱动不同诊断流程 | 当前以 Planner 元数据选择 + Executor 读取 playbook 的方式接入 |
|
||
|
||
## 8. 后续演进
|
||
|
||
当诊断场景和工具复杂度继续上升时，再考虑拆分：
|
||
|
||
- `ExternalApiSubAgent`：接口文档、错误码、请求参数、第三方日志。
|
||
- `DatabaseSubAgent`：连接池、慢 SQL、死锁、索引建议。
|
||
- `CacheSubAgent`：Redis 超时、连接、热点 key、内存风险。
|
||
- `GenericDiagnosisSubAgent`：专项 Agent 失败后的兜底。
|
||
|
||
拆分前提：
|
||
|
||
- 当前 Executor prompt 已难以维护。
|
||
- 不同故障类型的工具权限明显不同。
|
||
- Trace 能证明某类问题需要独立的推理策略。
|
||
- 评测集能覆盖拆分前后的行为差异。
|