osiman/SuperBizAgent-java

Fork 0

Files

T

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

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

5.7 KiB

Raw Blame History

Agent 架构演进路线

更新日期：2026-07-20 状态：后续演进设计，不代表当前已实现
参考历史文档：archive/2026-07-05-legacy/agent-architecture.md

1. 为什么需要演进路线

旧版 agent-architecture.md 包含很多生产级设想：专科 SubAgent、完整 Skill 治理、进程隔离、跨 Agent 回退、MCP 工具协议化、进化引擎。当前已经落地 bounded StateGraph、安全 Fallback 和基础 Skill/Playbook 接入；本文件只描述它们之上的后续增强。

当前原则：

当前文档只声明已经可运行或明确落地的能力。
演进路线记录未来方向和触发条件。
每个演进项必须有可验证收益，不能只因为“架构更炫”就拆。

2. 演进总图

flowchart TD
    MVP["Current MVP: bounded StateGraph + evidence gates"] --> Split{"Executor 是否过载?"}
    Split -->|是| SubAgents["专科 SubAgent"]
    Split -->|否| Keep["继续强化通用 Executor"]

    SubAgents --> Skills["Skill / Playbook 版本化治理"]
    Skills --> Fallback["跨 SubAgent 回退路由"]
    Fallback --> Isolation["进程或 Pod 隔离"]

    MVP --> ToolGrowth{"工具数量和来源是否增长?"}
    ToolGrowth -->|是| MCP["MCP / Tool Server 协议化"]
    ToolGrowth -->|否| ToolCallbacks["继续使用 @Tool / ToolCallback"]

    MVP --> EvalGrowth{"评测数据是否足够?"}
    EvalGrowth -->|是| Evolution["Prompt / Skill 进化引擎"]
    EvalGrowth -->|否| Baseline["先扩大 baseline"]

3. 专科 SubAgent

触发条件

Executor prompt 变得臃肿，难以同时覆盖接口、数据库、缓存、网络等场景。
不同故障类型需要明显不同的工具权限。
Trace 显示某些场景经常走错排查路径。
评测集已经能衡量拆分前后的收益。

候选 SubAgent

SubAgent	场景	工具倾向
`ExternalApiSubAgent`	错误码、接口参数、第三方调用失败	`lookup_knowledge`, logs, trace
`DatabaseSubAgent`	连接池、慢 SQL、死锁、数据库不可用	metrics, logs, knowledge
`CacheSubAgent`	Redis 超时、热点 key、内存风险	metrics, logs, knowledge
`GenericDiagnosisSubAgent`	兜底诊断	全量只读证据工具

不立即拆分的原因

当前 MVP 的工具规模还可由通用 Executor 管理。
过早拆分会增加 Prompt、评测和 trace 分析成本。
没有足够分类评测前，拆分可能只是移动复杂度。

4. Skill / Playbook 版本化治理

当前已经通过 Planner metadata selection + Executor read_skill 接入诊断 Playbook。下一阶段不是重新建设 Skill 入口，而是增加版本、评测、回退和审计治理。

fault_category
  -> playbook
      -> required evidence
      -> tool sequence
      -> stop condition
      -> report template
      -> evaluation checks

当前已覆盖的方向：

AIOps 告警处理 Playbook。
支付超时 Playbook。
MySQL 连接池风险 Playbook。
Redis timeout Playbook。

后续增强前提：

每个 Playbook 至少有 3-5 个 eval case。
Playbook 失败时可以回退到通用 Executor。
Trace 中能标记使用了哪个 Playbook 和哪个版本。

5. 回退路由

当前 Chat 已有低置信补证据和 REJECT 降级输出。后续如果引入 SubAgent，可扩展为：

Specialized SubAgent
  -> failed / low confidence
  -> another specialized SubAgent
  -> GenericDiagnosisSubAgent
  -> degraded answer with confirmed facts only

回退依据：

工具连续失败。
Verifier REJECT。
Verifier LOW_CONFID 且补证据失败。
Agent 输出缺失关键报告字段。

6. 进程隔离

当前所有 Agent 在同一 JVM 内运行。生产级隔离可以考虑：

API service
  -> Supervisor service
  -> Planner service
  -> SubAgent services
  -> Verifier service

触发条件：

某类 Agent 需要独立扩缩容。
某类工具依赖不稳定，可能拖垮主应用。
不同 Agent 需要不同权限和网络访问策略。
单 JVM 内资源隔离不足。

MVP 阶段暂不拆分进程，优先保证 trace、评测和工具边界清晰。

7. MCP / Tool Server 协议化

当前工具主要通过 @Tool、methodTools 和 ToolCallbackProvider 暴露。工具数量增加后，可演进为：

Agent
  -> Tool registry
  -> MCP / tool server
      -> log server
      -> metrics server
      -> knowledge server
      -> ticket/change server

收益：

工具独立部署。
新工具上线不必重发主应用。
不同 Agent 可获得不同工具子集。
工具调用协议统一，更利于审计。

风险：

调用链更长。
权限和超时治理更复杂。
本地开发和 Demo 成本上升。

8. 进化引擎

旧版文档提到从诊断中学习。当前可以拆成更务实的步骤：

先扩大 diagnosis eval 和 RAG eval。
从失败 trace 中标注 bad case。
将高频失败沉淀为 Playbook 或 Prompt 规则。
对 Prompt 版本做离线对比。
足够稳定后再考虑线上 A/B。

不建议 MVP 直接做自动 Prompt 自优化。没有可靠评测和回滚机制时，自动优化更容易引入不可解释变化。

9. 演进优先级

优先级	项目	原因
P0	扩大 eval baseline	没有评测，拆任何架构都难以证明收益
P1	Playbook 化高频故障	可控、可解释、比拆 SubAgent 更轻
P1	完整 evidence block	提升 Verifier 和 Trace 质量
P2	专科 SubAgent	等问题类型和工具权限差异足够明显
P2	AIOps LLM Verifier	规则门禁不足时再引入
P3	MCP 工具协议化	工具来源复杂后再做
P3	进程隔离	生产负载和权限隔离需要明确后再做

5.7 KiB Raw Blame History Unescape Escape