# Agent 编排架构

**更新日期**：2026-07-20
**状态**：当前可运行架构
**参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`

## 1. 设计定位

旧版 Agent 架构把系统描述为 Supervisor、Planner、SubAgent、Verifier 的团队协作。当前 MVP 保留这个核心思想，但实现更收敛：

- Chat 复杂诊断使用有递归上限的显式 StateGraph；正常路径是 `Planner -> Executor -> Gatekeeper -> Verified Input -> Verifier -> Composer`，条件边负责有限技术重试、一次补证据和安全 Fallback。
- 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 --> ChatGraph["ChatDiagnosisGraphRuntime / StateGraph"]
        ChatGraph --> ChatPlanner["Planner Node"]
        ChatPlanner --> ChatExecutor["chat_executor"]
        ChatExecutor --> ChatTools["evidence tools"]
        ChatTools --> ChatExecutor
        ChatExecutor --> ChatGatekeeper["Gatekeeper Node"]
        ChatGatekeeper --> VerifiedInput["Verified Input Node"]
        VerifiedInput --> ChatVerifier["Verifier Node"]
        ChatVerifier --> ChatDecision{"PASS / LOW_CONFID / REJECT"}
        ChatDecision --> ChatComposer["Composer Node"]
        ChatDecision --> ChatFallback["Fallback Node"]
        ChatComposer --> ChatAnswer["final answer"]
        ChatFallback --> ChatAnswer
    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"]
        ChatSession["chat_session"]
        Run["diagnosis_run"]
        Step["agent_step"]
        Invocation["tool_invocation"]
        SelfEval["self_evaluation"]
    end

    ChatService --> ChatSession
    ChatService --> Run
    ChatPlanner --> Step
    ChatExecutor --> Step
    ChatGatekeeper --> SelfEval
    ChatGraph --> Run
    ChatVerifier --> Step
    ChatTools --> Invocation
    ChatDecision --> SelfEval
    ChatComposer --> Step

    AiOpsService --> ChatSession
    AiOpsService --> Run
    AiOpsPlanner --> Step
    AiOpsExecutor --> Step
    AiOpsTools --> Invocation
    AiOpsRule --> SelfEval
```

## 3. Chat 编排

Chat 复杂诊断采用 `ChatDiagnosisGraphRuntime` 执行、`DiagnosisGraphFactory` 编译的 bounded StateGraph。它有一条正常路径和显式条件边，不再依赖固定顺序 Agent 或隐式前置校验：

```text
START -> PLANNER -> EXECUTOR -> GATEKEEPER -> VERIFIED_INPUT -> VERIFIER -> COMPOSER -> END
          |             |             |                         |          |
          + retry       + fallback    + fallback                + retry    + retry/fallback
                                                               + EVIDENCE_RETRY -> PLANNER (最多一次)
```

关键行为：

| 角色 | 当前职责 | 输出 |
|---|---|---|
| `chat_planner` | 拆解问题，注入知识域地图和对话历史，给出排查方向 | `planner_plan` |
| `chat_executor` | 按计划调用证据工具，抽取带 `source_invocation_id + raw_path + evidence_excerpt` 的微观事实 | `executor_evidence_v2` |
| `GatekeeperNode` / `ExecutorGatekeeperService` | 按当前 `runId` 做代码级引用验真，拒绝伪造 ID、错配 raw_path、错配 excerpt | `gatekeeper_result` |
| `VerifiedInputNode` | 只投影 Gatekeeper 通过的 claims 与 matched evidence，隔离完整工具 Trace | `verified_executor_output`、`verified_evidence` |
| `chat_verifier` | 只判断已验真的 evidence excerpt 是否能推出 claim，不做新检索、不读取完整工具 Trace | `verifier_output` |
| `chat_composer` | 只表达 Verifier 允许输出的 claims、缺口和建议，生成最终用户答复 | `composer_output` |
| `FallbackNode` | 在不可恢复失败或路由上限触发时生成非空安全答复 | `final_answer`、degraded trace |

Chat Graph 支持有限技术重试，并只允许一次 evidence retry；所有分支最终进入 Composer 或 Fallback：

```mermaid
sequenceDiagram
    autonumber
    participant C as ChatService / StateGraph
    participant P as chat_planner
    participant E as chat_executor
    participant T as tools
    participant G as gatekeeper
    participant V as chat_verifier
    participant M as chat_composer
    participant R as diagnosis_run

    C->>P: 原始问题 + history + retry_context
    P-->>C: planner_plan
    C->>E: planner_plan + 上下文
    E->>T: 调用证据工具
    T-->>E: 证据结果
    E-->>C: executor_evidence_v2
    C->>G: executor_output + run-owned tool_invocation.evidence_refs
    G-->>C: gatekeeper_result
    C->>C: VerifiedInputNode projects passed claims/evidence
    C->>V: verified_executor_output + verified_evidence + gatekeeper_audit
    V-->>C: PASS / LOW_CONFID / REJECT
    C->>R: 写入 verifier_evaluation
    alt LOW_CONFID 且允许一次补证据
        C->>P: retry_context: 仅补缺失证据
    else PASS / LOW_CONFID 可输出
        C->>M: allowed_claims + missing_info + recommended_actions
        M-->>C: composer_output
        C->>R: 保存 Composer 最终 answer
    else 不可恢复失败
        C->>R: Fallback 安全答复
    end
    C->>R: 保存 orchestration_trace(version/transitions/final_node/termination_reason/degraded/evidence_retry_count)
```

决策语义：

| Verdict | 行为 |
|---|---|
| `PASS` | 把 Verifier 允许表达的 claims 交给 Composer 输出 |
| `LOW_CONFID` | 如果分数低于阈值且仍有轮次，构造 `retry_context` 补证据；否则输出低置信提示 |
| `REJECT` | Verifier 完成后仍进入 Composer，但 Composer 只能表达允许材料和诊断限制；Gatekeeper REJECT 才直接进入 Fallback |

### 3.1 运行时边界

- 外层 Graph 使用 `runId` 作为 `RunnableConfig.threadId`，metadata 只承载 `sessionId/runId` 等业务身份。
- `ReactAgentDiagnosisInvoker` 为 nested Agent 创建独立 config，不传播外层 human-feedback、state-update、checkpoint/resume 控制 metadata。
- Graph State 默认 replace，只有 `orchestration_events` append；事件使用 portable Map，避免 DevTools classloader 的 record identity 问题。
- Planner、Verifier、Composer 各最多一次技术重试；evidence retry 独立计数且最多一次；Graph recursion limit 为 32。
- `DiagnosisGraphResultMapper` 负责质量评估，`DiagnosisOrchestrationTraceBuilder` 负责路由摘要，两者分别写入 `self_evaluation` 和 `orchestration_trace`。

完整运行时拓扑、路由表和失败语义见 [stategraph-runtime-architecture.md](stategraph-runtime-architecture.md)。

## 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 --> Gatekeeper["Gatekeeper"]
    Gatekeeper --> Verifier["Verifier"]
    ToolTrace --> Verifier
    Verifier --> Composer["Composer"]
```

| 角色 | Skill 可见性 | 工具权限 |
|---|---|---|
| Planner | 只看 skill name / description，并输出 `selected_skill` | 不暴露 `read_skill` |
| Executor | 读取 Planner 选中的 skill 正文 | 暴露官方 `read_skill` 和证据工具 |
| Gatekeeper | 不看 skill catalog，也不读 skill 正文 | 只读取 Executor 输出和 `tool_invocation.retrieval_details.evidence_refs` |
| Verifier | 不看 skill catalog，也不读 skill 正文 | 只读取 Verified Input 投影和 Gatekeeper audit |
| Composer | 不看 skill catalog，也不读 skill 正文 | 只读取 Verifier 允许表达的内容 |

## 7. 与旧版设计的差异

| 旧版设想 | 当前实现 |
|---|---|
| Supervisor + Planner + 多个专科 SubAgent + Verifier | Chat: Planner + Executor + Gatekeeper + Verifier + Composer；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 能证明某类问题需要独立的推理策略。
- 评测集能覆盖拆分前后的行为差异。