> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Agent 安全策略

> 艾维斯如何让 Agent 执行保持有范围、可审计，并保护企业机密数据。

艾维斯Agent 面向企业环境设计：用户可能要求 Agent 搜索私有知识、处理敏感上下文，并调用获准工具。安全策略的核心是：让 Agent 具备执行能力，但不能绕过产品授权、租户边界、凭据管理或审计策略。

上图展示了 Agent 执行的关键安全边界：用户请求先进入可信 AIvis API 边界，经过身份、工作区、Agent 配置和 request ID 绑定后，只把最小必要上下文传递给运行时。知识检索、工具调用和模型调用分别经过权限控制；用量与审计遥测只记录事实，不复制完整 prompt、模型回复、推理轨迹、原始工具参数或密钥。

## 安全目标

| 目标               | 艾维斯策略                                                     |
| ---------------- | --------------------------------------------------------- |
| 防止机密信息泄漏         | Agent 只接收有范围的上下文和已批准工具。Prompt 不能扩大文档、连接器、工作区或工具访问范围。      |
| 保持执行可归因          | Agent run、工具调用和用量记录绑定可信服务端用户、工作区、Agent 和 request context。 |
| 最小化敏感内容存储        | 运维遥测应存储用量事实和标识符，而不是完整 prompt、回复、推理轨迹或工具参数。                |
| 遇到歧义 fail-closed | runtime 身份缺失、过期、伪造、已删除或存在多个候选时，应拒绝访问，而不是回退到上一个用户或宽泛服务账号。  |
| 凭据与 prompt 分离    | 模型、连接器和工具凭据保留在受管理配置中，不被当作 prompt 文本处理。                    |

## Agent 授权模型

Agent 不是管理员、数据库客户端，也不是连接器凭据所有者。它只是由用户请求、Agent 配置、检索上下文和允许工具生成的执行计划。

艾维斯应在资源归属服务中执行授权：

* 知识检索受工作区、连接器、文档可见性、文档集、群组和源系统映射限制。
* 工具调用会按当前用户、工作区、Agent 配置、部署策略和工具 allowlist 检查。
* 模型访问由管理员维护的 Provider 配置和模型可用性控制。
* 会改变状态的 Action 在执行前由服务端授权。
* 用户 prompt 和 Agent 指令不能授予新工具、扩大文档范围、冒充其他用户或覆盖租户边界。

## 机密信息边界

| 边界           | 保护行为                                                             |
| ------------ | ---------------------------------------------------------------- |
| Prompt 与回复内容 | 不把对话内容作为授权来源。运维遥测避免存储完整 prompt、回复、推理或工具参数。                       |
| 检索知识         | 只返回通过当前用户、工作区、Agent 和文档范围授权的分块。                                  |
| 工具参数         | 执行前按 schema 和策略校验。参数可能包含客户数据、密钥或记录 ID 时，避免记录原始值。                 |
| 凭据           | 密钥保存在受管理配置中。不要把凭据放进 Agent 指令、示例、OpenAPI 描述或 MCP server metadata。 |
| 错误输出         | 返回有边界的用户可见错误。不暴露 stack trace、本地路径、内部主机名、原始密钥值或无限制日志。             |

## 可信身份链路

Agent 执行应依赖可信 AIvis 服务提供的身份，而不是浏览器可控 header 或用户提交参数。安全部署应：

1. 在 API 边界确认已认证用户和工作区。
2. 将 Agent run 绑定到服务端 request ID、conversation ID、Agent ID 和 workspace ID。
3. 只向 runtime 服务传递必要执行上下文。
4. 移除或忽略用户伪造的身份 header。
5. 通过部署控制的服务注册或网络元数据校验 runtime 来源身份。
6. 当身份映射缺失、过期、已删除、重复或存在其他歧义时，拒绝 run 或工具调用。

这样可以防止 Agent 任务继承上一个用户上下文、冒充其他工作区，或被归因到宽泛共享服务身份。

## 工具与 Action 控制

Agent 只能调用被明确启用的工具。在工具对 Agent 可用前，请审查：

| 审查项       | 重要原因                                             |
| --------- | ------------------------------------------------ |
| 负责人和用途    | 每个工具都需要业务负责人和清晰的允许用途。                            |
| 输入 schema | 强 schema 可减少 prompt 驱动的参数注入和意外越权。                |
| 权限检查      | 资源归属服务必须校验当前用户、工作区、Agent 和策略。                    |
| 凭据范围      | 使用最小权限凭据。除非必须写入，否则优先只读凭据。                        |
| 副作用       | 会发送消息、创建记录、更新系统或触发支付的工具应标记为高影响工具。                |
| 审计记录      | 保留足够 metadata，用于追踪谁发起了 Action、何时执行、调用了哪个工具、是否成功。 |

高影响工具应先通过小范围 allowlist 上线，同时测试允许路径和拒绝路径，并在生产使用后复盘。

## 不采集内容的遥测

企业管理员通常需要查看用量和成本，但这不应要求把敏感 prompt 或回复复制到分析表中。艾维斯遥测应优先存储轻量事实：

* Request 或 span 标识符。
* 时间戳和执行路径。
* 用户、工作区、Agent 和 persona 标识符或快照。
* 模型和 Provider 标识符。
* token 数、耗时、状态和成本快照。
* 审计需要时的工具名称和结果，但不记录原始密钥值或完整客户 payload。

应避免存储：

* 完整 prompt。
* 完整模型回复。
* 推理轨迹。
* 原始工具参数。
* 连接器凭据值。
* access token 或 API key。

如果用户被删除，历史聚合用量可保留用于运营核算，但面向用户的报表不应显示已从身份系统移除的个人数据。

## Fail-closed 示例

| 场景                       | 预期行为                  |
| ------------------------ | --------------------- |
| 请求缺少已认证用户上下文。            | 拒绝 Agent 执行或工具归因。     |
| 浏览器提交 runtime 身份 header。 | 忽略或移除；只使用可信服务端上下文。    |
| runtime 来源身份无法校验。        | 拒绝 run，而不是使用共享默认身份。   |
| 一个来源匹配多个 runtime 映射。     | 在歧义解决前拒绝。             |
| 工具引用另一个租户或工作区。           | 由目标资源归属服务拒绝。          |
| 用户要求 Agent 展示连接器凭据。      | 不暴露受管理密钥；返回有边界的拒绝或错误。 |
| 连接器权限同步不完整。              | 不假设宽泛访问；在权限确认前限制检索。   |

## 企业上线清单

* 为每个生产 Agent 指定负责人。
* 记录每个 Agent 允许使用的知识、模型、工具和副作用。
* 确认 prompt 不能新增工具或覆盖文档权限。
* 至少测试一个用户范围外文档的拒绝检索路径。
* 至少测试一个无权限用户的工具拒绝路径。
* 验证 Agent 遥测不包含完整 prompt、回复、推理轨迹和原始工具参数。
* 验证日志可按 request ID 检索，且不暴露密钥。
* 大范围启用高影响工具前完成审查。
* 按组织数据策略确认保留周期、备份和删除行为。