自定义容器沙盒概览

标准沙盒提供了一组预定义的库，这些库为特定任务（例如代码执行和计算机使用）提供了开箱即用的解决方案。 对于需要特定依赖项、库、自定义工具或专用数据平面接口的智能体工作负载，您可以提供自己的容器映像（也称为自带容器或 BYOC）。借助此功能，您可以在沙盒环境的安全范围内运行自定义工作负载。

准备工作

设置项目、映像仓库和权限。

设置容器映像

  1. 构建容器映像：创建一个包含自定义 环境的 Docker 映像。为确保与 Gemini Enterprise Agent Platform 沙盒兼容，您的自定义映像必须满足以下要求：

    • 操作系统：基于 Linux（例如 Debian 或 Ubuntu）。
    • 运行程序：必须包含 Gemini Enterprise Agent Platform 可用于执行命令的兼容运行程序或入口点。
    • 安全性：不得要求根权限或访问受限 系统资源，因为映像将在安全隔离的沙盒中运行。

  2. 将映像添加到 Artifact Registry：将映像添加到 Google Cloud Agent Platform 可以访问的 Artifact Registry。预配沙盒时，请提供 Artifact Registry 映像 URI。

配置权限

如需允许 Agent Sandbox 从 Artifact Registry 拉取自定义容器映像， 请向 Agent Sandbox 服务代理授予包含该映像的仓库的 Artifact Registry Reader (roles/artifactregistry.reader) 角色：

  • Agent Sandbox 服务代理：service-PROJECT_NUMBER@gcp-sa-vertex-sandbox.

将 PROJECT_NUMBER 替换为您的项目编号。

如需详细了解如何授予角色，请参阅向服务 代理授予权限。

创建 Agent Platform 实例

如果您没有 Agent Platform 实例，请创建一个。

import vertexai
client = vertexai.Client(
    project='PROJECT_ID',
    location='LOCATION',
    http_options={
        "api_version": "v1beta1",
    }
)
agent_instance = client.agent_engines.create()
agent_instance_name = agent_instance.api_resource.name

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • LOCATION：您的 Agent Platform 实例的 Google Cloud 区域。 请参阅支持的区域。

创建自定义容器沙盒

如需创建自定义容器沙盒，您首先需要创建沙盒模板 (SandboxEnvironmentTemplate)。创建模板后，Agent Platform 会创建与该模板关联的预热池，以提供更快、更可靠的启动时间。

如需创建模板，请定义 SandboxEnvironmentTemplate 资源，该资源用于指定自定义容器的配置：

  • 容器映像：托管在 Artifact Registry 中的预构建自定义映像的 URI。
  • 端口：要从容器公开的网络端口。

创建模板

# Create a custom sandbox template
templates_client = client.agent_engines.sandboxes.templates

operation = templates_client.create(
    name=agent_instance_name,
    display_name="DISPLAY_NAME",
    config={
        "custom_container_environment": {
            "custom_container_spec": {
                "image_uri": "IMAGE_LOCATION"
            },
            "resources": {
                "requests": {
                    "cpu": "1",
                    "memory": "500Mi"
                },
                "limits": {
                    "cpu": "1",
                    "memory": "500Mi"
                }
            },
            "ports": [
                {
                    "port": PORT_NUMBER,
                    "protocol": "TCP"
                }
            ]
        },
        "egress_control_config": {
            "internet_access": True
        }
    }
)
template_name = operation.response.name
print(f"Template created: {template_name}")

创建沙盒

定义模板后，您可以通过引用模板资源名称来预配新的沙盒环境。

# Provision a sandbox referencing the template
create_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": "DISPLAY_NAME"
    }
)
sandbox = create_operation.response
print(f"Sandbox environment provisioned: {sandbox.name}")

后续步骤