> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/agentic_ai_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/agentic_ai_guide/di-san-bu-fen-gong-cheng-shi-jian-yu-luo-di/09_agentops/9.5_enterprise.md).

# 9.5 企业级智能体平台：架构、安全与治理

在本地 Notebook 里跑通一个智能体只是第一步，将其转化为可扩展、安全且合规的企业级服务则面临着完全不同的挑战。

企业级部署不仅关注 **高可用性**，更核心的是 **安全性**、**多租户隔离** 和 **治理**。本节将深入探讨如何构建一个生产就绪的智能体平台。

## 9.5.1 多租户与隔离架构

智能体应用通常是 **有状态** 且 **长运行** 的，这决定了其架构必须能够处理复杂的资源隔离和状态管理。

### 1. 异步任务队列与状态管理

由于智能体执行可能持续数分钟甚至更久，同步 HTTP 请求不可行。推荐使用 **异步事件驱动架构**，如下图所示。

```mermaid
graph LR
    %% Agentic Design System
    classDef user fill:#fff7e6,stroke:#fa8c16,stroke-width:2px;
    classDef agent fill:#e6f7ff,stroke:#1890ff,stroke-width:2px;
    classDef tool fill:#f6ffed,stroke:#52c41a,stroke-width:2px;
    classDef system fill:#f0f0f0,stroke:#d9d9d9,stroke-width:2px;
    classDef memory fill:#fff0f6,stroke:#eb2f96,stroke-width:2px;

    Client["客户端"] -->|"POST /task"| API_Gateway["API 网关"]
    API_Gateway -->|"推送任务"| Queue["任务队列<br/>(Redis/RabbitMQ)"]

    subgraph AgentWorkerCluster["智能体工作集群"]
        Dispatcher["调度器"] -->|"拉取"| Queue
        Dispatcher -->|"启动"| Worker["智能体 Worker<br/>(Pod/容器)"]

        Worker -->|"模型调用"| Model_Gateway["模型网关"]
        Worker -->|"工具调用"| External_APIs["外部 API"]
        Worker -->|"状态更新"| State_Store["状态数据库<br/>(PostgreSQL)"]
    end

    Client -.->|"WebSocket / 轮询"| API_Gateway
    API_Gateway <-->|"读取状态"| State_Store

    class Client user;
    class API_Gateway,Dispatcher system;
    class Queue memory;
    class Worker agent;
    class Model_Gateway,External_APIs tool;
    class State_Store memory;
```

图 9-13：异步事件驱动架构

* **提交**: 返回 `TaskID`，状态 `Accepted`。
* **执行**: Worker 异步执行，状态持久化到数据库。
* **流式**: 通过 WebSocket 推送思考过程和增量结果，缓解用户焦虑。

### 2. 多租户工作池

在企业内部或者 SaaS 平台，不同部门（如财务部与研发部）的智能体需要严格隔离。

* **计算隔离**: 使用 Kubernetes Namespaces 或不同的 Node Pools 隔离不同租户的 Worker。
* **网络隔离**:
  * **Egress Control**: 财务部的 Agent 只能访问 ERP 系统，严禁访问外网。
  * **Service Mesh**: 使用 Istio/Cilium 实施细粒度的网络策略。

## 9.5.2 深度防御体系

安全不仅仅是 Prompt 上的约束，必须构建多层防御体系。随着工具连接协议与工具服务的普及，Agent 可调用的工具范围大幅扩展，安全防御的重要性也随之倍增。

关于 Agent 安全威胁的完整分类（提示词注入 vs 越狱、供应链攻击等）和通用防御策略，详见[第 11.1 节](/agentic_ai_guide/di-si-bu-fen-wei-lai-zhan-wang/11_future/11.1_security.md)。本节重点关注**企业级部署中的工程实现与运维观点**。

### 多层防御架构速览

| 防御层级      | 关键技术              | 主要作用                        | 详见章节      |
| --------- | ----------------- | --------------------------- | --------- |
| Layer 1-3 | Prompt 工程、护栏、应用鉴权 | 在应用逻辑层防止越权与不当调用             | 11.1.2    |
| Layer 4   | 结构化输出约束           | 确保模型输出符合 Schema，防止注入导致的格式污染 | 9.5.2（下文） |
| Layer 5   | 基础设施沙箱            | 隔离代码执行环境，防止恶意代码逃逸           | 9.5.2（下文） |
| Layer 6   | 侧车代理安全联网          | 对外网访问的密钥与域名白名单管理            | 9.5.2（下文） |

### Layer 4: 结构化输出约束

在企业级智能体核心链路上，底层大模型往往被要求精确输出符合特定语法（如 JSON 或 XML Schema）的数据以供下游 API 解析消费。完全依赖“基于 Prompt 提示配合事后校验和重试”会导致高频的失败及高昂的成本，这在严苛的生产环境中不可接受。

* **系统层面极高的 Schema 一致性保证**: 现代高性能推理引擎（例如 vLLM, SGLang, TensorRT-LLM）在模型自回归生成循环底层引入了高度压缩的有限状态机（FSM）或正则表达式。它在每一步生成时动态计算，通过掩码（Logits Masking）直接在模型的输出概率矩阵中屏蔽掉所有潜在的不合规词汇，从物理层面提供了极高可靠的格式确定性（Schema Reliability）。且这类引擎通过异步与 GPU 前向并发的底层设计，使得加上护栏后完全不再拖累系统的原生吞吐。

### Layer 5: 基础设施沙箱

这是最后一道防线，防止 Agent 执行恶意代码。

* **MicroVM 沙箱**：可选用轻量虚拟化或容器隔离方案来运行不可信代码。
  * **托管式沙箱**：也可以使用第三方沙箱服务，按需启动受控执行环境。
* **文件系统隔离**: 沙箱内只能访问临时 `/tmp`，任务结束后立即销毁，不留任何痕迹。

### Layer 6: 侧车代理安全联网

当智能体需要访问外部 API 或互联网时，直接暴露网络权限会带来密钥泄露和越权访问的风险。**侧车代理（Sidecar Proxy）** 模式通过在智能体容器旁部署一个独立的网络代理进程，实现对所有出站请求的拦截、过滤和增强。

**核心架构**

```mermaid
graph LR
    classDef agent fill:#e6f7ff,stroke:#1890ff,stroke-width:2px;
    classDef proxy fill:#fff7e6,stroke:#fa8c16,stroke-width:2px;
    classDef external fill:#f6ffed,stroke:#52c41a,stroke-width:2px;

    Agent["智能体容器"] -->|"curl $API_URL<br>Header: Token=$PLACEHOLDER"| Sidecar["侧车代理"]
    Sidecar -->|"校验域名白名单"| Check{允许?}
    Check -->|Yes| Inject["注入真实密钥"]
    Check -->|No| Block["拒绝并记录"]
    Inject --> External["外部 API"]
    External --> Sidecar
    Sidecar --> Agent

    class Agent agent;
    class Sidecar proxy;
    class External external;
```

**三大安全机制**

* **域名白名单**：开发者预先配置允许访问的域名列表。智能体发出的所有 HTTP 请求必须匹配白名单，否则被侧车代理直接拦截并返回错误。这防止了模型被提示注入攻击诱导去访问恶意 URL。
* **密钥占位符注入**：智能体在容器内永远看不到真实的 API Key 或 OAuth Token。它只能使用预定义的占位符（如 `$API_KEY`）。侧车代理在请求真正发出时，仅对白名单内的目标域名注入真实凭证。即使智能体试图将密钥发送到非授权域名，侧车也会拒绝注入。
* **请求审计与限流**：侧车代理记录所有出站请求的目标、频率和响应状态码，为事后审计提供完整的网络行为日志。同时支持按域名配置速率限制，防止智能体因循环调用而产生意外的高额账单。

**与传统方案的对比**

| 方案         | 密钥安全    | 访问控制粒度    | 审计能力   | 运维复杂度 |
| ---------- | ------- | --------- | ------ | ----- |
| 环境变量直接注入   | ❌ 模型可读取 | 无         | 无      | 低     |
| API 网关集中管理 | ✅ 集中存储  | 中（按路由）    | 中      | 中     |
| **侧车代理**   | ✅ 占位符隔离 | 高（按域名+路径） | 高（逐请求） | 中     |

侧车代理模式是一种常见的工程落地选项，适合把工具访问、密钥代理和审计策略从智能体应用逻辑中解耦。不同生产级智能体平台的实现形态并不相同：有的平台把工具执行、沙箱、文件和审计能力封装在托管运行时中，有的平台则通过企业网关或本地代理承接这些边界。

## 9.5.3 治理与合规

随着 Agent 自主性增强，“谁运行了什么？做了什么？”变得至关重要。工程上需要把互操作协议、鉴权模型、审计事件与可追溯的数据结构统一起来，才能让跨团队的协作与治理真正落地。

### 1. 角色访问控制

* **Agent 定义权限**: 谁可以创建/修改 Agent 的 Prompt 和工具集？
* **Agent 执行权限**: 谁可以向 Agent 下达指令？
* **工具调用权限**：
  * **静态授权**：管理员为智能体绑定可调用的工具与资源范围。
  * **动态授权**：智能体代表用户执行操作时，以用户身份的访问令牌进行代理调用，确保不越权。
* **跨智能体通信授权**：智能体之间通信时，需验证双方身份与权限范围，防止冒充或越权请求。

### 2. 审计日志

所有操作必须 **不可篡改** 地记录：

1. **输入**: 用户的原始 Prompt。
2. **思考**: Agent 的中间推理步骤。
3. **工具**: 调用的函数名、参数、以及 **返回结果**（这是取证的关键）。
4. **输出**: 最终响应。

### 3. 法规合规

不同司法辖区对 AI 系统的合规要求差异较大。面向强监管行业与市场的企业级智能体系统，通常需要重点关注：

* **风险分级与技术文档**：哪些场景属于高风险，需要更严格的验证与记录。
* **透明度义务**：用户是否被明确告知正在与 AI 系统交互。
* **人类监督**：高风险操作是否保留有效的人工介入机制。

### 4. 成本治理

企业级 Agent 平台还需从组织治理角度管控 Token 消耗（详见 9.4 节的成本优化策略）：按团队/部门设定 Agent 调用预算上限，并将成本归因到具体 Agent 实例，配合异常熔断机制防止成本失控。

## 9.5.4 PII 网关与数据隐私

在金融和医疗场景，严禁将客户 PII（个人可识别信息）发送给公有 LLM 模型商。

**架构模式：PII Sidecar / Gateway**

```mermaid
sequenceDiagram
    participant User
    participant Gateway as PII Gateway
    participant LLM as Public LLM
    participant Tool as Internal Tool

    User->>Gateway: "给张三(ID:12345)发邮件"

    Gateway->>Gateway: 识别 PII: "张三", "12345"
    Gateway->>Gateway: 替换为 Token: "[PERSON_1]", "[ID_1]"

    Gateway->>LLM: Prompt: "给 [PERSON_1]([ID_1]) 发邮件"
    LLM->>Gateway: Tool Call: send_email(to="[ID_1]")

    Gateway->>Gateway: 还原参数: to="12345"
    Gateway->>Tool: 执行 send_email(12345)
```

图 9-14：PII 网关脱敏流程

* **PII 识别组件**：可选用开源或商用的 PII 识别与脱敏工具。
* **核心思想**: LLM 只处理逻辑，不接触真实敏感数据。

## 9.5.5 部署策略与可观测性集成

### 蓝绿部署与影子测试

Agent 的行为难以预测，V2 版本的 Prompt 微调可能导致回归。

* **影子模式**: 将线上流量复制一份给 V2 Agent，记录其响应但不返回给用户。后台运行 **Evaluator Agent** 对比 V1 和 V2 的结果质量。

### SIEM 集成

将 Agent 的审计日志对接企业 SIEM 系统。

* **异常检测**: 监控 “工具调用失败率骤增” 或 “Token 消耗异常暴涨”（可能遭受 DoS 攻击或陷入死循环）。

## 9.5.6 企业采用现状

企业落地智能体通常会经历从“试点”到“有限生产”再到“规模化”的过程。可以用权限与自动化程度来粗略划分阶段：

| 阶段      | 特征                      |
| ------- | ----------------------- |
| **实验期** | 在非生产环境尝试，无严格 SLA        |
| **辅助型** | 多为只读权限，辅助检索与总结          |
| **行动型** | 开始引入写权限与自动执行，但有明确的审批与边界 |
| **自治型** | 跨系统自动执行为主，人类介入较少，治理成本高  |

阶段越靠后，越需要把“权限、审计、回滚、成本与故障恢复”做成平台能力，而不是靠应用侧临时补丁。这些平台级能力——从系统指令预设、工具调用管理到生命周期钩子——共同构成了所谓的 **智能体运行壳（Agent Harness）**：一个包裹在模型外围、专门管理长周期任务的操作系统级基础设施层（详见 [9.2 节](/agentic_ai_guide/di-san-bu-fen-gong-cheng-shi-jian-yu-luo-di/09_agentops/9.2_harness.md)）。

下面通过一个完整案例，展示 Harness 各层如何协同工作。

## 9.5.7 实战案例：长周期自主编码智能体的 Harness 架构

### 场景描述

一个企业级自主编码智能体需要独立完成大规模 Web 应用的全栈开发。单次任务跨越多个上下文窗口，累计运行时间可达数小时。任务包括：根据 200+ 功能需求列表，逐项实现前后端代码、编写端到端测试、在浏览器中验证结果。

传统做法是给模型一个高层级 Prompt 然后期望它“一次成型”。实践表明，即使是前沿模型也会因上下文丢失、进度遗忘、环境漂移等问题导致任务失败。Harness 的职责正是解决这些模型本身无法处理的**运行时治理**问题。

### Harness 分层架构

下图展示了 Harness 如何包裹在模型外围，形成六层治理结构：

```
┌─────────────────────────────────────────────────┐
│              Layer 6: 人类监督与升级              │
│  置信度门禁 · 高风险操作审批 · 异常升级           │
├─────────────────────────────────────────────────┤
│              Layer 5: 成本与资源治理              │
│  Token 预算硬切断 · 会话时长上限 · 并发限流        │
├─────────────────────────────────────────────────┤
│              Layer 4: 可观测性与审计              │
│  全链路 Trace · 工具调用日志 · 决策归因            │
├─────────────────────────────────────────────────┤
│              Layer 3: 故障恢复与韧性              │
│  Git 回滚 · 会话重启 · 环境自检 · 降级策略        │
├─────────────────────────────────────────────────┤
│              Layer 2: 跨会话状态管理              │
│  进度文件 · 功能清单 · Git 历史 · 环境快照         │
├─────────────────────────────────────────────────┤
│              Layer 1: 沙箱与权限隔离              │
│  文件系统隔离 · 网络白名单 · 密钥占位符            │
├─────────────────────────────────────────────────┤
│                  LLM（模型层）                    │
│          理解需求 · 推理 · 生成代码                │
└─────────────────────────────────────────────────┘
```

图 9-15：长周期编码智能体的 Harness 分层架构

模型只负责“思考和生成”，其余所有运行时关注点——状态持久化、故障恢复、安全隔离、成本控制、人类升级——全部由 Harness 各层承担。

### 核心机制详解

**1. 跨会话状态管理（Layer 2）**

长周期任务最大的挑战是上下文窗口的边界：每个新会话启动时，模型对之前的工作一无所知。Harness 通过三个持久化机制解决这个问题：

* **进度文件**（`claude-progress.txt`）：每次会话结束前，Harness 指示模型将当前进度、遇到的问题、下一步计划写入该文件。新会话启动时，模型首先读取此文件恢复上下文。
* **结构化功能清单**（`feature-list.json`）：包含全部功能需求，每条附带端到端测试描述和 `passes` 布尔字段。模型每完成一个功能就标记为通过，Harness 据此判断整体进度。
* **Git 历史**：每个功能实现后立即提交，提交消息包含功能编号和摘要。Git 日志成为可回溯的“工作日记”。

**2. 会话初始化协议**

每个新会话遵循固定的启动序列，避免模型浪费 Token 在“搞清楚现在在哪”：

```
Step 1: pwd → 确认工作目录
Step 2: 读取 claude-progress.txt → 恢复上下文
Step 3: 读取 feature-list.json → 选择下一个未完成的功能
Step 4: 运行端到端测试 → 验证环境健康，捕获继承的 Bug
Step 5: 开始实现单个功能
```

这个协议由 Harness 的系统指令强制执行，而非依赖模型自发遵循。

**3. 防止“虚假完成”（Layer 6）**

长周期智能体最危险的失败模式之一是在任务未真正完成时声称已完成。Harness 通过以下机制防范：

* **测试驱动验证**：模型不能自行编辑或删除测试用例。功能是否完成由独立的端到端测试判定，而非模型的自我评估。
* **进度文件交叉校验**：Harness 对比 `feature-list.json` 中的 `passes` 字段与实际测试结果，不一致时拒绝标记为完成。
* **人类升级门禁**：连续 3 次测试失败、或单次会话 Token 消耗超过预算的 80% 时，自动暂停并通知人类审查。

**4. 故障恢复（Layer 3）**

```
故障检测                    恢复策略
─────────                  ─────────
端到端测试失败         →    git revert 到上一个绿色提交，重新尝试
开发服务器崩溃         →    执行 init.sh 重建环境，从进度文件恢复
模型陷入循环           →    Harness 检测重复输出模式，强制结束会话并记录
依赖服务不可用         →    切换到 Mock 服务，标记为降级模式
```

关键原则：每次故障恢复后，Harness 都会将故障原因和恢复措施追加到进度文件中，防止后续会话重蹈覆辙。

**5. 成本治理（Layer 5）**

| 控制维度      | 机制   | 触发条件                  |
| --------- | ---- | --------------------- |
| 单会话 Token | 硬切断  | 超过预设上限（如 200K Tokens） |
| 单功能耗时     | 超时中断 | 单个功能实现超过 30 分钟        |
| 累计成本      | 预算熔断 | 项目总 Token 成本超过预算阈值    |
| 工具调用频率    | 限流   | 同一工具 60 秒内调用超过 20 次   |

### 与全书知识点的映射

| Harness 层 | 对应章节          | 本案例中的具体体现                 |
| --------- | ------------- | ------------------------- |
| 沙箱与权限隔离   | 11.1.2 多层防御体系 | 文件系统隔离、侧车代理管控外部访问         |
| 跨会话状态管理   | 3.6 上下文工程     | 进度文件 + 功能清单 + Git 历史三层持久化 |
| 故障恢复与韧性   | 9.6 故障模式与韧性设计 | Git 回滚、环境重建、循环检测、降级策略     |
| 可观测性与审计   | 9.3 可观测性与调试   | 全链路 Trace、工具调用日志、决策归因     |
| 成本与资源治理   | 9.4 性能优化与成本控制 | Token 预算硬切断、超时中断、频率限流     |
| 人类监督与升级   | 5.4 人机协作      | 测试失败升级、高风险操作审批、置信度门禁      |

### 经验总结

* **Harness 不是框架，是运行时治理层**：框架（如 LangGraph）解决的是开发时的编排问题；Harness 解决的是运行时的安全、状态和恢复问题。二者互补而非替代。
* **状态管理的核心是“让新会话在 5 步内恢复完整上下文”**：进度文件、功能清单、Git 日志、环境自检——每一层都在缩短模型的“冷启动”时间。
* **模型的自我评估不可信**：功能是否完成、代码是否正确，必须由 Harness 管理的独立测试来判定，而非模型的文本输出。
* **Harness 的复杂度应随智能体自主性增长而升级**：实验阶段可以只有日志和预算限制；生产环境则需要完整的六层治理。这与 9.5.6 的企业采用阶段相呼应。

***

**下一节**: [9.6 故障模式与韧性设计](/agentic_ai_guide/di-san-bu-fen-gong-cheng-shi-jian-yu-luo-di/09_agentops/9.6_failures.md)