本页面演示了如何使用 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 检查。如需了解详情,请参阅安全、身份和可观测性边界。