管理沙盒

本页面演示了如何使用 Python SDK 管理沙盒环境的生命周期。您可以列出现有沙盒、查看其详细信息、暂停和恢复沙盒,或在不再需要沙盒时将其删除。

准备工作

如需管理沙盒,您需要对项目拥有以下角色:

  • Agent Platform User (roles/aiplatform.user)

管理沙盒

您可以列出、查看、暂停、恢复和删除与 Agent Platform 实例关联的沙盒环境。借助暂停和恢复功能,您可以取消为空闲沙盒安排计算资源,并在稍后将其重新上线,而不会丢失文件系统状态或连接身份。如需更改现有沙盒的配置,您必须将其删除并创建一个新沙盒。

列出沙盒

如需列出与 Agent Platform 实例关联的所有沙盒,请运行以下命令:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:Agent Platform 实例的 Google Cloud 区域。 请参阅受支持的国家/地区。
  • INSTANCE_ID:Agent Platform 实例 ID。

查看沙盒详情

如需查看特定沙盒的配置和状态,请执行以下操作:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:Agent Platform 实例的 Google Cloud 区域。 请参阅受支持的国家/地区。
  • INSTANCE_ID:包含沙盒的 Agent Platform 实例 ID。
  • SANDBOX_ID:现有沙盒 ID。

输出包含创建时间、状态(例如 STATE_RUNNING)和沙盒规范等详细信息。

暂停沙盒

暂停沙盒会释放其计算资源,同时保留磁盘状态和连接元数据。暂停的沙盒费用远低于运行中的沙盒,并且可以在几秒钟内恢复。当沙盒长时间处于空闲状态,但您希望保留会话状态和连接身份以供日后使用时,请使用暂停。

暂停的沙盒具有以下特征:

  • 保留其沙盒 ID、连接元数据和任何 Private Service Connect 端点。
  • 在暂停时保留所有容器内文件系统状态。
  • 改用 STATE_PAUSED。在您恢复之前,向其数据平面端点发出的请求会返回错误。

如需暂停正在运行的沙盒,请运行以下代码:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:Agent Platform 实例的 Google Cloud 区域。 请参阅受支持的国家/地区。
  • INSTANCE_ID:包含沙盒的 Agent Platform 实例 ID。
  • SANDBOX_ID:现有沙盒 ID。

恢复沙盒

恢复已暂停的沙盒会使其计算资源重新上线。沙盒会保留其在暂停时的 ID、连接端点(包括任何 Private Service Connect 服务连接)和文件系统状态。恢复操作完成后,可以再次向沙盒发出数据平面请求。

如需恢复已暂停的沙盒,请运行以下代码:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:Agent Platform 实例的 Google Cloud 区域。 请参阅受支持的国家/地区。
  • INSTANCE_ID:包含沙盒的 Agent Platform 实例 ID。
  • SANDBOX_ID:已暂停的沙盒 ID。

删除沙盒

如需明确删除沙盒环境并释放资源,请执行以下操作:

client.sandboxes.delete(name=sandbox_name)
print("Sandbox deleted.")

审核日志记录和监控

当您在沙盒中管理和执行命令时,Agent Platform 会在 Cloud Audit Logs 中记录 API 级活动,并使用 aiplatform.googleapis.com 服务名称和 audited_resource 受监控的资源类型:

  • 管理员活动 (ADMIN_WRITE) 日志:系统会自动记录控制平面生命周期变更,包括 CreateSandboxEnvironment、PauseSandboxEnvironment、ResumeSandboxEnvironment、SnapshotSandboxEnvironment 和 DeleteSandboxEnvironment(需要 aiplatform.sandboxEnvironments.* IAM 权限)。
  • 数据访问 (ADMIN_READ) 日志:在为元数据读取操作(包括 GetSandboxEnvironment 和 ListSandboxEnvironments)启用时记录。
  • 数据访问 (DATA_WRITE) 日志:在为数据平面命令执行和访问授权调用(包括 ExecuteSandboxEnvironment、BidiExecuteSandboxEnvironment、AuthorizeSandboxEnvironmentAccess 和 ExecuteCode)启用时记录。对于受 VPC Service Controls 保护的资源,审核日志中会省略请求和响应载荷。

请注意以下可观测性和威胁检测边界:

  • 容器内进程和流活动:Cloud Audit Logs 会记录发起命令执行或授权连接的 API 请求,但不会记录容器内生成的各个子进程、文件系统修改,也不会记录通过打开的 WebSocket、Chrome DevTools Protocol (CDP) 或 PTY 会话发送的后续交互式帧。
  • 容器 stdout 和 stderr 日志记录:针对 Agent Runtime 的自动 Cloud Logging 收集(例如 reasoning_engine_stdout 和 reasoning_engine_stderr)仅适用于父级 ReasoningEngine 实例,不会自动从沙盒子资源收集日志。命令输出(stdout、stderr 和退出代码)会在执行响应中返回给父智能体,您可以在其中检查结构化条目并将其写入 Cloud Logging。
  • 威胁检测和网络检查:沙盒通过 gVisor 内核隔离和无特权的沙盒内身份(无环境 Google Cloud 凭据)强制执行隔离。如需监控异常行为或未经授权的网络出站流量,请将 DATA_WRITE 审核日志与父智能体上的智能体异常检测相结合,并通过 Private Service Connect 接口路由沙盒出站流量,同时使用 VPC 流日志、Cloud Next Generation Firewall (Cloud NGFW) 规则日志记录和 Secure Web Proxy 检查。如需了解详情,请参阅安全、身份和可观测性边界。