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 全景

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，顺序固定：

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 链路最多支持两轮验证：

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：

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 可用工具来自两类：

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。

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 能证明某类问题需要独立的推理策略。
评测集能覆盖拆分前后的行为差异。

7.5 KiB Raw Blame History Unescape Escape