agent 架构设计智能客服、智能医疗问诊与 rag-agent 整合架构设计依据文档：智能客服：Intellige

智能客服、智能医疗问诊与 rag-agent 整合架构设计

1. 整合目标与原则

1.1 目标

rag-agent 为基座：在现有 rag-agent（Node + Python + React）上扩展，不另起新仓；RAG 为基座能力，客服、医疗为扩展 Agent。
多 Agent 并存：RAG 文档问答、智能客服、智能医疗问诊 同平台、入口分离（API + MCP）、流水线独立。
多 MCP 口子：前端层设计 多个 Agent 入口，以 多个 MCP 暴露（RAG MCP、客服 MCP、医疗 MCP），便于 IDE / 工作流 / 其他 AI 按需调用。
共享基础设施：Embedding、Redis、配置、日志、Node 认证与路由复用；知识库与推理链按子域隔离。

1.2 原则

基座 + 扩展：核心能力与扩展 Agent 分层；新增 Agent 以可插拔方式接入，通过配置与路由注册。
入口区分：API 路径 + MCP 工具 双通道；前端/客户端可走 REST 或 MCP 调用各 Agent。
数据隔离：RAG → Qdrant 用户文档；客服 → 客服知识库；医疗 → ChromaDB 医学三库。
可独立演进：各 Agent 子域可单独迭代、扩缩容、替换组件，互不影响；新增 Agent 时不动基座核心。

2. 三类 Agent 对比（入口与流水线）

维度	RAG 文档问答	智能客服	智能医疗问诊
入口	单轮 `ask`	多轮 `chat`（session）	单次 `consult`（症状+图）
交互形态	问题 → 答案+来源	多轮消息 → 回复/澄清	症状+可选图 → 结构化报告
核心流水线	embed → Qdrant → LLM → 回答	预处理 → 意图‖实体 → 对话管理 → KB → 响应	图像分析 → 症状解析 → 知识检索 → 诊断 → 报告
知识库	Qdrant `user_{id}`	客服 KB（FAISS / Qdrant）	ChromaDB 症状/疾病/治疗
输出	`answer` + `sources`	文本回复 or 澄清	结构化报告
多模态	否	否	是

3. 整体架构图（基座 + 扩展 + 多 MCP）

3.1 逻辑分层总览

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                            前端层 · 多 Agent 口子（多 MCP）                               │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐      … 可扩展        │
│  │  RAG Agent MCP  │    │ 客服 Agent MCP  │    │ 医疗 Agent MCP  │                      │
│  │  Manifest       │    │ Manifest        │    │ Manifest        │                      │
│  └────────┬────────┘    └────────┬────────┘    └────────┬────────┘                      │
│           └──────────────────────┼──────────────────────┘                               │
│                                  ▼                                                      │
└──────────────────────────────────┼──────────────────────────────────────────────────────┘
                                   │
┌──────────────────────────────────┼──────────────────────────────────────────────────────┐
│              Node.js · BFF + Policy Gateway（认证、鉴权、限流、MCP token→user）           │
│        /api/v1/rag/*  │  /api/v1/customer-service/*  │  /api/v1/medical/*               │
└──────────────────────────────────┼──────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                    Agent Runtime / Orchestrator（统一调度与约束）                         │
│  注册表 · 能力声明 · Prompt/Policy 管控 · Tool 调度 · Memory 策略 · 安全/合规 Hook       │
└─────────────────────────────────────────────────────────────────────────────────────────┘
                                   │
            ┌──────────────────────┼──────────────────────┐
            ▼                      ▼                      ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│ RAG（基座）     │      │ 智能客服（扩展） │      │ 医疗问诊（扩展） │
│ RAGService      │      │ 意图/实体/对话   │      │ Coordinator     │
│ Qdrant · LLM    │      │ 客服 KB · LLM   │      │ 合规层·ChromaDB·ERNIE │
└────────┬────────┘      └────────┬────────┘      └────────┬────────┘
         │                        │                        │
         └────────────────────────┼────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│  共用：EmbeddingService · config · logger · Observability（Trace）                       │
└─────────────────────────────────────────────────────────────────────────────────────────┘
            │                        │                        │
            ▼                        ▼                        ▼
     ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
     │ Qdrant      │          │ 客服 KB     │          │ ChromaDB    │
     │ Redis       │          │ Redis       │          │ FastDeploy  │
     │ OpenAI      │          │ OpenAI      │          │ Embedding   │
     └─────────────┘          └─────────────┘          └─────────────┘

约定：MCP 与 REST 仅调用 Agent Runtime，不直连各 Agent 内部；Runtime 负责注册、调度、Policy、Tool 路由与合规 Hook。

3.2 多 MCP 口子与 Agent 映射

                    ┌───────────────────────────────────────────┐
                    │           多 MCP 口子（前端层）            │
                    └───────────────────────────────────────────┘
                                         │
         ┌───────────────────────────────┼───────────────────────────────┐
         │                               │                               │
         ▼                               ▼                               ▼
┌─────────────────┐             ┌─────────────────┐             ┌─────────────────┐
│  RAG Agent MCP  │             │ 客服 Agent MCP  │             │ 医疗 Agent MCP  │
├─────────────────┤             ├─────────────────┤             ├─────────────────┤
│ tools:          │             │ tools:          │             │ tools:          │
│ · rag_ask       │             │ · cs_chat       │             │ · medical_consult│
│ · rag_upload    │             │ · cs_session    │             │                 │
│ · rag_status    │             │                 │             │                 │
└────────┬────────┘             └────────┬────────┘             └────────┬────────┘
         │                               │                               │
         └───────────────────────────────┼───────────────────────────────┘
                                         │
                         ┌───────────────┴───────────────┐
                         │  MCP ↔ 后端 适配层            │
                         │  请求发往 Runtime（经 Node    │
                         │  或直连 Python），不直连 Agent│
                         └───────────────┬───────────────┘
                                         │
         ┌───────────────────────────────┼───────────────────────────────┐
         ▼                               ▼                               ▼
    /rag/ask                    /customer-service/chat            /medical/consult
         └───────────────────────────────┼───────────────────────────────┘
                                         ▼
                              Agent Runtime → 分派至对应 Agent

要点：每个 Agent 对应一个 MCP 口子；MCP 内暴露 tools，经 Manifest 声明能力；MCP & REST 只调用 Runtime，由 Runtime 调度到具体 Agent。

4. Agent Runtime / Orchestrator 设计

4.1 定位与价值

统一调度与约束：所有 Agent 经 Runtime 注册、暴露、被调用；避免各 Agent 各自为政、行为不一致。
多 Agent 协作：后续 Agent-to-Agent、编排、组合能力可基于 Runtime 的注册表 + Tool 路由实现，而非硬编码。
治理与边界：Prompt / Policy / Memory / 安全合规 Hook 收口在 Runtime，便于管控与审计。

4.2 逻辑架构

┌─────────────────────────────────────────────────────────────────────────┐
│                     Agent Runtime / Core                                 │
├─────────────────────────────────────────────────────────────────────────┤
│  · Agent 注册表（id, capabilities, tools, constraints）                  │
│  · 能力声明（Capabilities）· 与 MCP Manifest 对齐                        │
│  · Prompt / Policy 管控（按 Agent 或全局）                               │
│  · Tool 调度（tool → Agent 路由）                                        │
│  · Memory 策略（会话 / 跨轮 / 跨 Agent）                                 │
│  · 安全 / 合规 Hook（Pre-Check、Safety Filter、Output Formatter）        │
└─────────────────────────────────────────────────────────────────────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
                  RAG          客服           医疗

4.3 工程落点（目录与模块）

app/core/agent_runtime/
  ├── registry.py        # Agent 注册表
  ├── agent_base.py      # BaseAgent，所有 Agent 继承并注册 capabilities / tools / constraints
  ├── tool_router.py     # Tool → Agent 路由
  ├── policies/          # Prompt、Policy 配置与执行
  ├── memory/            # 会话 / 跨轮 / 跨 Agent 记忆策略
  └── hooks/             # 安全、合规 Hook（如医疗 Pre-Check、Output Formatter）

所有 Agent：继承 BaseAgent，注册 capabilities、tools、constraints。
MCP & REST：请求先进 Runtime；Runtime 做路由、Policy、Hook 后再派发到具体 Agent 实现。

4.4 与 MCP、Node 的关系

MCP：暴露 tools；Manifest 来自 Runtime 的 Agent 能力声明；调用时走 Runtime，不直连 Agent。
Node：BFF + Policy Gateway；鉴权、限流、用户画像 等在此；向后调 Python 时，可统一进 Runtime 再分派，或按路由直接进 Runtime 入口。

5. rag-agent 基座与扩展性设计

5.1 基座与扩展分层

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│  扩展层（可插拔 Agent）                                                                   │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
│  │ 智能客服        │  │ 医疗问诊        │  │ 未来 Agent 3    │  │ …               │   │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        │ 注册 / 配置 / 路由
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│  基座（rag-agent 既有）                                                                   │
│  · Node API（认证、会话、文档/对话元数据）                                                │
│  · Python RAG（embed、Qdrant、LLM、process-document、ask）                                │
│  · React 文档管理 + RAG 对话                                                             │
│  · 共用：EmbeddingService、Redis、Config、Logger                                         │
└─────────────────────────────────────────────────────────────────────────────────────────┘

基座：保持 rag-agent 现有职责与边界，不侵入改动。
扩展：新 Agent 以子域（API 路由 + 服务模块 + 可选 MCP）形式挂载；通过配置与 路由表 注册，便于启用/停用与迭代。

5.2 扩展性机制（如何加新 Agent）

机制	说明
Runtime 注册	新 Agent 继承 `BaseAgent`，在 registry 登记 `capabilities`、`tools`、`constraints`；MCP Manifest 与 Runtime 同步。
路由注册	新增 `app/api/v1/{agent}/`，在 `main.py` 中 `include_router`；Node 增加对应转发。
配置驱动	`AGENTS_ENABLED = ["rag","customer_service","medical"]` 等；未启用则不挂路由、不注册 MCP。
MCP 注册	每个 Agent 对应一个 MCP 定义（tools + Manifest）；统一 MCP 网关或独立 MCP 进程按配置加载。
知识库隔离	新 Agent 自带 KB（独立集合/库），与 RAG、客服、医疗隔离；建议带 KB Meta（§9.3）。
目录约定	`app/api/v1/{agent}.py`、`app/services/{agent}/`、`app/kb/{agent}/` 等，便于批量发现与文档生成。

6. 多 MCP 设计（多个 Agent 口子）

6.1 定位

前端层提供 多个 Agent 口子，以 多 MCP 形式暴露；每个 Agent 一个 MCP，对应一组 tools。
使用方（React、Gradio、IDE、n8n、其他 AI 等）可按需连接一个或多个 MCP，调用对应 Agent，无需混用同一接口。

6.2 MCP 与 Agent 对应

MCP	对应 Agent	典型 tools	说明
RAG Agent MCP	RAG 文档问答	`rag_ask`, `rag_upload`, `rag_status`	文档上传、问答、任务状态
客服 Agent MCP	智能客服	`cs_chat`, `cs_session`	多轮对话、会话状态
医疗 Agent MCP	智能医疗问诊	`medical_consult`	症状+图像问诊，结构化报告

6.3 MCP 与后端对接

各 MCP 的 tool 实现 内部分别调用现有 Node / Python API（如 POST /api/v1/rag/ask、POST /api/v1/customer-service/chat、POST /api/v1/medical/consult）。
MCP 层可部署为：
- 独立 MCP Server（按 Agent 拆多个 server），或
- 统一 MCP Gateway：一个 server 暴露多组 tools，按 prefix 或 tool 名路由到对应 Agent 后端。

6.4 前端与 MCP 的关系

React：可集成 MCP 客户端，连接 RAG / 客服 / 医疗 等 MCP，在文档页、客服页、医疗页调用对应 tools。
Gradio：医疗页可直连 医疗 Agent MCP 或 REST；若统一走 MCP，则与 React 一致。
新增 Agent：新增 MCP + tools，前端增加对应入口即可，不改已有 MCP。

6.5 MCP Capability Manifest（能力清单）

MCP 不止 tool → API 的薄封装，建议增加 Agent Capability Manifest，与 Runtime 能力声明对齐。
作用：IDE / 工作流 / Auto-Agent 可 发现 Agent 能力，做自动编排、多 Agent 协作；后续 Agent Marketplace、SaaS API 文档可自动生成。

示例（医疗 Agent）：

{
  "agent": "medical",
  "version": "1.0",
  "capabilities": ["symptom_analysis", "risk_assessment", "medical_report"],
  "input_schema": { "text_input": "string", "image_b64": "string|null" },
  "output_schema": { "symptoms": "string[]", "risk_assessment": "object", "treatment_plan": "object" },
  "constraints": {
    "medical_disclaimer": true,
    "no_diagnosis": true,
    "no_dosage": true
  }
}

各 MCP 提供 manifest 端点 或资源，供发现与校验；Manifest 由 Runtime 注册表 生成或同步。

7. 统一路由与入口（API + MCP）

7.1 API 路由规划

路径	方法	子域	说明
`/api/v1/rag/process-document`	POST	RAG	文档处理（基座）
`/api/v1/rag/ask`	POST	RAG	RAG 问答（基座）
`/api/v1/rag/status/:id`	GET	RAG	任务状态（基座）
`/api/v1/customer-service/chat`	POST	智能客服	多轮对话
`/api/v1/customer-service/session/:id`	GET	智能客服	会话状态（可选）
`/api/v1/medical/consult`	POST	医疗问诊	单次问诊

7.2 入口与请求体摘要

入口	请求体（要点）	输出
RAG ask	`question`, `user_id`, `conversation_id`, `conversation_history?`	`{ answer, sources }`
客服 chat	`session_id`, `user_input`	`{ response }` 或 `{ response, missing_slots? }`
医疗 consult	`text_input`, `image_b64?`, `user_id?`	`{ symptoms, risk_assessment, treatment_plan, ... }`

7.3 MCP tools 与 API 映射

MCP tool	等价 API	说明
`rag_ask`	`POST /api/v1/rag/ask`	RAG 问答
`rag_upload`	`POST /api/v1/rag/process-document`	文档处理
`rag_status`	`GET /api/v1/rag/status/:id`	任务状态
`cs_chat`	`POST /api/v1/customer-service/chat`	客服单轮
`cs_session`	`GET /api/v1/customer-service/session/:id`	客服会话
`medical_consult`	`POST /api/v1/medical/consult`	医疗问诊

8. 各子域流水线概览

8.1 RAG 子域（基座）

用户问题 → rag_ask / /rag/ask → RAGService.ask
    → embed(query) → Qdrant(user_{id}) → LLM → answer + sources

8.2 智能客服子域（扩展）

user_input → cs_chat / /customer-service/chat → 预处理
    → [ 意图识别 ‖ 实体抽取 ] → DialogManager
    → 槽位齐 ? KB 检索 → 响应 : 澄清话术 → response

8.3 医疗问诊子域（扩展）

症状+图像 → medical_consult / /medical/consult → AgentCoordinator
    → 图像分析(可选) → 症状解析 → 知识检索(ChromaDB) → 诊断 → 报告

8.4 医疗 Agent 合规与责任隔离层

医疗 Agent 须 显式加入合规与责任隔离，不依赖 Prompt 约定，而是 Policy as Code。

建议结构：

MedicalAgent
  ├─ Pre-Check（scope / disclaimer 校验）
  ├─ Reasoning（内部推理，可隐藏）
  ├─ Safety Filter（过滤禁止输出：用药剂量、明确诊断结论等）
  └─ Output Formatter（非诊断声明、建议就医、遵医嘱等强制字段）

策略示例：
- 强制输出：风险等级、建议就医条件、非诊断免责声明。
- 禁止：用药剂量、明确诊断结论。
实现：在 services/medical/ 下增加 compliance/（如 pre_check.py、safety_filter.py、output_formatter.py），由 Coordinator 或 Runtime Hook 调用；Strategy 可配置化。

9. 共享与隔离

9.1 共享组件

组件	用途
EmbeddingService	RAG / 客服 query / 医疗检索向量化
Redis	缓存、客服会话等
Config / Logger	统一配置与日志
Node	认证、路由、文档/对话元数据
FastAPI app	挂载 rag、customer-service、medical 路由

9.2 按子域隔离

子域	知识库	推理/模型
RAG	Qdrant `user_{id}`	OpenAI LLM
智能客服	客服 KB（FAISS / Qdrant）	意图/实体模型 + LLM
医疗问诊	ChromaDB 医学三库	ErnieClient (FastDeploy)

9.3 知识库 Meta Layer（分级 + 标签化）

知识库不仅 按子域隔离，建议增加 KB Meta Layer，支持 分级 + 标签化，便于 Policy 与合规控制。

建议元数据：

字段	说明	示例
`domain`	所属域	`medical` \| `cs` \| `rag`
`level`	可见/使用级别	`public` \| `internal` \| `restricted`
`source`	来源类型	`guideline` \| `faq` \| `user_upload`
`validity`	有效期	`ttl` / `review_date`
`risk_tag`	风险标签	`high_risk` \| `normal`

用途：医疗 Agent 优先 guideline、禁止 high_risk 直接输出；客服可按业务线切换 KB；RAG 可按 level 做权限过滤。

10. 部署与模块落点（rag-agent 基座）

10.1 服务部署视图

                    ┌─────────────────────────────────────────────────┐
                    │              API Gateway / Nginx                 │
                    └─────────────────────────┬───────────────────────┘
                                              │
              ┌───────────────────────────────┼───────────────────────────────┐
              ▼                               ▼                               ▼
    ┌─────────────────┐            ┌─────────────────┐            ┌─────────────────┐
    │ Node · BFF +    │            │ Python 服务     │            │ MCP 层           │
    │ Policy Gateway  │ ──HTTP──►  │ Runtime +       │ ◄── 适配 ── │ 多 MCP 口子     │
    │ 认证/鉴权/限流   │            │ RAG+客服+医疗   │            │ + Manifest      │
    └─────────────────┘            └────────┬────────┘            └────────┬────────┘
              │                             │                             │
              │  MySQL / Redis              │  Qdrant, ChromaDB,          │  前端 / IDE /
              │  文档/对话/用户              │  FAISS, Redis, LLM,         │  工作流 等
              │  画像/权限                   │  Observability              │
              ▼                             ▼                             ▼
    ┌─────────────────┐            ┌─────────────────┐            ┌─────────────────┐
    │ 业务数据        │            │ 向量/模型/缓存   │            │ MCP 客户端      │
    └─────────────────┘            └─────────────────┘            └─────────────────┘

10.2 Python 子域与目录映射（基座 + 扩展）

子域	路由	服务/知识库
RAG（基座）	`app/api/v1/rag.py`	`rag_service`, `vector_store`(Qdrant)
智能客服（扩展）	`app/api/v1/customer_service.py`	`services/customer_service/`，`kb/cs/` 或 FAISS
医疗问诊（扩展）	`app/api/v1/medical.py`	`services/medical/`，`kb/medical/`(ChromaDB)

均挂载到 同一 FastAPI app；扩展 Agent 按配置注册。

10.3 Node 层：BFF + Policy Gateway

Node 不止转发，明确为 BFF（Backend For Frontend）+ Policy Gateway。
建议能力：
- 用户画像：普通用户 / 医生 / 客服等；按角色决定可调用的 Agent 与接口。
- Agent 调用权限：按路由或 MCP tool 校验是否有权调用对应 Agent。
- 调用频率限制：按 user / token / IP 限流，防滥用。
- MCP token → user 映射：MCP 请求经 Node 时，将 token 解析为 user，再传 Python / Runtime。
实现：在现有认证、路由之上增加 Policy 中间件（权限、限流、画像）；新增 /customer-service/*、/medical/* 转发；基座 /rag/* 保持现状。

11. 前端层：多 Agent 口子与多 MCP

11.1 口子与 MCP 对应

前端入口	对接方式	说明
文档管理 / RAG 对话	RAG Agent MCP 或 `/rag/*`	基座
智能客服对话	客服 Agent MCP 或 `/customer-service/*`	扩展
医疗问诊	医疗 Agent MCP 或 `/medical/*`，Gradio 可直连	扩展

各入口可二选一：走 MCP（如 IDE、工作流）或走 REST（如 React、Gradio）。
多个 Agent 口子 = 多个 MCP；新增 Agent 时新增 MCP，前端增加对应口子即可。

11.2 扩展新 Agent 时前端侧

新增 MCP（或在一体化 MCP Gateway 中新增 tools）。
前端新增 路由/页 或入口，连接该 MCP 或对应 REST。
无需改动既有 RAG / 客服 / 医疗的 MCP 或页面。

12. 数据流小结

子域	典型输入	主输出	知识检索
RAG	`question`	`answer` + `sources`	Qdrant 用户文档
智能客服	`session_id`, `user_input`	文本回复 or 澄清	客服知识库
医疗问诊	`text_input`, `image_b64?`	结构化报告	ChromaDB 医学三库

13. 实施顺序建议

Phase 0：巩固 rag-agent 基座；按 03 方案完成 医疗扩展，打通 RAG + 医疗。
Phase 1：实现 智能客服 子域与 /customer-service/*；Node 转发；客服 Agent MCP 与 cs_chat / cs_session。
Phase 2：多 MCP 口子 落地：RAG / 客服 / 医疗各 MCP 就绪；Agent Runtime、MCP Manifest 就绪；前端可对接 MCP 或 REST。
Phase 3：治理与平台化：Observability（Trace）、安全 / 合规 / Policy、Node BFF + Policy Gateway；医疗合规层、KB Meta；按需客服转人工、扩展 Checklist 落地。
Phase 4（v3.1）：规模化治理：Agent 调度与依赖治理（§16）、Prompt/Policy/Tool 版本治理（§17）、成本与预算（§18）、Trust Level（§19）、Memory 生命周期与隔离（§20）、Human-in-the-loop（§21）、Agent 生命周期（§22）；满足规模化 / 商业化 / 长周期演进。

14. Agent 可观测性（Observability）

客服误答、医疗风险、RAG 幻觉等 必须可复盘；缺少观测则无法定位与改进。

建议：Agent Call Trace

字段	说明
`trace_id`	调用链唯一标识
`input_hash`	输入哈希（脱敏后可追溯）
`agent`	调用的 Agent
`prompt_version`	当前 Prompt 版本（§17）
`policy_version`	当前 Policy 版本（§17）
`tools_used`	使用的 tools / 子步骤（含版本，如 `kb_search@2.1`）
`invocation_chain`	Agent 调用链（§16，编排时）
`latency_ms`	端到端与分段耗时
`kb_hit_rate`	知识库命中情况（可选）
`safety_trigger`	是否触发安全/合规过滤
`tokens_used` / `estimated_cost`	成本与预算（§18，可选）
`recommended_action`	HITL：auto \| review \| human（§21，可选）

落点：Runtime 或各 Agent 入口打点；输出到日志 / 监控（如 OpenTelemetry、自建 trace 表）。
使用：排障、合规审计、效果评估、模型与 KB 迭代。

15. 安全、合规与 Policy 设计

安全：认证、鉴权、限流（Node BFF + Policy Gateway）；MCP token → user 映射；敏感数据脱敏。
合规：医疗 合规与责任隔离层（§8.4）；禁止输出（用药剂量、明确诊断）与 强制输出（免责、建议就医）以 Policy 代码 实现，而非仅靠 Prompt。
Policy 管控：集中在 Agent Runtime；按 Agent 或全局配置 Prompt / 输出约束 / 审批流程；与 Observability 联动，便于审计。

16. Agent 调度与依赖治理规范（必须级）

目标：防止 Agent 规模化后出现调用失控、循环依赖、成本爆炸。
Agent 规模 >3 后的生死线：若不明确「谁可调谁、怎么调」，易出现隐式链路、循环依赖、成本与延迟失控。

16.1 设计原则（必须写清）

Agent 不得直接调用 Agent
所有 Agent 协作必须经由 Agent Runtime 编排
Runtime 是唯一允许多 Agent 调度的控制面（Control Plane）

Agent = 数据面；Runtime = 控制面。

16.2 Agent 调用模型

单 Agent 调用（默认）：

Client / MCP / API
        ↓
   Agent Runtime
        ↓
     Agent A

不允许 Agent A → Agent B。
Agent 内部只可：调用 Tool、查询 KB、使用 Memory。

多 Agent 协作（编排模式）：

Client
 ↓
Runtime
 ├─ Agent A（分析）
 ├─ Agent B（检索）
 └─ Agent C（输出）

Runtime 明确：调用顺序、中间结果结构、最大深度。

16.3 核心规则与 Runtime 约束

规则	说明
Agent 不得直接调用 Agent	任何 Agent 内部不得直接 HTTP/内部调用另一 Agent；协作只能经 Runtime 编排。
协作仅经 Runtime	客服 → RAG、医疗 → 知识检索等跨域能力，由 Runtime 的编排层或显式 DAG 触发，而非 Agent 间直连。

能力	说明
最大调用深度	单次请求内 Agent 链深度上限（如 3）；超过直接中断，返回安全降级结果。
允许的 Agent DAG	白名单式「允许谁调谁」；Runtime 在执行前校验；禁止运行时“临时串联”。
调用成本与时间预算	每条 Agent 链：token_budget、latency_budget；任一 Agent 超限 → Runtime 中断后续。

配置示例：

runtime:
  max_agent_depth: 3

{
  "medical": ["rag"],
  "customer_service": ["rag"],
  "rag": []
}

16.4 调度失败策略

场景	行为
Agent 超时	中断链路
超预算	返回部分结果
Agent 不可用	启用 fallback Agent

16.5 工程落点

注册表扩展：Agent 注册时声明 allowed_downstream: ["rag"] 或空（不可调其他 Agent）；Runtime 校验 DAG 再执行。
编排层：若需「客服中查文档」，由 Runtime 暴露 组合 Tool（如 cs_chat_with_rag），内部按 DAG 调用 RAG 与客服，而非客服内部调 RAG。
Trace：记录 invocation_chain: ["customer_service", "rag"]，便于审计与成本归因。

17. Prompt / Policy / Tool 版本治理（必须级）

无版本策略则：Prompt 微调导致行为漂移、事故回溯找不到「当时版本」。

17.1 版本策略

类型	建议	说明
Prompt	semver + 内容 hash	如 `1.2.3`，变更时 bump；重大变更可带 hash 后缀便于精确回溯。
Policy	强制版本锁定	部署/发布时锁定 policy 版本；Trace 与审计必须记录 policy_version。
Tool	向后兼容声明	接口变更需兼容旧调用方或升主版本；在 Manifest 中声明 tool 版本（如 `kb_search@2.1`）。

17.2 Trace 中记录版本

在 Agent Call Trace（§14）中增加版本字段，便于事故回溯与 A/B 对比：

{
  "trace_id": "...",
  "agent": "medical",
  "prompt_version": "1.2.3",
  "policy_version": "1.0.1",
  "tools": ["kb_search@2.1", "safety_filter@1.0"],
  "latency_ms": 1200,
  "safety_trigger": false
}

落点：Runtime 在派发请求时注入当前 Agent 的 prompt_version / policy_version；各 Tool 执行处上报 tool 及版本。

18. 成本与预算控制（必须级）

目标：让 Agent 平台「算得清账、卖得了钱、控得住成本」。
平台一定会被问到的问题；无预算则 Agent 越多成本越不可控，SaaS 定价无法落地。

18.1 成本模型拆分

维度	说明
LLM Token	Prompt + Completion
Tool	API 调用
KB	向量检索
Memory	读写次数

18.2 Runtime 成本控制机制（强制）

单请求预算：

{
  "max_prompt_tokens": 4000,
  "max_completion_tokens": 1000,
  "max_tool_calls": 5
}

Agent 级成本上限：

agent:
  medical:
    max_tokens_per_request: 3000
  rag:
    max_tokens_per_request: 2000

用户 / MCP Key 配额：

对象	限制
User	日 / 月
MCP Key	QPS + 月度 token
Organization	总预算

18.3 成本可观测（必须写入 Trace）

{
  "cost": {
    "prompt_tokens": 1200,
    "completion_tokens": 300,
    "tool_calls": 2,
    "estimated_usd": 0.012
  }
}

18.4 成本超限策略

软限制：返回压缩回答。
硬限制：直接拒绝 + 提示升级套餐。

18.5 与现有组件的衔接

Node BFF：配额与限流可前置在 Node（按 user/token），Runtime 做二次校验（按 Agent/tool）。
Trace：记录 tokens_used、estimated_cost、quota_remaining，便于计费与运营。
配置：建议 config/quotas.yaml 或等效配置驱动，便于按环境/版本切换。

19. Agent 能力分级（Trust Level）（强烈建议）

不是所有 Agent 同一风险等级；企业版 / 医疗版 / 教育版的核心机制。

19.1 分级示例

Level	说明	典型 Agent
L0	只读、无外部 Tool	简单 FAQ、文档检索（仅返回片段）
L1	可查 KB，无写操作	RAG 问答、客服知识库检索
L2	可调用外部 API / 写操作	客服工单创建、通知发送
L3	高风险（医疗、金融、法律）	医疗问诊、投资建议

19.2 Runtime 行为

根据 用户身份 / 角色、MCP key、场景（如是否医疗合规环境）决定 是否允许调用高等级 Agent。
在 Node BFF + Policy Gateway 或 Runtime 内做 Trust Level 校验；未授权调用 L3 时返回 403 或降级到 L1/L2。
Manifest 与注册表声明每个 Agent 的 trust_level，与 MCP 能力发现对齐。

20. Memory 生命周期与隔离策略（强烈建议）

目标：避免隐私风险、记忆污染、行为不可控。
仅提「Memory」不够；需明确「活多久、谁可见、合规边界」。

20.1 Memory 分级模型（强制）

层级	范围	生命周期
Request Memory	单次调用	请求结束
Session Memory	会话	会话结束（如 TTL 30min）
Long-term Memory	用户	显式授权（如 TTL 90d）

20.2 Agent Memory 默认策略

Agent	默认
医疗	❌ 禁止长期记忆
RAG	❌ 禁止长期记忆
客服	✅ 可摘要存储

20.3 Memory 写入规则（强制）

只允许写：事实性偏好、问题摘要。
禁止：原始对话全文、医疗症状原文、情绪判断。

20.4 按 Agent 的隔离策略

Agent	建议
医疗	默认禁止长期记忆；仅 request / 可选 session（匿名或脱敏）；禁止把症状/诊断写入用户长期画像除非合规授权。
客服	可持久化问题摘要、工单 ID；会话级对话可保留；长期用户画像需策略与合规一致。
RAG	对话历史可 session 级；用户文档与索引归属已有规范。

20.5 Memory 生命周期管理

memory:
  session_ttl: 30min
  long_term_ttl: 90d

支持用户删除；支持 Agent 主动失效。
落点：Runtime Memory 策略 按 Agent 配置 memory_scope（request | session | user）与 TTL；合规 Hook 可拦截「长期写入」行为。

21. Human-in-the-loop（HITL）接口预留（强烈建议）

目标：让 Agent 在「不确定 / 高风险」时让位于人。
纯自动无法覆盖：医疗高风险需转人工、客服不确定需接管。

21.1 Agent 输出必须包含置信度

{
  "answer": "...",
  "confidence": 0.62,
  "risk_level": "medium"
}

由各 Agent 或合规层填充；Runtime / Policy 据此决策。

21.2 Runtime 决策矩阵

风险	置信度	行为
低	≥0.8	自动
中	0.5–0.8	提示人工
高	任意	强制转人工

21.3 决策与接口（模式）

模式	说明	典型场景
自动	直接返回用户	低风险、高置信
半自动	Agent 生成草稿，人类审核后发布	中风险、中置信
全人工	Agent 仅提供 KB 检索、建议结构；人类主导	高风险、低置信、合规强制

接口预留：Runtime 输出 recommended_action: "auto" | "review" | "human"；Node 或前端据此路由到人工队列、工单或待办。
Trace：记录 recommended_action、confidence、risk_level，便于审计与效果评估。

21.4 医疗场景强制规则

高风险：不允许自动回复；必须转人工 / 医疗专业人员。
所有自动回复：强制免责声明（与 §8.4 合规层一致）。

22. Agent 生命周期管理（加分项）

持续演进且不破坏现有用户：支持暂停、灰度、下线。

22.1 状态

状态	说明
enabled	正常可调
paused	暂停新请求，已有请求可跑完；运维/事故时使用
grayscale	仅部分用户 / 流量可调；用于新版本验证
sunset	已下线，返回明确错误或迁移提示；MCP 不再暴露

22.2 与 MCP / Runtime 的联动

Runtime 注册表：Agent 带 status；调度前校验，非 enabled 且非 grayscale 命中则拒绝或降级。
MCP：Manifest 或 discovery 返回 Agent 状态；IDE / 工作流可感知「不可用」并提示。
配置驱动：AGENTS_STATUS 或等效配置；便于运维一键暂停/恢复，无需改代码。

23. Agent 扩展 Checklist

新增 Agent 时必须满足：

项	说明
能力声明	在 Runtime 注册 capabilities、tools、constraints
KB 策略	明确知识库（含 Meta：domain / level / risk_tag）；与既有 KB 隔离
MCP	提供 MCP tools；Manifest（含 capabilities、input/output、constraints）
Policy	合规、安全、输出约束等；可插 Runtime Hook
Observability	打点（trace、latency、safety_trigger、版本、成本等）
依赖治理	不直连其他 Agent；若需协作，经 Runtime 编排与 DAG 白名单（§16）
版本	Prompt/Policy/Tool 版本声明并在 Trace 中记录（§17）
文档	接口、Manifest、使用说明更新

基座与已有 Agent 不受影响；新 Agent 按 Checklist 接入后，即可通过 Runtime、MCP、Node 暴露。

24. 小结

基座：rag-agent 为 Platform / 基座；RAG 为基座能力，客服、医疗为扩展 Agent。
Agent Runtime：统一调度与约束；注册表、能力声明、Prompt/Policy、Tool 路由、Memory、安全合规 Hook；MCP & REST 只调 Runtime，不直连 Agent。
多 MCP 口子：前端 多 Agent 口子 以 多 MCP 暴露；MCP Capability Manifest 与 Runtime 对齐，支持发现与编排。
Node：BFF + Policy Gateway；用户画像、Agent 权限、限流、MCP token→user。
治理与平台化：KB Meta（分级、标签）、医疗合规层（Policy as Code）、Observability（Trace）、Agent 扩展 Checklist；下一步重在 治理、调度、规范、边界，而非单纯叠加 Agent。
v3.1 新增：Agent 调度与依赖治理（§16：不直连、DAG/深度/成本预算）、版本治理（§17：Prompt/Policy/Tool 版本 + Trace）、成本与预算（§18）、Trust Level（§19）、Memory 生命周期与隔离（§20）、Human-in-the-loop（§21）、Agent 生命周期（§22）；满足 规模化 / 商业化 / 长周期演进 的治理与约束。

成熟度自评（v3.1：补足依赖治理 + 版本 + 成本 + Trust + Memory + HITL + 生命周期后）：

维度	评价
架构方向	⭐⭐⭐⭐⭐
工程可落地	⭐⭐⭐⭐
扩展性	⭐⭐⭐⭐⭐
合规意识	⭐⭐⭐⭐⭐
平台化能力	⭐⭐⭐⭐⭐（含 Runtime + 治理 + 成本）

补上 Agent 调用治理、版本 + Trace、成本/配额、Trust Level、Memory 策略、HITL、生命周期 后，本设计可作为 SaaS / 企业级 Agent 平台 的规模化架构基础。

整体升级后的平台状态（补完 §16–§22 后）

✅ 规模化 Agent 调度能力（控制面/数据面分离、DAG 白名单、调度失败策略）
✅ 成本可控、可售卖（成本模型、单请求/Agent 级预算、配额、Trace 可观测、超限策略）
✅ 合规可审计（Memory 写入规则、HITL 决策矩阵、医疗强制规则、版本 + Trace）
✅ 企业 / 医疗可落地（Trust Level、Memory 默认策略、人工接管模式）

直白结论：本设计已从「AI 项目架构」升级为 「Agent 平台治理规范」；下一步不再是「要不要补」，而是 「开始实现哪一块最值钱」。

文档版本：v3.1 | 平台级 Agent 系统 · 依赖治理 + 版本 + 成本 + Trust + Memory + HITL + 生命周期