> 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 可以使用模型输出、知识检索和已批准的 Actions。runtime 边界的设计目标是：Agent 执行不会独立获得对用户、文档、凭据或工具的权威控制。

该架构图展示了浏览器、艾维斯控制平面、Agent 运行时、Tool Gateway、知识检索、模型服务商和外部应用之间的安全交互。关键点是：运行时只接收最小上下文和凭据引用，真正的数据访问、工具调用、凭据注入和高影响 Action 审批仍由受控服务完成。

如需面向企业安全评审的策略说明，请参阅 [Agent 安全策略](/aivis-security/architecture/agent-security-strategy)。

## Runtime 信任边界

| 边界                          | 安全行为                                           |
| --------------------------- | ---------------------------------------------- |
| 浏览器到 AIvis API              | 浏览器会话认证到 AIvis Web 和 API。Runtime 服务不是面向浏览器的接口。 |
| AIvis API 到 Agent Runtime   | AIvis API 只发送获准运行所需的执行上下文。                     |
| Agent Runtime 到 Tool Bridge | 工具调用通过授权 bridge，而不是直接访问数据库或连接器。                |
| Tool Bridge 到 AIvis 服务      | AIvis 服务执行工具可用性、用户上下文、工作区上下文和策略检查。             |

## Runtime 输入

一次 Agent run 可能包含：

* 当前用户和工作区上下文。
* 已选择 Agent 及其配置指令。
* 允许使用的模型和生成设置。
* 已由艾维斯限定范围的检索知识分块。
* 为该 Agent 启用的工具定义。
* request ID、conversation ID 和 trace context 等运行元数据。

Runtime 应把这些值视为执行输入，而不是全局授权。任何读取数据、写入状态、调用集成或访问连接器的行为，仍应经过服务端授权。

## 工具访问

Agent 工具应被视为部署能力，而不是提示词指令。管理员决定启用哪些 Actions、连接器和集成。运行时，艾维斯应将工具调用经过授权检查，并绑定到当前用户、工作区、Agent 和已配置工具集。

| 控制项          | 必要行为                              |
| ------------ | --------------------------------- |
| 工具清单         | 每个工具应有负责人、用途、输入 schema、输出预期和可用范围。 |
| 工具 allowlist | Agent 只应收到它被允许调用的工具。              |
| 参数校验         | 工具输入应在执行前校验。                      |
| 权限检查         | 当用户、Agent、工作区或部署策略不允许时，应拒绝工具调用。   |
| 结果处理         | 工具结果应保留足够审计上下文，但不暴露密钥或原始基础设施细节。   |

## 凭据处理

模型凭据、连接器凭据、API token 和集成密钥必须保留在艾维斯管理的配置中。不要把它们粘贴到提示词、Agent 指令、对话消息、示例或公开文档中。Runtime 服务只应在部署需要时接收有范围的服务凭据。

## Prompt 与指令边界

Agent 指令可以塑造行为，但不是安全边界。不要依赖提示词文本来决定：

* 哪些用户可以读取某个文档。
* 哪些工具调用被允许。
* 哪些外部系统可被访问。
* 某个凭据是否可以被展示。
* 某个管理操作是否被允许。

这些决策应由产品配置和服务端检查完成。

## 输出处理

Agent 输出可能包含检索文本、生成内容、工具结果和错误消息。生产部署应避免把原始 stack trace、本地路径、服务主机名、带值的密钥名或无限制日志返回给最终用户。

## 需要测试的失败模式

| 场景                   | 预期结果                    |
| -------------------- | ----------------------- |
| 用户要求 Agent 调用未启用的工具。 | 工具不可用或被拒绝；run 不应伪造访问能力。 |
| 用户请求范围外文档。           | 检索只返回获授权上下文，或不返回上下文。    |
| 工具参数引用另一个工作区或租户。     | 服务端授权拒绝请求。              |
| 模型输出包含泄露密钥的命令。       | Runtime 和工具不会暴露配置中的密钥。  |
| 连接器或模型 Provider 失败。  | 用户收到有边界的错误，日志保留足够运维细节。  |

## 运维检查

* 验证 runtime 服务只能由获准内部服务访问。
* 确认用户或 Agent 缺少权限时工具调用会被拒绝。
* 在 runtime、bridge 或模型访问变更时轮换服务凭据。
* 使用 request ID 记录 runtime 决策，并能与 AIvis API 日志关联。
* 在为大量 Agent 启用高影响工具前进行人工审查。
* 对每个可调用工具的生产 Agent，至少测试一个允许路径和一个拒绝路径。