许多智能体任务都涉及执行不受信任的代码、运行命令、使用网络浏览器或以可能带来安全风险的方式与外部环境交互。Gemini Enterprise Agent Platform 提供隔离的沙盒，以安全地处理这些工作负载。
沙盒提供安全、隔离的执行环境，这些环境是为了代表智能体执行特定任务而生成的。通过在沙盒中运行这些操作，您可以保护基础架构和数据免受智能体可能执行的恶意或错误操作的影响。沙盒通过以下方式降低这些风险：
- 隔离：每个沙盒都与其他沙盒和主机系统隔离。一个代理在沙盒中执行的操作不会影响共享相同运行时资源的其他代理或用户。
- 安全性：沙盒内的操作受到限制，可防止对资源的未经授权访问。所有沙盒环境都使用安全的容器沙盒，从而提供强大的安全边界。恶意代码无法访问运行时中的敏感数据或凭据。
- 安全性：如果智能体执行有害命令或无限循环，其影响会限制在沙盒内。例如，编写不当或恶意代码可能会消耗所有可用的 CPU 或内存。
沙盒与运行时对比
Agent Runtime 和沙盒在用途和用法上有所不同：
- Agent Runtime：这是智能体的核心逻辑、决策和编排运行的环境。这是一个可信环境，用于执行代码并管理智能体的生命周期。
- 沙盒：这是由智能体或平台生成的辅助环境，用于执行特定的、可能不安全的任务。沙盒可以是短期的、基于会话的，也可以是持续数天的有状态沙盒。
例如，如果智能体需要通过生成并运行自定义 Python 脚本来计算复杂公式，则应在代码执行沙盒中运行该脚本，而不是在自己的运行时中运行。此外，如果代理使用技能和 shell 脚本，则必须使用最终用户的访问权限，在专门为该会话预配的环境中运行它们。
TTL 和沙盒预配速度
沙盒环境具有以下存留时间 (TTL) 和预配特性：
- TTL：沙盒 TTL 各不相同，从自定义容器映像的 7 天到代码执行沙盒的 14 天不等。这样，您就可以在几天后恢复沙盒环境中的状态，以便执行长跨度任务和可恢复的 shell 环境。
- 预配：创建新沙盒最多需要 2 分钟才能从冷启动预配资源，但在预配后，沙盒通常会在几秒钟内启动。您可以在以下开源项目中查看底层架构：AX 和 Substrate。
特性
沙盒提供多种功能，例如预定义沙盒、自定义容器、企业安全控制和生命周期管理：
- 代码执行：允许智能体在安全的环境中生成和运行代码。这对于复杂的数学计算、数据分析和其他需要计算的任务非常有用。
- 计算机使用：使智能体能够与网络浏览器交互，以执行填写表单、搜索网络或浏览复杂界面工作流等任务。
- 自定义容器：您可以“自带容器”，使用特定的库、工具或配置自定义执行环境。使用此选项可为代理提供一个 shell 环境，其中包含自定义映像中的命令和工具。
- VPC Service Controls：配置安全边界，以保护敏感数据并防止未经授权的数据从沙盒环境流出。
- 客户管理的加密密钥 (CMEK)：使用在 Cloud Key Management Service (Cloud KMS) 中管理的加密密钥保护沙盒静态数据。
安全性、身份和可观测性边界
在设计在沙盒中执行不受信任代码或命令的智能体时，请考虑 Agent Platform 如何在 Agent Runtime 和沙盒容器之间分离执行身份、网络出站流量过滤和审核日志记录。
执行身份和凭证边界
在沙盒内执行的代码会在 gVisor 隔离的容器内由 Google 管理的租户项目中运行，并且不会继承父级智能体的身份或凭据。下表总结了沙盒操作中涉及的身份：
| 身份层 | 主体 | 范围和权限 |
|---|---|---|
| 父智能体 Agent Runtime 身份 | 代理身份 (principal://agents.global.org-ORG_ID.system.id.goog/...) 或附加到 ReasoningEngine 实例的自定义或默认服务账号 |
由 Agent Runtime 中运行的编排代码使用，用于调用 Google Cloud API 以及管理或调用沙盒。绝不会装载到沙盒容器内。 |
| 沙盒服务代理 | service-PROJECT_NUMBER@gcp-sa-vertex-sandbox. |
Google 管理的每个项目服务代理，由沙盒控制平面用于执行基础架构任务，例如从 Artifact Registry 拉取自定义容器映像或使用 CMEK 密钥。绝对无法被沙盒内运行的代码访问。 |
| 沙盒内执行环境 | 由无特权租户身份 (sandbox-untrusted) 支持的无特权容器用户（例如 shell 沙盒中的 appuser），在您的项目中没有任何 Identity and Access Management (IAM) 角色 |
在沙盒 Pod 中运行不受信任的代码。没有环境 Google Cloud 凭据，也没有对您的项目或父级 ReasoningEngine 的权限。 |
在沙盒中运行代码时，请注意以下凭据和身份验证边界：
- 没有环境凭据或元数据服务器令牌访问权限：沙盒化代码没有项目的应用默认凭据 (ADC)，无法查询 Compute Engine 元数据服务器 (
169.254.169.254:80) 来铸造 OAuth 2.0 访问令牌、读取服务账号密钥或检查宿主项目元数据。 - 入站调用方身份验证：您的代理或客户端使用 IAM（
aiplatform.sandboxEnvironments.execute权限，包含在roles/aiplatform.user等角色中）或由generate_access_token或generate_browser_ws_headers生成的短期访问令牌向沙盒控制平面和数据平面进行身份验证。 - 对来自沙盒内部的出站调用进行身份验证：由于沙盒没有环境身份，因此直接从沙盒内部发出的任何外部 API 调用都必须使用您明确提供的凭据。最好在 Agent Runtime 上的父智能体中执行经过身份验证的 Google Cloud API 操作，并且仅将所需的输入数据传递到沙盒中。如果沙盒内的代码必须直接调用外部服务，请为该特定执行注入短期、范围狭窄的令牌，而不是传递长期服务账号密钥。
网络出站流量和网域许可清单
沙盒不提供沙盒或 SandboxEnvironmentTemplate 资源的内置网域许可清单属性。出站网络行为取决于沙盒类型和模板上的 egress_control_config 设置：
- 代码执行沙盒：在没有出站互联网或虚拟私有云 (VPC) 网络访问权限的情况下运行。
- 基于模板的沙盒（计算机使用、Shell 沙盒和自定义容器）：默认停用出站互联网访问权限（
internet_access为False）。 - 直接互联网出站流量（
internet_access: True，不含network_attachment）：授予沙盒对公共 IP 地址 (0.0.0.0/0) 的无限制出站访问权限，而网络政策会阻止对专用 RFC 1918 地址范围（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）和链路本地元数据范围 (169.254.0.0/16) 的访问。您无法直接在egress_control_config中指定允许或拒绝的网域列表。 - 使用 VPC 控制功能进行网域许可清单和出站流量过滤：如需将沙盒限制为特定网域 (FQDN)、网址或 IP 范围，请在模板上配置
egress_control_config.network_attachment，以通过 Private Service Connect (Private Service Connect) 接口将所有沙盒出站流量桥接到 VPC。流量进入 VPC 后，使用以下工具强制执行网域许可清单和出站流量政策：- Cloud Next Generation Firewall (Cloud NGFW)：创建全球网络防火墙政策出站规则，以允许特定目标 FQDN 或 IP 范围，并拒绝所有其他出站流量 (
0.0.0.0/0)。 - 安全 Web 代理 (Secure Web Proxy)：通过安全 Web 代理路由来自 Private Service Connect 子网的出站流量，以进行第 7 层 TLS 检查和网址级许可清单。
- Cloud DNS 对等互连：配置
dns_peering_configs和专用 Cloud DNS 区域，以便沙盒仅通过 VPC 而非公共 DNS 解析器解析已批准的名称。
- Cloud Next Generation Firewall (Cloud NGFW)：创建全球网络防火墙政策出站规则，以允许特定目标 FQDN 或 IP 范围，并拒绝所有其他出站流量 (
如需查看分步配置说明，请参阅通过沙盒配置 VPC Service Controls 和 Private Service Connect。
审核日志记录和威胁检测
沙盒的可观测性和安全监控涵盖 Agent Platform API 控制平面和数据平面、Agent Runtime 上的父智能体以及您的 VPC 网络。
Cloud Audit Logs 覆盖范围
Agent Platform 会在 aiplatform.googleapis.com 服务名称和 audited_resource 受监控的资源类型下为对沙盒资源进行的 API 调用写入 Cloud Audit Logs 日志条目，但不会为容器内生成的内部进程生成审核日志条目。下表总结了在每个边界记录的内容：
| 活动类型 | API 方法或操作 | 日志类别 | 备注 |
|---|---|---|---|
| 沙盒和模板生命周期变更 | CreateSandboxEnvironment、DeleteSandboxEnvironment、SnapshotSandboxEnvironment、PauseSandboxEnvironment、ResumeSandboxEnvironment、CreateSandboxEnvironmentTemplate、UpdateSandboxEnvironmentTemplate、DeleteSandboxEnvironmentTemplate、DeleteSandboxEnvironmentSnapshot |
管理员活动 (ADMIN_WRITE) |
默认情况下始终处于启用状态。记录调用方身份、资源名称和操作元数据。 |
| 沙盒和模板元数据读取次数 | GetSandboxEnvironment、ListSandboxEnvironments、GetSandboxEnvironmentTemplate、ListSandboxEnvironmentTemplates、GetSandboxEnvironmentSnapshot、ListSandboxEnvironmentSnapshots |
数据访问 (ADMIN_READ) |
此日志默认停用。为 aiplatform.googleapis.com 启用 ADMIN_READ 日志，以审核谁检查或列出了沙盒。 |
| 数据平面命令执行和访问授权 | ExecuteSandboxEnvironment、BidiExecuteSandboxEnvironment、AuthorizeSandboxEnvironmentAccess、ExecuteCode |
数据访问 (DATA_WRITE) |
此日志默认停用。为 aiplatform.googleapis.com 启用 DATA_WRITE 日志，以审核执行 RPC 和令牌生成。对于 VPC Service Controls 边界内的资源，审核日志中会省略请求和响应载荷。 |
| 容器内子进程、文件写入和交互式流帧 | 由 shell 命令、文件系统修改以及通过打开的 WebSocket、Chrome DevTools Protocol (CDP) 或 PTY 会话发送的单个帧生成的子进程 | 未记录在 Cloud Audit Logs 中 | Cloud Audit Logs 会记录初始 API 调用（ExecuteSandboxEnvironment、BidiExecuteSandboxEnvironment 或 AuthorizeSandboxEnvironmentAccess），而不会记录后续的客户机内系统调用或流帧。 |
容器 stdout 和 stderr 输出 |
在沙盒内运行的命令的标准输出和错误流 | 在执行 API 响应中返回 | 自动 Cloud Logging 收集（例如 reasoning_engine_stdout）仅适用于父级 ReasoningEngine 运行时，不会从沙盒子资源收集日志。在 Agent Runtime 中记录父智能体的命令输出，或参阅管理沙盒。 |
威胁检测和监控
沙盒在 Google 管理的租户项目中使用 gVisor 内核隔离强制执行运行时包含，并且不运行内置的来宾主机入侵检测代理或自动预部署漏洞扫描程序。如需监控沙盒活动并检测威胁，请结合使用以下控制措施：
- 启用数据访问审核日志：在
aiplatform.googleapis.com上启用ADMIN_READ和DATA_WRITECloud Audit Logs，以检测未经授权的沙盒创建、访问令牌生成 (AuthorizeSandboxEnvironmentAccess) 或执行请求。 - 监控父智能体行为：启用智能体异常检测，以分析 Agent Runtime 智能体中的跟踪记录、工具调用和执行模式。
- 检查 VPC 中的网络出站流量：使用 Private Service Connect 接口将沙盒出站流量桥接到 VPC，并在 Private Service Connect 子网上启用 VPC 流日志、Cloud NGFW 规则日志记录、Secure Web Proxy 访问日志和 Cloud DNS 查询日志记录，以检测异常出站连接或数据渗漏尝试。
- 在部署前扫描自定义容器映像：使用自定义容器 (BYOC) 时，请在 Artifact Registry 中启用漏洞扫描，以便在
SandboxEnvironmentTemplate中引用映像 URI 之前识别易受攻击的软件包。