osiman/SuperBizAgent-java

Fork 0

Files

T

zhuyongxin 4b9cf7c5cc refactor(trace): enforce run-only diagnosis model

2026-07-20 14:11:34 +08:00

11 KiB

Raw Blame History

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

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 或隐式前置校验：

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：

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。

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

11 KiB Raw Blame History Unescape Escape