企业级 Agent 系统架构设计：从循环引擎到信任层级的完整技术方案

2026/4/8

#AI技术#架构设计

企业级 Agent 系统架构设计：从循环引擎到信任层级的完整技术方案

基于真实项目实践——将一个拥有数百个 API 的企业级平台，从”人在 UI 上操作”演进为”意图驱动的 Agent 智能体系统”。约 2800 行设计文档，19 轮迭代，~3 天完成。

本文的目标读者：正在设计或即将设计企业级 Agent 系统的架构师。如果你面对的是”已有一套复杂的企业平台，要在上面加一层 Agent 大脑”的问题，这篇文章提供了完整的架构参考。

一、Agent 系统是什么——从”人操作 UI”到”意图即操作”

1.1 范式跳跃

传统平台：人 → 固定 UI → 各模块独立操作 → 人脑串联结果
Agent 平台：人 → 对话 → Agent 大脑 → MCP 工具（= 各模块的原子化接口）→ Agent 自动串联

Agent 不是平台上面的一层壳——Agent 就是平台本身。

已有平台的每个模块都是 Agent 的”器官”。Agent 系统做的是给这些器官加上”大脑”（Agent Brain）、“自生长能力”（工厂 Agent）和”肌肉记忆”（经验固化），并把”固定 UI + 用户旅程”替换为”意图即操作的对话界面”。

四层能力递进：

层次	能力	一句话
层次一	对话即平台	自然语言对话取代传统 UI，所有能力原子化为 MCP 工具，Agent 大脑是平台的操作系统
层次二	按需呈现	Agent 大脑从 Schema 约束的信息呈现原语中按需选取图表、表格、时间线等嵌入对话
层次三	经验自固化	通过行为分析，将 Agent 反复执行的行动模式自动沉淀为确定性工作流
层次四	能力自生产	AI 自主识别能力缺口，自主生成规则、子 Agent、测试用例等结构化制品

1.2 两个关键设计选择

Schema 约束的有限解空间：Agent 的”生成”不是写任意代码，而是在 Schema 约束下组装结构化制品——有限解空间 + 自动化验证 + 热加载生效
不设计用户旅程：客户有意图，Agent 理解并执行，中间不需要”旅程”。客户可能说出产品经理从未想过的需求，对话式交互天然支持这种不可预测性

二、架构全景

2.1 分层架构

┌─────────────────────────────────────────────────────────────────┐
│                    👤 用户（自然语言对话）                          │
└───────────────────────────┬─────────────────────────────────────┘
                            ↕
┌───────────────────────────┴─────────────────────────────────────┐
│                   对话引擎 + AG-UI 渲染器                         │
│              （唯一交互入口，信息呈现原语按需嵌入）                  │
└───────────────────────────┬─────────────────────────────────────┘
                            ↕
┌───────────────────────────┴─────────────────────────────────────┐
│                    🧠 Agent 大脑（平台操作系统）                    │
│          意图理解 · 任务规划 · 全局态势感知 · 子 Agent 调度          │
│                       长期记忆                                    │
├─────────────┬──────────────┬────────────────────────────────────┤
│  子 Agent    │  工厂 Agent   │  信任层级执行框架                    │
│  1+N 专项    │  规则/Agent   │  L0自主→L1事后→L2审批→L3多人审批    │
│  角色集群     │  工作流/模板   │                                    │
└──────┬──────┴──────┬───────┴────────────────────────────────────┘
       ↕             ↕
┌──────┴─────────────┴────────────────────────────────────────────┐
│              🔧 MCP Tool 层（原子工具 · 五类分级）                  │
│    👁感知  🧠决策  ⚡执行  💾记忆  📊呈现                          │
├─────────────────────────────────────────────────────────────────┤
│              📦 制品体系（Schema Registry + Artifact Store）       │
└───────────────────────────┬─────────────────────────────────────┘
                            ↕
┌───────────────────────────┴─────────────────────────────────────┐
│              ⚙️ 已有平台能力底座（现有各模块 · 不变）                │
│              模块A · 模块B · 模块C · 模块D · IAM · ...             │
├─────────────────────────────────────────────────────────────────┤
│              数据层（消息队列 · 时序数据库 · 关系型数据库）           │
└─────────────────────────────────────────────────────────────────┘

分层说明：

对话层（新增）：用户唯一入口，替代传统 UI
智能层（新增）：Agent 大脑 + 子 Agent + 工厂 Agent + 信任层级
工具层（新增）：MCP Tool 原子接口 + 制品体系
能力层（继承）：已有平台所有现有模块，通过 MCP Tool 层被 Agent 调用
数据层（继承）：数据库、消息队列、通信链路

2.2 Agent 引擎内部架构

以下将全景图中”新增层”展开，展示一次用户请求从进入到响应的完整数据流：

                          👤 用户输入（自然语言）
                                  │
                ┌─────────────────▼──────────────────────────────────┐
                │              Agent 循环引擎（核心）                  │
                │                                                    │
  ┌──────────┐  │  ① 意图识别 ──→ ② 任务规划 ──→ ③ 工具选择         │  ┌──────────┐
  │ 上下文管理 │──▶      │              │                │            │  │ 模型路由器 │
  │          │  │      │         复杂任务分派         │            │◀─│          │
  │ ·规范文件 │  │      │              │                ▼            │  │ ·企业白名单│
  │ ·ToolSearch│ │      │              ▼        ④ 权限决策（五层）    │  │ ·内网优先 │
  │ ·PromptCache││      │        ┌──────────┐    L5企业策略          │  │ ·按需fallback│
  │ ·Compaction│ │      │        │ 子Agent  │    L4信任层级          │  └──────────┘
  └──────────┘  │      │        │ 调度(1+N)│    L3 Hook拦截         │
                │      │        └────┬─────┘    L2 审计记录          │  ┌──────────┐
  ┌──────────┐  │      │             │          L1 人工确认          │  │ 配置系统  │
  │ 持久化层  │◀─│──────│─────────────│──────────────│               │──▶│          │
  │          │  │      │             │              ▼               │  │ ·企业策略 │
  │ ·会话转录 │  │      │             │        ⑤ MCP Tool 执行      │  │ ·用户偏好 │
  │ ·行动轨迹 │  │      │             │              │               │  └──────────┘
  │ ·长期记忆 │  │      │             │              ▼               │
  │ ·审计日志 │  │      │             └──────→ ⑥ 结果回传            │  ┌──────────┐
  └──────────┘  │      │                          │                 │  │ 观测系统  │
                │      │    ┌──────────┐    未完成 │  尝试退出        │──▶│          │
  ┌──────────┐  │      │    │ 工厂Agent │          │      │         │  │ ·Traces  │
  │ 工厂Agent │◀─│──能力缺口 │(延后启动) │    ┌─────▼──────▼───────┐  │  │ ·Metrics │
  │ (延后启动) │  │      │    └──────────┘    │ ⑦ Stop Hook 完成度  │  │  │ ·Logs    │
  └──────────┘  │      │                    │ approve→退出循环     │  │  └──────────┘
                │      └────────────────────│ block →继续循环      │  │
                │                           └──────────┬──────────┘  │
                └──────────────────────────────────────┼─────────────┘
                                                       ▼
                                👤 用户响应（文字 + 可视化组件 + 审批卡片）

架构说明：

核心循环：① 意图识别 → ② 任务规划 → ③ 工具选择 → ④ 权限决策（五层）→ ⑤ 工具执行 → ⑥ 结果回传 → 循环或退出。⑦ Stop Hook 检查完成度，未完成则自迭代
模型路由器：每次 LLM 推理前，根据企业配置 + 网络环境 + 数据敏感度选择最优模型，内网优先，按策略 fallback
上下文管理：规范文件 + ToolSearch 按需加载 + Prompt Cache + Compaction，控制每次推理的输入质量和 token 成本
配置系统：企业→用户两级配置，注入到模型路由器和权限决策引擎
子 Agent 调度：从任务规划步骤分叉，独立执行后将结论+证据+轨迹回传
持久化层：循环中四个写入点——执行写轨迹、权限写审计、结果写转录、意图读写记忆
观测系统：采集循环每一步的 Traces / Metrics / Logs

三、Agent 框架选型——从 9 个框架中提炼设计精华

本节不是”从 N 个框架中选一个”，而是从主流框架中提炼设计精华，结合企业场景的独特需求，设计最合适的 Agent 引擎。

3.1 主流 Agent 框架能力全景

框架	核心模式	工具调用	多 Agent	上下文管理	扩展方式	运行形态
Claude Code	Agent 循环 + 事件钩子 + 分层插件	MCP 原生	SubAgent/Teammate/Task 三级	CLAUDE.md + Skill 三级 + Compaction + ToolSearch	Hook/Skill/MCP/Command	本地 CLI（TypeScript/Bun）
OpenAI Codex CLI	统一 App Server + CodeAct	JSON Schema + MCP	有限	线程级	IDE 插件	本地 CLI + IDE
Cursor	VS Code Fork + Composer	多模型切换	8 Agent 并行	Git 历史 + 编辑器	插件市场	IDE 内嵌
LangGraph	状态图 DAG + 检查点	统一接口	状态机 + 人工审批	检查点持久化	自定义节点	Python 库
CrewAI	角色化团队 + Manager	工具注册	层级式分派	最小化	自定义 Agent	Python 库
AutoGen	事件驱动消息传递	函数工具	异步拓扑	可定制	组件化	Python 库
Dify	可视化工作流 DAG	多类型 + MCP	工作流内链式	RAG 集成	插件系统	Web 平台
Coze/扣子	全生命周期管理	Skill 体系	有限	全链路 Tracing	Skill 生态	Web 平台

3.2 选型评估

企业级 Agent 需要的是一个可嵌入私有化部署环境的 Agent 引擎——以独立服务端进程运行，支持多用户并发会话，权限控制内建到引擎核心。

一、按产品形态分类

分类	框架	运行形态	与企业场景的适配度
本地工具型	Claude Code、Codex CLI、Cursor	本地 CLI / IDE 内嵌	产品形态不匹配——企业 Agent 是服务端多用户系统。但设计理念高度可参考
通用编排库	LangGraph、CrewAI、AutoGen	Python 库，可包装为微服务	运行形态可适配——但需评估领域需求支持能力
平台型	Dify、Coze	Web 托管平台	不可私有化嵌入

关键区分：产品形态不匹配 ≠ 没有参考价值。“不能直接用”和”不值得学”是两件事。

二、通用编排库详细评估

LangGraph（最接近可用）

维度	评估
架构优势	状态图 DAG + 检查点恢复机制成熟；Human-in-the-loop 作为一等公民
可借鉴	状态机管理（任务的进行中/等待审批/已完成状态）；审批作为正常流程
不能直接用	① 状态图 DAG 适合固定工作流，Agent 循环是开放式推理（每轮工具选择不可预测），用 DAG 建模会过度约束；② Human-in-the-loop 有但不是”引擎原生信任层级”——审批是流程节点，企业需要的是每次工具调用前的信任层级评估，粒度不同；③ 无多用户会话隔离、无审计、无领域感知

CrewAI（角色模型好，框架太轻）

维度	评估
架构优势	角色化 Agent + Manager 分派模型直觉好
可借鉴	Manager 模式的 1+N 子 Agent 分工
不能直接用	① 无权限控制、无审计、无 Hook 体系；② 上下文管理最小化，无法承载大型上下文（数百工具清单 + 规范文件 + 用户配置）；③ 框架面向轻量原型，不适合生产级系统的长期演进

AutoGen（通信模型好，稳定性存疑）

维度	评估
架构优势	事件驱动消息传递架构设计好，支持异步拓扑
可借鉴	子 Agent 间通过结构化消息（task→conclusion+evidence）通信
不能直接用	① 核心 API 正在重写，选择正在重构的框架做生产系统基础风险太高；② 事件驱动适合跨进程分布式场景，同一引擎内的 Agent 不需要这层复杂度

三、企业领域需求 vs 框架能力差距

上述框架各有设计亮点。但它们共同缺失以下企业领域需求——不是”配置一下就能满足”的功能缺失，而是框架从设计之初就没有考虑的场景：

企业领域需求	说明	通用框架的现状
信任层级原生化	L0-L3 是 Agent 循环引擎的核心数据结构——每次工具调用前评估，不是可选插件	无此概念，需侵入框架内核实现
多用户会话隔离	同一引擎实例内，不同用户的上下文/记忆/配置/工具权限完全隔离	面向单用户设计
合规级审计不可关闭	每次工具调用自动产出不可篡改的审计记录	审计是可选功能
制品 Schema 体系	引擎原生集成 Schema Registry，工厂 Agent 生成制品时自动校验	无此概念
经验固化闭环	行动轨迹 → 行为分析 → 工作流提炼 → Skill 替代 LLM 推理	无此概念

在现有框架上定制实现这些能力，等于在框架内核中插入大量侵入式代码。长期维护成本不低于自研。

3.3 从各框架提炼的 12 条设计精华

自研不等于从零发明。以下设计理念从各框架中提炼，直接复用：

#	设计理念	提炼来源	在企业 Agent 中的应用
1	Agent 循环引擎（LLM→权限→执行→回传→循环）	Claude Code	Agent Loop 核心骨架，每步内建信任层级检查
2	状态图 + 检查点恢复	LangGraph	任务状态机管理、会话中断恢复
3	角色化 Agent + Manager 分派	CrewAI	顶层 Agent 作为 Manager，子 Agent 按角色分化
4	事件驱动消息传递	AutoGen	子 Agent 间通过结构化消息通信
5	递归任务分解 + 深度自主规划	企业级 Agent 平台实践	多步任务规划，每步检查依赖和信任层级
6	Skill 市场架构理念	企业级 Agent 平台实践	Schema 约束的结构化制品生态
7	事件钩子体系（生命周期拦截）	Claude Code	15 个事件，审计和权限控制通过 Hook 实现
8	Human-in-the-loop 一等公民	LangGraph	L2 审批是”正常流程”而非”异常路径”
9	上下文分层管理（Compaction / ToolSearch）	Claude Code	大规模工具三档加载、自动压缩断路器、大输出外溢
10	五层纵深权限模型	Claude Code	企业策略→信任层级→Hook 拦截→审计→人工确认
11	MCP 工具协议	Claude Code / Dify	标准化工具接口，与外部系统互操作的基础
12	全链路 Tracing	Coze Loop	每次推理和工具调用的完整追踪链

来源分布：Claude Code 5 条（循环引擎/钩子/上下文/权限/MCP），是贡献最多的——因为它是唯一经过大规模生产验证的 Agent 系统。

3.4 技术选型总结

决策项	选型	核心理由
Agent 引擎	Python 自研，独立微服务部署	9 框架评估均不满足企业领域需求；自研引擎，设计模式从框架精华提炼
开发语言	Python（asyncio 并发模型）	Agent 引擎 95% I/O 密集（等 LLM 响应、等 HTTP 返回），asyncio 完美匹配；Python AI 生态远超其他语言
工具协议	MCP（Model Context Protocol）	行业标准，与外部系统互操作的基础
LLM 接口	统一适配层，多厂商	模型无关架构——多厂商通过统一接口适配，模型切换不影响业务逻辑
前端协议	AG-UI（Agent-User Interface）	流式通信 + 呈现原语嵌入，Human-in-the-loop 审批作为一等公民
与已有平台的关系	独立微服务，REST API/MCP 通信	Agent 引擎与已有后端语言解耦、进程隔离——Agent 崩溃不影响已有平台核心功能

自研范围界定——不是所有东西都自研：

范围	自研/复用/标准	说明
Agent 循环引擎（核心循环 + 权限决策 + 状态管理）	自研	信任层级、审计、会话隔离深度内建
事件钩子体系	自研（设计参考 Claude Code）	通用事件 + 领域特有事件
子 Agent 调度协议	自研（设计参考 CrewAI + AutoGen）	角色化分派 + 结构化消息传递
MCP Tool 层	采用标准协议	MCP 标准，使用官方 SDK
LLM 调用层	复用开源 SDK + 自研路由逻辑	各厂商 SDK 处理通信，自研路由器
上下文管理（Compaction / ToolSearch / Prompt Cache）	自研（设计参考 Claude Code）	上下文压缩和工具按需加载与约束保护深度耦合
持久化层	复用已有基础设施	PostgreSQL / ClickHouse / Redis
观测系统	采用标准协议	OpenTelemetry
Schema Registry	自研（轻量级）	JSON Schema 校验，需与引擎深度集成

四、Agent 核心引擎

本章描述 Agent 引擎的核心运转机制——Agent 循环如何工作、子 Agent 如何协作。

4.1 Agent 大脑（顶层 Agent）

4.1.1 定位与职责

Agent 大脑是整个系统的操作系统内核——用户对话的直接对象，所有任务的调度中枢。

职责	说明
意图理解	解析自然语言，映射到具体操作
任务规划	将复杂意图分解为多步执行计划，决定调用哪些工具或子 Agent
全局态势感知	持续监控业务事件流、状态变化，主动发现并推送风险
子 Agent 调度	将专项任务分派给对应子 Agent，汇总结果后组装响应
结果呈现	决定用文字、图表还是表格呈现结果——呈现方式选择是推理的一部分
长期记忆	记录用户偏好、历史结论、经验模式，跨会话保持上下文连续性

4.1.2 运行模式

被动模式（用户驱动）——用户发起对话，Agent 响应：

用户："最近有没有异常？"
  → Agent 大脑调用 event.query() + status.check() + health.overview()
  → 推理、关联
  → 组装响应（文字结论 + 指标卡片 + 事件表格）

主动模式（自主巡检）——Agent 后台持续监控，主动推送：

Agent 大脑后台持续监控：
  → 发现业务指标异常飙升
  → 自动调用 event.query() 关联分析
  → 判断需要人关注
  → 主动推送："检测到用户 X 的操作模式异常，建议排查"
  → 用户确认后，调度分析员深入调查

Headless 模式（API/SDK 驱动）——无人交互，供外部系统调用：

外部系统通过 SDK/API 发送指令：
  → Agent 大脑接收结构化任务
  → 执行预定义工作流（如：定时全量检查、定时态势报告）
  → 结果写入持久化层，通知外部系统
  → L2 操作降级为排队等待人工审批

4.1.3 Agent 循环引擎状态机

这是最核心的组件——所有 Agent 行为都在这个循环中发生。

                    ┌──────────────────────────┐
                    │      IDLE（空闲）          │
                    │   等待用户输入 or 主动触发   │
                    └────────────┬─────────────┘
                                 │ 收到输入
                                 ▼
                    ┌──────────────────────────┐
              ┌────→│    REASONING（推理中）      │
              │     │  LLM 推理：意图→工具选择    │
              │     └────────────┬─────────────┘
              │                  │ 产出工具调用请求
              │                  ▼
              │     ┌──────────────────────────┐
              │     │  PERMISSION（权限评估中）    │
              │     │  五层决策引擎评估            │
              │     └──┬──────┬──────┬─────────┘
              │        │      │      │
              │     denied  approved  need_approval
              │        │      │      │
              │        ▼      ▼      ▼
              │     跳过   ┌──────┐  推送审批卡片
              │     执行   │EXEC  │  等待用户响应
              │      │    │执行中 │     │
              │      │    └──┬───┘     │
              │      │       │         │
              │      ▼       ▼         ▼
              │     ┌──────────────────────────┐
              │     │   RESULT（结果处理）        │
              │     │  PostToolUse Hook → 审计   │
              │     │  结果注入上下文              │
              │     └────────────┬─────────────┘
              │                  │
              │           ┌──────┴──────┐
              │           │             │
              │        未完成        尝试退出
              │           │             │
              └───────────┘             ▼
                               ┌──────────────────┐
                               │  STOP_CHECK       │
                               │  Stop Hook 检查    │
                               └──┬──────┬────────┘
                                  │      │
                               approve  block
                                  │      │
                                  ▼      └──→ 重新注入提示 → REASONING
                            ┌──────────────┐
                            │  COMPLETE     │
                            │  组装响应      │
                            │  写入转录      │
                            └──────────────┘

循环控制参数（全部可通过配置系统调整）：

参数	说明
`max_reasoning_rounds`	单次会话最大推理轮次，防止 Agent 无限循环
`tool_call_timeout`	单次工具调用超时时间
`approval_wait_timeout`	L2 审批等待超时时间
`same_tool_repeat_limit`	连续调用同一工具的最大次数（断路器）
`total_session_timeout`	单次会话总超时时间

异常处理与恢复：

异常场景	处理策略
LLM 调用失败	重试 1 次 → 仍失败则返回错误提示，不中断会话
工具调用超时	PostToolUse Hook 记录超时 → 结果标记为 timeout → Agent 可选择换一个工具重试
权限被拒绝	记录到审计 → 跳过该工具 → Agent 继续推理选择替代方案
循环次数达上限	强制退出 → 返回当前已有结论 + 提示”任务未完成”
同一工具连续调用 N 次	断路器触发 → 强制退出该工具 → Agent 推理选择其他路径
LLM 幻觉不存在的工具	工具注册表校验失败 → 拒绝执行 → 将”工具不存在”作为结果回传 LLM
子 Agent 超时	子 Agent 返回 timeout 状态 → 顶层 Agent 决定是否重派或放弃
上下文溢出	触发 Compaction → 断路器（3 次仍溢出则终止）

循环中的核心数据结构：

数据结构	职责	生命周期
LoopState	循环当前状态（IDLE/REASONING/PERMISSION/EXEC/RESULT/STOP_CHECK/COMPLETE）	单次会话
ConversationCtx	对话上下文（含压缩管理），供每轮 LLM 推理使用	单次会话，Compaction 管理
ToolRegistry	MCP Tool 注册表（只读引用），循环中查询工具 Schema 和信任层级	全局共享
TrustConfig	当前会话的信任层级配置（从配置系统按用户加载）	单次会话
ActionTrace	本次会话的行动轨迹列表（每次工具调用记录：工具名、输入、输出、权限决策、耗时、钩子结果、时间戳）	单次会话，完成后写入持久化层

4.1.4 上下文管理

Agent 面临的上下文压力远大于编程场景——数百个工具 Schema + 业务规则库 + 历史事件 + 资产台账，不做分层管理必然爆窗口。

四类上下文：

上下文类型	存储位置	生命周期	内容
会话上下文	内存	单次对话	当前多轮对话历史、中间工具调用结果
工作记忆	短期存储（Redis）	当前任务链	任务进度、待确认审批、子 Agent 已返回的结论
长期记忆	持久化存储（PostgreSQL）	永久，跨会话	用户偏好、历史结论、经验模式
态势上下文	实时计算	持续更新	业务事件统计、异常趋势、系统健康度

五大上下文管理机制：

机制一：规范文件（≈ Claude Code 的 CLAUDE.md）

~/.agent/global.md                → 全局运营偏好（管理员级）
    ↓ 覆盖
/user/{userId}/agent.md           → 用户个人偏好

每次会话启动时自动加载，多级文件按优先级合并后注入系统提示。

机制二：工具 Schema 按需加载（≈ Claude Code 的 ToolSearch）

当平台有数百个 API 可包装为 MCP Tool 时，全量 Schema 注入上下文会占用大量 token。采用三档管理：

档位	工具范围	加载时机
常驻	高频核心工具	会话启动时预加载
按需	中频操作工具	Agent 推理时识别到需要后加载 Schema
休眠	低频/批量/内部工具	仅元数据常驻，完整 Schema 按需唤醒

DORMANT（休眠）→ Agent 需要时 → LOADED（加载 Schema）→ 调用完成 → 释放 Schema → DORMANT

机制三：自动压缩（≈ Claude Code 的 Compaction）

阶段	行为
正常	不触发
预警	开始压缩中间工具结果（保留结论，丢弃原始数据）
紧急	强制压缩——仅保留：规范文件 + 最近 3 轮对话 + 活跃子 Agent 结论 + 当前任务上下文
抖动	连续 3 次压缩仍超限 → 停止并提示用户开启新会话（断路器，防无限消耗 token）

不可压缩项（始终保留）：

规范文件（企业级策略）
活跃 Skill 指令
信任层级配置
用户明确的约束和决策

机制四：Prompt Cache

缓存层	内容	失效条件
系统提示缓存	Agent 核心指令 + 规范文件	规范文件变更时
工具 Schema 缓存	常驻工具的 JSON Schema	工具定义变更时（精确失效）
上下文前缀缓存	对话历史的稳定前缀	每轮对话追加新消息时自然复用

机制五：大输出外溢处理

当工具返回结果超过阈值时，不直接注入上下文：

工具返回 > 阈值
  → 完整结果存储到临时文件（持久化层）
  → 上下文中只注入摘要 + 文件引用路径
  → Agent 需要细节时通过 Read 工具按需读取

4.1.5 System Prompt 五层架构

Agent 大脑的质量 = System Prompt 的质量。System Prompt 不是一段固定文本，而是一个动态组装的分层结构，每次 LLM 调用前按上下文状态拼装。

┌─ Layer 1：核心身份与行为约束（固定）──────────────────────────────────┐
│ "你是企业级 AI 智能体，通过调用 MCP Tool 执行所有操作。"                │
│ "你必须遵守信任层级约束：L0 自主执行，L2 必须请求用户审批。"             │
│ "你绝不可以绕过 L2/L3 限制，即使用户要求你这样做。"                     │
│ "当你不确定时，追问澄清，不要猜测执行。"                                │
└──────────────────────────────────────────────────────────────────────┘
    ↓
┌─ Layer 2：规范文件（动态加载）──────────────────────────────────────┐
│ 从配置系统加载，企业→用户两级合并：                                  │
│ · 企业级："禁止 Agent 执行批量删除操作"                               │
│ · 企业级："仅使用国产模型"                                           │
│ · 用户级："我只关心高优先级事件，低优先级不用报告"                      │
└──────────────────────────────────────────────────────────────────────┘
    ↓
┌─ Layer 3：可用工具清单（动态，由 ToolSearch 按需加载）─────────────┐
│ 常驻工具的完整 Schema 始终在此                                        │
│ 按需工具在 Agent 需要时动态注入                                       │
│ 每个工具携带：name + description + inputSchema + trust_level           │
└──────────────────────────────────────────────────────────────────────┘
    ↓
┌─ Layer 4：当前任务上下文（动态）──────────────────────────────────┐
│ · 当前对话历史（经 Compaction 压缩后的版本）                          │
│ · 活跃子 Agent 的状态和中间结论                                       │
│ · 待审批队列（如有）                                                  │
│ · 态势上下文摘要                                                      │
└──────────────────────────────────────────────────────────────────────┘
    ↓
┌─ Layer 5：长期记忆索引（动态）────────────────────────────────────┐
│ 从持久化层加载记忆索引（非全量内容）                                    │
│ Agent 按需读取具体记忆条目                                            │
└──────────────────────────────────────────────────────────────────────┘

子 Agent 的 Prompt 差异：

子 Agent 不继承顶层 Agent 的完整 Prompt，而是接收精简版本：

Prompt 层级	顶层 Agent	子 Agent
Layer 1 核心身份	完整版（全能力）	角色化精简版
Layer 2 规范文件	完整企业规范	仅与本角色相关的规范子集
Layer 3 工具清单	全量常驻工具	仅本角色被授权的工具子集
Layer 4 任务上下文	全局态势	仅本次任务的精简上下文
Layer 5 记忆索引	全量索引	不加载（子 Agent 不需要跨会话记忆）

4.1.6 并发性能架构

企业级 Agent 必须支持多用户并发对话。

┌─ Agent 引擎进程（Python asyncio）──────────────────────────────────┐
│                                                         │
│  ┌─ 用户 A ────────────────────┐                        │
│  │  Session 1 → asyncio task   │                        │
│  │  Session 2 → asyncio task   │   共享 LLM 连接池      │
│  │  (上下文完全隔离)            │   共享 MCP Tool 注册表  │
│  └─────────────────────────────┘   共享 Schema Registry  │
│                                                         │
│  ┌─ 用户 B ────────────────────┐                        │
│  │  Session 3 → asyncio task   │                        │
│  │  (上下文完全隔离)            │                        │
│  └─────────────────────────────┘                        │
│                                                         │
│  ┌─ 共享资源 ──────────────────┐                        │
│  │  LLM 连接池（按模型分组）    │                        │
│  │  MCP Tool 注册表（只读）     │                        │
│  │  Schema Registry（只读）     │                        │
│  │  配置缓存（按用户分片）      │                        │
│  └─────────────────────────────┘                        │
└─────────────────────────────────────────────────────────┘

隔离与共享的边界：

资源	隔离/共享	机制
对话上下文	完全隔离	每个 Session 独立 asyncio task
长期记忆	用户隔离	按 user_id 过滤
行动轨迹	用户隔离	按 user_id 分区
LLM 连接池	共享	按模型分组，协程安全
MCP Tool 注册表	共享（只读）	启动时加载，热加载通过替换实现
Prompt Cache	部分共享	Layer 1 全局共享；Layer 2~5 按用户/会话隔离

4.1.7 意图识别与模型选择

意图识别架构：

用户输入（自然语言）
    ↓
┌─────────────────────────────────────────┐
│ 意图分类器（第一层，快速路由）              │
│                                         │
│ · 直接操作意图 → 调用 MCP Tool            │
│   "帮我查一下今天的事件"                    │
│                                         │
│ · 复杂分析意图 → 分派子 Agent             │
│   "调查这个异常行为的根因"                  │
│                                         │
│ · 闲聊/知识咨询 → 直接回复                │
│   "XXX 模块是什么？"                       │
│                                         │
│ · 模糊意图 → 追问澄清                    │
│   "帮我看看整体态势" → "你想看哪个维度？"    │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│ 任务规划器（第二层，多步编排）              │
│                                         │
│ 复杂任务拆解为多步执行计划：                │
│ "把这个新实体注册完再做检查再接入"            │
│   → Step 1: entity.create()             │
│   → Step 2: check.create()             │
│   → Step 3: 等待检查完成                  │
│   → Step 4: 通过 → policy.create()      │
│   → 每步检查信任层级（L2 操作需审批）       │
└─────────────────────────────────────────┘

模型选择策略：

Agent 引擎不绑定单一模型厂商，通过统一 LLM 接口适配多厂商，按场景差异化配置：

场景	模型要求	推理深度
顶层 Agent（意图理解 + 任务规划）	最强推理 + 长上下文	高
分析类子 Agent（证据推理）	强推理 + 结构化输出	高
操作类子 Agent（规则生成）	结构化生成 + Schema 遵循	中
工厂 Agent（制品生成）	强结构化生成	中
固化工作流执行	无需模型（零 token）	—

4.2 子 Agent 协作架构

角色设计依据：子 Agent 的角色划分基于已有平台实际能力模块（数百个 API）和业务场景反推，不是凭空设计——每个 Agent 背后有明确的 API 领域支撑。

4.2.1 1+N 分层协作体系

采用 1 + N 架构——1 个顶层 Agent 统筹调度 N 个专项子 Agent：

┌──────────────────────────────────────────────────────────────┐
│              🏠 顶层 Agent（Agent 大脑）                         │
│        意图理解 · 全局态势 · 任务分派 · 结果组装                 │
│                 使用最强推理模型                                │
│                 有长期记忆和全局上下文                           │
└───┬────────┬────────┬──────────┬────────────┬────────────────┘
    ↓        ↓        ↓          ↓            ↓
┌───┴──┐ ┌───┴──┐ ┌───┴────┐ ┌───┴──────┐ ┌───┴──────┐
│🔬检查 │ │🛡️配置 │ │📞协作  │ │📦资产    │ │📊分析    │
│专员   │ │专员   │ │专员    │ │管理员    │ │专员      │
│      │ │      │ │       │ │         │ │         │
│质量检查│ │规则调优│ │IM通讯  │ │实体注册  │ │事件分析  │
│测试执行│ │策略生成│ │多渠道  │ │资源管理  │ │日志检索  │
│报告生成│ │效果验证│ │通知    │ │生命周期  │ │趋势分析  │
└──────┘ └──────┘ └───────┘ └─────────┘ └─────────┘

4.2.2 角色设计的三个依据

依据一：能力模块对齐——每个子 Agent 背后有明确的 API 领域

检查专员    ← 检查/评估模块（N 个 API）
配置专员    ← 策略/规则管理模块（N 个 API）
协作专员    ← 通讯/通知模块（N 个 API）
资产管理员  ← 资产管理模块（N 个 API）
分析专员    ← 事件/日志模块（N 个 API）

依据二：多步推理需求——每个角色都有需要 5+ 步工具调用的核心场景

Agent	典型多步场景	步骤数
检查专员	创建任务→等待完成→查结果→查问题→生成建议→重测	7+
配置专员	查当前配置→分析效果→调整规则→推送生效→验证→回滚	6+
协作专员	识别对象→发起通讯→等待回复→追问→汇总→推送给顶层 Agent	5+
资产管理员	创建实体→配置关联→配置规则→生成访问入口→验证	6+
分析专员	查事件列表→查详情→搜日志→关联证据→AI 解读→标记处置	7+

依据三：上下文隔离必要性——每个角色处理的数据量大，塞进主对话会溢出

Agent	典型数据量	为什么要隔离
检查专员	检查报告可能很长	检查细节不应占据用户对话上下文
配置专员	规则库可能有数百条	规则遍历不应暴露在主对话中
协作专员	多轮通讯可能 10+ 轮	与第三方的沟通不应和用户对话混在一起
资产管理员	资产台账列表很长	资产清单遍历不应占据主上下文
分析专员	日志检索可能返回大量原始数据	数据细节应在子 Agent 内消化，只返回结论

4.2.3 协作模式

模式一：串行分派（常见场景）

用户："把这个新实体做完检查再接入"
  → 顶层 Agent 拆解任务
  → Step 1: 分派资产管理员 → 注册实体
  → Step 2: 分派检查专员 → 执行检查
  → Step 3: 检查通过 → 分派配置专员 → 创建策略（L2 审批）
  → Step 4: 审批通过 → 配置专员推送生效
  → 顶层 Agent 汇总结果 → 回复用户

模式二：并行分派（调查场景）

用户："调查这个异常事件的根因"
  → 顶层 Agent 分派两个任务并行：
    ├─ 分析专员 → 查事件详情 + 搜日志 + 关联证据
    └─ 协作专员 → 通讯问询当事人
  → 两者结论汇总到顶层 Agent
  → 综合研判 → 回复用户

模式三：级联触发（自动化场景）

系统检测到新事件
  → 顶层 Agent 判断需要处理
  → 分派分析专员 → 分析结论：需要调整配置
  → 顶层 Agent 转派配置专员 → 生成配置调整方案（L2）
  → 推送审批卡片给用户

4.2.4 调度协议

顶层 Agent 与子 Agent 之间的交互遵循统一协议：

顶层 Agent → 子 Agent：
  {
    task_id: "uuid",
    task_type: "check | config | liaison | asset | analyst",
    context: { ... },       // 精简后的任务上下文（非全局上下文）
    constraints: {
      max_tool_calls: 20,   // 工具调用次数上限
      timeout_seconds: 300, // 超时时间
      trust_level: "L1"     // 该子 Agent 的最高信任层级
    }
  }

子 Agent → 顶层 Agent：
  {
    task_id: "uuid",
    status: "completed | escalated | timeout | waiting_approval",
    conclusion: "...",      // 结论摘要
    evidence: [ ... ],      // 证据链
    actions_taken: [ ... ], // 行动轨迹（供经验固化分析）
    suggested_next: "..."   // 建议的后续操作（可选）
  }

4.2.5 子 Agent Prompt 设计指引

通用约束（所有子 Agent 共享）：

只能使用被授权的工具子集，尝试调用未授权工具时引擎层会拒绝
不能修改自己的信任层级上限
必须在 constraints.max_tool_calls 次数内完成任务
结论必须结构化返回（conclusion + evidence + actions_taken），不能只返回自由文本

Prompt 与引擎的关系：Prompt 引导 LLM “应该做什么”（软约束），引擎层强制 LLM “不能做什么”（硬约束，代码层面不可绕过）。两层互补——Prompt 做意图引导，引擎做兜底。

Prompt 调优方法：先写初版 Prompt → 用意图测试集验证 → 分析失败用例 → 调优 Prompt → 再验证。这是迭代过程，不是一次性交付。

五、安全控制体系

5.1 信任层级执行框架

5.1.1 四级信任模型

企业级 Agent 自主执行必须设计严格的信任边界。将所有操作按风险等级分为四个信任层级：

信任层级	操作范围	Agent 行为	人的角色	典型操作
L0：完全自主	感知类操作	自主执行，无需报告	无需参与	查询列表、日志检索、状态查看
L1：自主 + 事后报告	低风险执行	自主执行，执行后通知人	事后审阅	标记已读、发送通知、记忆存储
L2：人工确认后执行	高风险执行	Agent 提出方案，人确认后才执行	事前审批	创建/修改策略、注册新资产
L3：最严格审批	极高风险操作	提交多人审批 + 冷静期二次确认	双人审批	批量删除、身份注销

5.1.2 信任层级与 MCP Tool 的绑定

每个 MCP Tool 在注册时必须声明其信任层级：

name: resource.create
trust_level: L2          # 需要人工审批
description: "创建一条新的业务资源"
side_effect: true
risk_description: "新资源将影响系统行为"
input_schema: { ... }
output_schema: { ... }

信任层级 × 工具分级映射示例：

L0（完全自主）：所有感知类、决策类工具（查询列表、详情、分析、状态检查）
L1（自主 + 事后报告）：低风险写入（标记已读、触发检查、更新非关键信息）
L2（人工确认后执行）：高风险写入（创建/修改/删除策略、注册/禁用资产）
L3（最严格审批）：极高风险操作（批量删除）

5.1.3 审批流程

L2 审批：

Agent 大脑判断需要执行 L2 操作
  → 生成操作方案（做什么 + 为什么 + 影响范围）
  → 通过 AG-UI 推送审批卡片到前端
  → 用户审阅方案
  → 同意 → Agent 执行 → 执行结果回报
  → 拒绝 → Agent 记录拒绝原因 → 调整方案或结束

L3 多人审批 + 冷静期：

Agent 大脑判断需要执行 L3 操作
  → 生成操作方案（做什么 + 影响范围 + 不可逆警告）
  → 推送 L3 审批卡片（标注"高危操作"）
  → 发起人确认（第一次确认）
  → 通知管理员确认（第二次确认）
  → 双人确认通过后进入冷静期（可配置）
  → 冷静期结束，推送最终确认
  → 最终确认 → Agent 执行 → 审计记录
  → 任一环节拒绝 → 操作取消，全程审计

设计理念：L3 的保障不靠”禁止”，靠流程摩擦力——双人确认排除个人误操作，冷静期排除冲动决策。闭环在对话内完成。

5.1.4 权限决策完整链路

当 Agent 发起一次工具调用时，请求经过以下五层逐级评估：

Agent 发起工具调用（tool_name + tool_input）
  → Layer 5 企业策略：deny 列表命中 → 直接拒绝（不可覆盖）
  → Layer 4 工具信任层级：L3→拒绝 / L2→进审批 / L1→执行+通知 / L0→执行
  → Layer 3 PreToolUse Hook：任一 deny→拒绝 / ask→升级审批 / allow→继续
  → Layer 2 审计记录：PostToolUse 自动写入观测系统，不可关闭
  → Layer 1 人工确认：L2 操作推送审批卡片 → 同意/拒绝/"总是允许"

5.1.5 权限决策引擎数据结构

组件	职责	数据来源
企业策略缓存	全局禁用工具列表、强制 L2 工具列表、模型白名单	管理员配置
用户信任配置缓存	按 user_id 分片存储用户级信任层级和工具权限	配置系统
工具信任层级映射	工具名 → 信任层级，从 Tool Registry 同步	MCP Tool 注册时声明
用户自定义规则	用户”总是允许”的操作规则	用户通过审批卡片生成

5.1.6 信任层级的动态调整

信任层级不是静态不变的：

向上提权：经过充分验证的固化工作流，可由管理员审批将部分 L2 操作提升为 L1
向下降权：Agent 出现异常行为（行为分析检测到偏离基线）时，自动将 L1 降级为 L2
紧急熔断：管理员可一键将所有 Agent 操作降级为 L3（仅建议模式）

5.2 事件钩子体系

“不改 Agent 内核，在外围拦截和扩展”的 AOP 模式。

5.2.1 事件清单

事件	触发时机	支持的钩子类型	典型用途
SessionStart	对话会话初始化	command	加载规范文件、用户配置、态势快照
SessionEnd	对话会话结束	command	持久化工作记忆、清理临时资源
UserPromptSubmit	用户输入后、Agent 推理前	prompt / command	输入合规检查、上下文增强
PreToolUse	Agent 决定调用工具、执行前	prompt / command	权限决策（核心）、参数校验、输入脱敏
PostToolUse	工具执行完成后	prompt / command	审计记录、结果脱敏、质量验证
PreCompact	上下文压缩前	command	保留关键上下文
Stop	Agent 大脑尝试退出	prompt / command	完成度检查——任务是否充分完成？
SubAgentStop	子 Agent 完成	prompt / command	子 Agent 结论质量检查
TaskCreated	后台任务创建	command	任务拦截和增强
TaskCompleted	后台任务完成	command	清理、通知、后续触发

根据业务领域，可在此基础上新增领域特有事件（如 PolicyChanged / AlertEscalated 等），覆盖关键业务时刻。

5.2.2 钩子执行引擎

事件触发（如 PreToolUse）
    ↓
从注册表中取出该事件的所有 Handler
    ↓
按注册顺序依次执行（非并行）
    ↓
每个 Handler：
    ├─ command 类型 → 直接执行，同步返回
    ├─ prompt 类型 → 发送给 LLM 判断，解析返回决策
    └─ 超时 → 视为 allow（fail-open）
    ↓
汇总结果：
    ├─ 任一 deny → 最终 deny（短路）
    ├─ 任一 ask → 升级为人工确认
    ├─ 全部 allow → 最终 allow
    └─ Hook 返回 modified_input → 传递给下一个 Hook 和实际工具执行

关键设计约束：

约束	说明	理由
顺序执行不并行	前一个的 modified_input 传给后一个	需要确定性
超时 fail-open	钩子超时视为 allow	业务连续性优先
deny 短路	任一钩子 deny 立即停止后续执行	性能优化
PostToolUse 不可 deny	工具已执行完毕，只能记录和告警	工具执行不可逆

钩子执行模式：

模式	执行方式	速度	适用场景
command	执行确定性函数	毫秒级	明确规则（权限匹配、审计记录）
prompt	发送给 LLM 判断	秒级	模糊判断（“这个操作是否合理？”、“调查结论是否充分？“）

5.3 Agent 自身安全威胁模型

Agent 大脑本身是 LLM 驱动的，面临各种威胁。Agent 系统自身的安全是必答题。

威胁	攻击方式	防御机制
Prompt Injection	用户注入指令试图绕过信任层级	① System Prompt Layer 1 硬编码不可覆盖；② 信任层级在引擎层强制执行，不依赖 LLM 遵守指令
工具幻觉	Agent 幻觉不存在的工具名或构造错误参数	① 工具注册表严格校验；② inputSchema 强类型校验；③ PostToolUse Hook 检查返回值
无限循环	Agent 反复调用同一工具或陷入推理死循环	① 最大循环次数限制；② 断路器；③ Stop Hook 检测循环模式；④ 工具调用超时
Agent 提权	多轮对话逐步提升操作权限	① 信任层级在引擎层硬编码，LLM 无法”说服自己”提权；② 提权只能通过管理员显式操作；③ 每次变更触发审计
敏感数据泄露	Agent 在响应中泄露其他用户数据	① 用户级会话隔离；② System Prompt 禁止输出原始记录；③ PostToolUse Hook 做响应脱敏
资源滥用	恶意用户发送极长对话消耗 token	① Compaction 断路器；② 并发会话限制；③ LLM 全局限速
子 Agent 逃逸	子 Agent 尝试调用超出权限的工具	① 工具清单在分派时已限定；② 权限决策引擎按子 Agent ID 校验

安全设计原则：

原则	说明
信任层级引擎层强制	安全约束不依赖 LLM 遵守指令——即使 LLM 被诱导，引擎层仍会拦截
最小权限	每个子 Agent 只能访问其角色所需的最小工具集
全量审计不可关闭	每次工具调用都写入不可篡改的审计日志
异常自动降权	行为分析检测到异常时自动降级信任层级
人是最终防线	L2/L3 操作的审批不可被 Agent 绕过——代码层面的强制

六、能力接入层

6.1 MCP Tool 层（原子工具体系）

6.1.1 定位与职责

MCP Tool 层是 Agent 大脑调用一切能力的统一接口。已有平台各模块的 API 通过原子化包装，暴露为 Agent 可理解、可调用的标准化工具。

核心原则：底层一套 API 实现，上面开两个口——CLI 和 MCP 平行暴露同一个底层实现。

                     ┌─ Skill（编排层）─────────────────┐
                     │  固化的多步工作流（零 token 执行）   │
                     └──────────────┬──────────────────┘
                                    ↑ 组合
┌───────────────────────────────────┼─────────────────────────┐
│                   同一个底层 API 实现                          │
│                                   │                          │
│  ┌─ CLI（命令行接口）──────────┐  │  ┌─ MCP Tool（协议接口）─┐│
│  │  agent resource query      │  │  │  resource.query(args)  ││
│  │  消费者：                   │  │  │  消费者：              ││
│  │  · Agent 通过 bash 执行     │  │  │  · Agent 原生调用      ││
│  │  · 人直接终端使用           │  │  │  · 外部系统互操作      ││
│  └─────────────────────────────┘  │  └────────────────────────┘│
└───────────────────────────────────┴─────────────────────────────┘

6.1.2 工具设计三原则

Tool 描述即契约：每个 MCP Tool 的 description 足够精确，让 Agent 仅凭描述即可判断何时调用——这是给 LLM 看的工具说明书
按副作用分级：感知类无副作用可自主调用；执行类有副作用必须标注风险等级，与信任层级联动
粒度适中：每个工具完成一个语义完整的原子动作——不拆太细（浪费 token），不合太粗（Agent 失去控制力）

6.1.3 五类工具分级

工具类别	副作用	职责	典型工具
感知类	无	获取系统状态与数据	`event.list` · `log.search` · `entity.list` · `config.list`
决策类	无	产出分析结论	`event.detail` · `check.result` · `entity.detail`
执行类	有	改变系统状态	`config.create`(L2) · `entity.create`(L2) · `event.mark`(L1)
记忆类	有（仅写记忆库）	经验存储与检索	`memory.store` · `memory.recall` · `workflow.save`
呈现类	无	组装可视化结果	`chart.render` · `table.render` · `report.generate`

6.1.4 Skill 层——从 Agent 行为中涌现

Skill 不需要预先设计，它是 Agent 行为固化的自然产物：

第 1~100 次：Agent 自主编排工具调用（灵活，消耗 token）
第 101 次：  系统发现历史轨迹高度相似 → 自动提炼为 Skill
第 102 次起：Agent 识别到匹配场景 → 直接调用 Skill（零 token，确定性执行）

6.2 已有平台改造原则

原则	说明
不重写内核，只加接口层	已有模块的业务逻辑已经过验证，不动内核。只在现有 API 外包 MCP Tool 壳（加 description + inputSchema + trust_level）
核心工具优先，不全量包装	数百个 API 不全部包装，按 Agent 使用频率筛选核心工具集
Schema 从现有结构导出	已有数据表结构直接导出为 JSON Schema，不重新设计
已有接口零改造	现有 API 完全保留，传统 UI 继续调用，零影响

6.3 Agent 专属 API 设计

Agent API 不是已有接口的封装，而是面向 Agent 推理需求重新设计的接口层。

已有 API 围绕”人在 UI 上的操作”设计——一个按钮对应一个 API。Agent 的消费模式完全不同：它需要在一个推理步骤内获得完整的决策上下文，而不是像人一样在多个页面间切换拼凑信息。

Agent 引擎（Python）
    ↓ 调用
MCP Tool 层
    ↓ 调用
┌─────────────────────────────────────────┐
│ Agent API 层（/agent/ 命名空间）          │ ← 新增
│ 调用已有 Service 层（不是调已有 API 层）   │
├─────────────────────────────────────────┤
│ 已有 REST API 层（数百个）               │ ← 不动
│ 调用已有 Service 层                      │
├─────────────────────────────────────────┤
│ 已有 Service 层（业务逻辑，共享）         │ ← 不动
├─────────────────────────────────────────┤
│ 数据库                                   │ ← 不动
└─────────────────────────────────────────┘

三种 API 性质：

性质	说明	示例
聚合型	多个原子 API 的结果组合为一个完整上下文	`entity.full-profile`（聚合基础信息+关联关系+状态历史）
增强型	在原子 API 基础上增加 Agent 消费所需的额外信息	`config.effect`（在配置详情基础上增加影响范围分析）
同步化型	将异步任务封装为同步接口	`log.search-sync`（将”创建→轮询→取结果”封装为一次调用）

设计原则：

原则	说明
面向推理步骤设计	一个 Agent API 调用 = Agent 一个推理步骤所需的完整信息
调 Service 层不调 API 层	Agent API 直接调用 Service 层方法，不走已有 API 的 Controller
精简字段	去掉 UI 友好字段（iconKey/colorCode），保留语义字段
含基线对比	返回值自带基线对比数据（同比/环比），减少 Agent 的额外查询

七、支撑系统

7.1 对话引擎 + AG-UI 渲染器

7.1.1 AG-UI 协议

AG-UI 是 Agent 大脑与前端渲染器之间的流式通信协议：

事件类型	方向	说明
`text.delta`	Agent → 前端	流式文本输出（逐 token）
`tool.call.start`	Agent → 前端	Agent 开始调用工具，前端展示加载状态
`tool.call.result`	Agent → 前端	工具调用结果
`render.component`	Agent → 前端	嵌入信息呈现原语（图表/表格/时间线）
`approval.request`	Agent → 前端	请求人工审批（L2 操作）
`user.message`	前端 → Agent	用户输入文本
`user.approval`	前端 → Agent	用户审批结果

7.1.2 信息呈现原语

当对话需要可视化时，Agent 大脑从 Schema 约束的原语中按需选取组件嵌入对话：

原语类型	典型场景	Schema 约束
折线图/柱状图	趋势变化	数据源绑定 + 时间范围 + 聚合粒度
表格	列表展示	列定义 + 排序 + 筛选条件 + 分页
时间线	事件链	事件序列 + 时间戳 + 关联证据
拓扑图	关系图	节点 + 边 + 分组
指标卡片	关键数字	指标名 + 值 + 趋势 + 对比基线
审批卡片	操作确认	操作摘要 + 影响范围 + 同意/拒绝按钮

设计原则：

大部分交互通过纯文字完成——文字是最可靠的
呈现原语是 Schema 约束的，Agent 的”呈现”是在有限选项中组装，不是生成前端代码
组件渲染失败时优雅降级为文字

7.2 制品体系 + Schema Registry

7.2.1 定位

制品体系是”能力自生产”的基础设施——定义 AI 可以生产什么、生产物长什么样、如何验证、如何上线。

核心概念：Schema 就是告诉 AI”你要生成的东西长什么样”的标准格式定义。有了它，AI 的生产行为从”写任意代码”变成”填一份有约束的结构化表单”。

7.2.2 四大 Schema 方向

方向一（MCP Tool 契约）→ Agent 大脑用来"做事"——调什么工具、传什么参数
方向二（业务制品）     → 工厂 Agent 用来"造东西"——生产什么规则、什么策略
方向三（Agent 编排）   → Agent 工厂用来"造 Agent"——定义什么角色、什么工作流
方向四（信息呈现）     → Agent 大脑用来"展示结果"——用什么图表、什么格式

MCP Tool 契约 Schema 示例：

name: "event.list"
description: "分页查询业务事件列表..."
trust_level: "L0"
side_effect: false
category: "感知"
input_schema:
  type: object
  properties:
    pageNum: { type: integer, minimum: 1 }
    pageSize: { type: integer, minimum: 1, maximum: 100 }
    filters: { type: object }
    time_type: { type: string, enum: ["today", "week", "month", "custom"] }
  required: ["pageNum", "pageSize"]
output_schema:
  type: object
  properties:
    total: { type: integer }
    items: { type: array }

Agent 编排 Schema 示例：

kind: AgentDefinition
name: "data-analyst"
role: "analyst"
model_requirement: "strong_reasoning"
tools_allowed: ["event.*", "log.*"]
tools_denied: ["config.*"]
max_trust_level: "L1"
trigger_conditions:
  - event_type: "anomaly"

工作流 DAG Schema 示例：

kind: WorkflowDAG
name: "event-investigate-standard"
trigger: "event.new"
nodes:
  - id: "query_event"
    tool: "event.detail"
  - id: "search_logs"
    tool: "log.search"
    depends_on: ["query_event"]
  - id: "conclude"
    type: "decision"
    branches: { true: "escalate", false: "close" }
fallback: "agent_mode"    # 失败时回退到 Agent 自主模式

7.2.3 制品生命周期

draft → validated → approved → canary → active → deprecated
  ↑        ↑          ↑          ↑        ↑
 生成    Schema    人工审批    灰度验证   全量上线
       自动校验

状态	触发条件	说明
draft	工厂 Agent 生成或人工创建	初始状态
validated	Schema 校验通过	结构合法
approved	人工审批通过	不可跳过
canary	灰度引擎启动新旧对比	新旧制品并行运行
active	灰度达标或管理员手动上线	正式生效
deprecated	新版本替代或管理员下线	保留记录

7.2.4 基础设施组件

组件	职责
Schema Registry	存储四大方向所有 Schema 定义，按方向分 namespace 管理
Artifact Store	制品仓库，带版本管理、来源追溯、状态流转
Validation Pipeline	Schema 校验 → 效果验证 → 历史数据回放 → 生成验证报告
Canary Engine	新旧制品并行运行，效果对比，自动决策上线或回滚

7.3 工厂 Agent 集群

工厂 Agent 让系统从”人工开发能力，等版本发布”变为”AI 自主识别能力缺口，自主生产新能力”。

传统模式：人设计 → 人编码 → 人测试 → 人部署
Agent 模式：AI 感知缺口 → AI 生成制品 → Schema校验 → 人审批 → 热加载生效
                                                      ↑
                                                唯一的人工环节

工厂	生产物	启动前提
规则工厂	业务规则 / 检测策略	热加载能力就绪 + 样本积累
Agent 工厂	子 Agent 定义（角色/工具集/权限/Prompt）	现有角色运营中出现覆盖盲区
工作流工厂	确定性工作流 DAG（经验固化）	Agent 运行积累足够行动轨迹数据

为什么适合 AI 自主工程：制品的解空间是有限的（Schema 约束），生成失败的代价可控（灰度可回滚），验证方式天然闭环——相比 AI 写通用代码，结构化制品的 AI 自主生产更可控。

7.4 持久化层

┌─ 会话级持久化 ──────────────────────────────────────────────┐
│  对话转录（Transcript）                                       │
│  · 格式：JSONL（每条消息一行，追加写入）                        │
│  · 内容：用户消息 + Agent 推理 + 工具调用 + 工具结果            │
│  · 用途：会话恢复、行动轨迹分析                                │
│                                                              │
│  会话状态（Session State）                                     │
│  · 工作记忆快照、活跃子 Agent 状态、待审批队列                  │
│  · 存储：Redis（TTL = 会话超时时间）                           │
│                                                              │
│  子 Agent 任务状态（Task State）                               │
│  · 任务进度、中间结论、行动轨迹                                │
│  · 存储：Redis + 完成后归档到持久存储                          │
└──────────────────────────────────────────────────────────────┘

┌─ 全局级持久化 ──────────────────────────────────────────────┐
│  长期记忆（Memory）                                           │
│  · 用户偏好、历史结论、经验模式                                │
│  · 加载：会话启动时加载索引，按需读取详情                      │
│                                                              │
│  行动轨迹（Action Trace）                                     │
│  · Agent 每次行动的完整记录                                   │
│  · 存储：时序数据库（供工作流工厂分析）                        │
│                                                              │
│  审计日志（Audit Log）                                        │
│  · 所有 L1/L2/L3 操作的不可篡改记录                           │
│  · 存储：追加写入，不可删除                                    │
└──────────────────────────────────────────────────────────────┘

会话恢复机制：

正常对话中
    ├─ 网络中断 → 会话状态已持久化 → 用户重新打开 → 自动恢复到中断点
    ├─ LLM 不可用 → 回退到传统 UI 模式 → 恢复后自动续接
    └─ 上下文溢出 → 保存状态 → 新会话自动加载长期记忆

7.5 观测系统

观测三支柱：

支柱	内容
Traces	Agent 每次推理→工具调用→子 Agent 调度的完整调用链
Metrics	Token 消耗、工具调用次数/延迟、Skill 命中率
Logs	权限决策记录、审批记录、异常事件、钩子执行结果

Agent 追踪数据模型：

{
  "trace_id": "uuid",
  "session_id": "uuid",
  "agent_id": "brain",
  "span_type": "tool_call | sub_agent_dispatch | llm_inference | approval_wait",
  "tool_name": "event.list",
  "trust_level": "L0",
  "permission_decision": "allow",
  "hook_results": [
    {"hook": "PreToolUse", "result": "allow", "latency_ms": 3}
  ],
  "input_tokens": 1200,
  "output_tokens": 350,
  "latency_ms": 2100,
  "timestamp": "2026-04-03T10:30:00Z"
}

7.6 配置系统

┌─ 企业级（最高优先级，不可被用户覆盖）───────────────────────┐
│  · 全局禁用的工具列表                                      │
│  · 强制审批的操作列表                                      │
│  · 允许的 LLM 模型白名单                                   │
│  · Agent 最大自主操作次数限制                               │
│  · 默认信任层级                                            │
│  · 规范文件                                                │
│  · 是否启用主动巡检模式                                    │
├──────────────────────────────────────────────────────────┤
│  ↓ 用户可在企业策略允许范围内覆盖                           │
├─ 用户级 ──────────────────────────────────────────────────┤
│  · 用户个人偏好（交互模式、通知频率、关注范围）              │
│  · 用户交互风格（简洁/详细）                                │
│  · 用户"总是允许"的操作规则                                 │
└──────────────────────────────────────────────────────────┘

配置合并规则：

读取配置值（key）：
  1. 检查企业级配置 → 如果是 deny/强制项 → 直接返回（不可覆盖）
  2. 检查用户级配置 → 如果有值 → 返回
  3. 返回系统默认值

八、新旧架构共存设计

Agent 系统上线后，传统 UI 不会立即下线。需要一个过渡期，新旧两套交互方式并存，用户可自由切换。

8.1 共存架构

┌─ 前端 ───────────────────────────────────────────┐
│  ┌─ 传统 UI ───────────┐  ┌─ 对话界面 ─────────┐ │
│  │  菜单 + 表单 + 分页   │  │  对话引擎 + AG-UI   │ │
│  └────────┬──────────────┘  └────────┬──────────┘ │
│           │     模式开关               │            │
└───────────┼──────────────────────────┼─────────────┘
            │                          │
            ▼                          ▼
┌─ API 层 ──────────────────────────────────────────┐
│  ┌─ 已有 REST API ────┐  ┌─ Agent API 层 ───────┐ │
│  │  数百个原子接口      │  │  /agent/ 聚合接口     │ │
│  │  面向 UI 消费       │  │  + 已有接口直调       │ │
│  └────────┬────────────┘  └────────┬─────────────┘ │
│           └───────────┬───────────┘                 │
│                       ▼                             │
│           同一个 Service 层（业务逻辑共享）            │
└───────────────────────────────────────────────────┘

关键架构约束：两种模式共享同一个 Service 层和数据库。传统 UI 调已有 API，Agent 调 /agent/ 聚合 API + 已有原子 API。数据完全一致。

8.2 模式切换机制

维度	说明
切换粒度	按用户级别
默认模式	过渡期默认传统 UI
数据一致性	共享 Service 层，零延迟一致
回退保障	对话模式异常时，用户可随时切回传统 UI——Agent 引擎是独立微服务，崩溃不影响已有平台

8.3 过渡期计划

阶段	传统 UI	Agent 对话
并存期	默认开启	可选开启（Beta）
切换期	可选保留	默认开启
迁移完成	仅保留核心管理页面	唯一入口

性能不退化原则：Agent 模式与传统 UI 模式完成同一操作的端到端时长对比，是决定切换节奏的关键指标。

降级策略：Agent 引擎是独立微服务。Agent 引擎崩溃 = 对话模式不可用，但传统 UI + 全部已有 API 继续正常工作。

九、Agent 测试体系设计

传统平台测试是确定性的——调 API、传固定参数、断言返回值。Agent 系统将确定性操作变成了”自然语言 → Agent 理解 → 工具选择 → 参数构造”，每一步都引入了概率性。没有系统化的测试体系，Agent 的质量无法量化。

9.1 Agent 测试与传统测试的本质差异

维度	传统 API 测试	Agent 测试
输入	固定 API Path + 固定参数	自然语言（同一意图有 N 种表达）
确定性	100%——同输入同输出	概率性——LLM 推理可能选不同工具
正确性定义	返回值 = 期望值	意图识别正确 + 工具选择正确 + 参数构造合理 + 信任层级正确
回归风险	代码变更导致	System Prompt 变更、模型升级、上下文变化都可能导致
覆盖率衡量	API 覆盖率 / 分支覆盖率	意图覆盖率——多少种用户意图被正确理解和执行

9.2 三层测试模型

┌─────────────────────────────────────────────────────┐
│ 第三层：端到端场景测试                                  │
│ "把这个新实体做完检查再接入"                             │
│ → 验证多步任务拆解、步骤顺序、审批流、最终结果             │
├─────────────────────────────────────────────────────┤
│ 第二层：工具选择 + 参数构造测试                          │
│ "查一下昨天的高优先级事件"                               │
│ → 验证选对工具 + 时间参数正确 + 筛选条件正确              │
├─────────────────────────────────────────────────────┤
│ 第一层：意图识别测试                                    │
│ "帮我看看最近的事件"                                    │
│ → 验证识别为正确的事件类型查询                            │
└─────────────────────────────────────────────────────┘

第一层：意图识别准确率

测试维度	说明
正向识别	标准表达 → 正确意图
同义变体	同一意图的不同表达方式均能识别
模糊消歧	模糊表达能正确追问或合理默认
误识别防御	不应被错误识别的表达
复合意图拆解	多意图表达能正确拆解

第二层：工具选择 + 参数构造正确性

测试维度	说明
工具选择	意图 → 正确的 MCP Tool
参数提取	自然语言中的条件正确提取为参数
参数默认	未指定的参数使用合理默认值
信任层级	操作的信任层级判定正确
子 Agent 分派	复杂意图正确分派给对应子 Agent

第三层：端到端场景测试

测试维度	说明
任务拆解	复杂意图正确拆解为多步计划
步骤顺序	有依赖关系的步骤按正确顺序执行
审批流	L2 操作正确触发审批
异常恢复	某步骤失败时的处理
上下文保持	多轮对话中上下文不丢失

9.3 评估指标

指标	定义	目标值
意图识别准确率	正确识别的意图数 / 总意图数	待建立基线
工具选择准确率	选对工具的次数 / 总调用次数	待建立基线
信任层级判定准确率	信任层级判定正确的次数 / 总调用次数	100%（底线——不允许将 L2 操作误判为 L0）
变体一致性	同一意图 N 种表达的识别一致率	待建立基线
回归通过率	基线集通过用例数 / 总数	≥ 95%

9.4 测试与开发的闭环

每次 System Prompt / 模型变更 → 运行回归基线集 → 通过率达标则允许发布；不达标则定位失败用例（意图退化→调 Prompt / 工具偏移→调 description / 参数错误→调 Schema / 信任层级误判→紧急修复）→ 修复后重跑回归集。

9.5 模型评测框架

评测维度	评测方法	用途
意图识别准确率	基础意图集 → 各模型识别正确率对比	选择 Agent 大脑模型
工具选择准确率	给定意图 → 各模型选择正确工具的比率	选择 Agent 大脑模型
结构化输出遵循率	要求输出 JSON → 各模型格式合规率	选择工厂 Agent 模型
推理延迟	相同 Prompt → 各模型首 token 延迟和完整响应延迟	权衡速度与质量
长上下文保持能力	上下文逐步增大 → 各模型准确率退化曲线	评估上下文管理策略
约束遵循率	Prompt Injection 测试集 → 各模型拒绝违规指令的比率	选择可信赖的模型

十、实施路线

10.1 Agent 引擎分阶段实施

阶段	交付物	完成标志
阶段零：Mock API Server	核心接口 Mock 就绪	Agent 引擎所有 MCP Tool 调用均可获得合法响应
阶段一：Agent 循环引擎骨架	状态机完整闭环	真实 Mock API 调用，完整循环可运转
阶段二：信任层级权限引擎	L0/L2 硬约束生效	L2 工具被引擎层拦截推审批，L0 无感通过
阶段三：事件钩子体系	核心三钩子接入	PreToolUse/PostToolUse/Stop 触发，审计记录落库
阶段四：1+N 子 Agent 调度	任务分派协议跑通	顶层 Agent 可分派任务，结论回传组装响应
阶段五：System Prompt 五层组装	动态 Prompt 替换	按用户动态注入 Layer 2，工具按需分档加载
阶段六：意图测试与调优	核心场景可演示	信任层级判定 100% 准确，端到端场景可完整演示

10.2 交付依赖关系

阶段一                阶段二                阶段三                阶段四
──────────────────────────────────────────────────────────────────────
MCP Tool 层 ──────→ Agent 引擎 ──────→ 子 Agent ──────→ 端到端验证
Schema Registry ──→ 信任层级框架 ──→ 审批流联调
                    对话引擎 ──────→ 前端联调 ──────→ 新旧共存
已有模块改造 + Agent 专属 API ──────────────────→ 集成测试
持久化 + 观测 + 配置 ──────────────────────────→ 运维验证
意图测试集 ──────────────────────────────────→ 回归门控

10.3 后续演进方向

方向	内容	启动前提
工作流工厂启动	历史轨迹 → 高频场景提炼为 DAG → Skill 执行，零 token	Agent 运行积累足够行动轨迹数据
规则工厂启动	AI 自动生成业务规则，响应周期从人工数天缩短到分钟级	热加载能力就绪 + 样本积累
Agent 工厂启动	现有角色覆盖盲区时自动生成新角色定义	运营期发现真实新角色需求
子 Agent 能力深化	自动效果分析、趋势预测、多渠道协作	基础版运营稳定后
信任层级动态化	基于行为分析自动提权/降权 + 紧急熔断	行为分析双用途完成
主动巡检模式	Agent 后台持续监控，主动推送风险	Agent 大脑能力成熟后

总结

这篇文章的十个核心架构模式

Agent 循环引擎状态机：IDLE→REASONING→PERMISSION→EXEC→RESULT→STOP_CHECK 六态循环，信任层级内建到每一步
信任层级四级模型 L0-L3：从完全自主到多人审批，引擎层强制执行，不依赖 LLM 遵守指令
事件钩子体系：AOP 模式拦截 Agent 生命周期，10+ 个事件点，支持 command 和 prompt 两种模式
1+N 子 Agent 协作：Manager + 专项角色的分派/调度协议，基于能力模块反推角色，上下文隔离
System Prompt 五层架构：核心身份→规范→工具→上下文→记忆的动态组装
上下文管理五机制：规范文件 / ToolSearch / Compaction / Prompt Cache / 大输出外溢
制品体系 + Schema Registry：Schema 约束的有限解空间，四大方向覆盖工具/业务/编排/呈现
框架选型方法论：不选框架本身，而是从各框架提炼设计精华，自研引擎整合
新旧架构共存：传统 UI 与 Agent 模式共享 Service 层，Agent 崩溃不影响已有平台
Agent 测试体系：三层测试模型（意图→工具→端到端），信任层级判定 100% 是底线

关键设计原则

Agent 不是平台上面的壳，Agent 就是平台本身——已有模块是”器官”，Agent 是”大脑”
信任层级是引擎原生的，不是插件——这决定了为什么通用框架不能直接用
Prompt 引导”应该做什么”，引擎强制”不能做什么”——两层互补
人负责决策，AI 负责分析和执行——L2/L3 审批是代码层面的强制，不是请求
不设计用户旅程——用户有意图，Agent 理解并执行，中间不需要”旅程”
Schema 约束的有限解空间——AI 的”生成”不是写任意代码，而是在约束下组装结构化制品

本文基于真实项目实践整理，已脱敏处理。架构设计由架构师与 AI 协作完成——架构师主导方向判断和技术决策，AI 负责设计推演、文档生成和一致性检查。