SuperBizAgent-java/mvp/architecture/agent-orchestration.md

Agent 编排架构

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

1. 设计定位

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

• Chat 链路使用固定顺序工作流：Planner -> Executor -> Gatekeeper -> Verifier -> Composer。
• 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 --> ChatGatekeeper["ExecutorGatekeeperService"]
        ChatGatekeeper --> ChatVerifier["chat_verifier"]
        ChatVerifier --> ChatDecision{"PASS / LOW_CONFID / REJECT"}
        ChatDecision --> ChatComposer["chat_composer"]
        ChatComposer --> 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"]
        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
    ChatVerifier --> Step
    ChatTools --> Invocation
    ChatDecision --> SelfEval
    ChatComposer --> Step

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

3. Chat 编排

Chat 复杂诊断采用 SequentialAgent，顺序固定：

chat_planner
  -> chat_executor
      -> lookup_knowledge / query_logs / query_metrics / date_time
      -> outputs executor_evidence_v2
  -> VerifierInputHook / ExecutorGatekeeperService
      -> validates source_invocation_id / raw_path / evidence_excerpt
  -> chat_verifier
      -> judges whether verified evidence can derive claims
  -> chat_composer
      -> writes final user-facing answer

关键行为：

角色	当前职责	输出
chat_planner	拆解问题，注入知识域地图和对话历史，给出排查方向	planner_plan
chat_executor	按计划调用证据工具，抽取带 source_invocation_id + raw_path + evidence_excerpt 的微观事实	executor_evidence_v2
ExecutorGatekeeperService	在 Verifier 前做代码级引用验真，拒绝伪造 ID、错配 raw_path、错配 excerpt	gatekeeper_result
chat_verifier	只判断已验真 evidence excerpt 是否能推出 claim，不做新检索	verifier_output
chat_composer	只表达 Verifier 允许输出的 claims、缺口和建议，生成最终用户答复	composer_output

Chat 链路最多支持两轮验证：

sequenceDiagram
    autonumber
    participant C as ChatService
    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_structured_output + tool_invocation.evidence_refs
    G-->>C: gatekeeper_result
    C->>V: executor_structured_output + gatekeeper_result + tool_trace_summary
    V-->>C: PASS / LOW_CONFID / REJECT
    C->>R: 写入 verifier_evaluation
    alt LOW_CONFID 且允许补证据
        C->>P: retry_context: 仅补缺失证据
    else PASS 或 REJECT
        C->>M: allowed_claims + missing_info + recommended_actions
        M-->>C: composer_output
        C->>R: 保存 Composer 最终 answer
    end

决策语义：

Verdict	行为
PASS	把 Verifier 允许表达的 claims 交给 Composer 输出
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 --> 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 正文	只读取 Gatekeeper 结果、结构化 claims 和 trace summary
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 能证明某类问题需要独立的推理策略。
• 评测集能覆盖拆分前后的行为差异。