本页面演示了如何直接调用 API 来创建和使用计算机使用沙盒环境。 在本快速入门中，您将执行以下任务：
- 创建 Agent Platform 实例以访问沙盒。
- 创建计算机使用沙盒。
- 为沙盒生成访问令牌。
- 发送请求以检查状态。
- 清理资源。
准备工作
设置您的项目和环境。
设置项目
- 登录您的 Google Cloud 账号。如果您是 Google Cloud新手， 请创建一个账号来评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Gemini Enterprise Agent Platform API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Gemini Enterprise Agent Platform API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.
获取所需的角色
如需使用沙盒并生成令牌，您需要以下角色：
- 项目的 Agent Platform User (
roles/aiplatform.user)。 - 用于生成令牌的服务帐号的 Service Account Token Creator (
roles/iam.serviceAccountTokenCreator)。 - 用于生成令牌的服务帐号还必须具有项目的 Agent Platform User (
roles/aiplatform.user) 角色。
安装库
安装 Agent Platform SDK：
posix-terminal
pip install google-cloud-aiplatform>=1.112.0
创建 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”：实例的区域（例如
us-central1）。
为计算机使用创建模板
创建一个沙盒模板，您将在创建计算机使用沙盒时使用该模板。
# Create a default Computer Use sandbox template
templates_client = client.agent_engines.sandboxes.templates
tmplt_operation = templates_client.create(
name=agent_instance_name,
display_name='DISPLAY_NAME',
config={
"default_container_environment": {
"default_container_category": "DEFAULT_CONTAINER_CATEGORY_COMPUTER_USE",
},
"egress_control_config": {
"internet_access": True,
},
},
)
template_name = tmplt_operation.response.name
print(f"Created template: {template_name}")
创建计算机使用沙盒
根据模板创建沙盒环境。
# Create a sandbox environment 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"Created sandbox environment: {sandbox.name}")
生成访问令牌
如需与沙盒互动，请使用服务帐号生成 JSON Web 令牌 (JWT) 访问令牌。
service_account_email = "SERVICE_ACCOUNT_EMAIL"
access_token = client.agent_engines.sandboxes.generate_access_token(
service_account_email=service_account_email,
)
将 SERVICE_ACCOUNT_EMAIL 替换为具有 Service Account Token Creator 角色的服务账号的电子邮件地址。
向沙盒发送请求
向沙盒 API 服务器发送 HTTP GET 请求，以检查其状态。
response = client.agent_engines.sandboxes.send_command(
http_method="GET",
access_token=access_token,
sandbox_environment=sandbox
)
print(f"Sandbox response: {response.body}")
清理
为避免产生费用，请删除在本快速入门中创建的资源。
client.agent_engines.sandboxes.delete(name=sandbox.name)
agent_instance.delete()
后续步骤
- 探索 快照，了解沙盒生命周期管理。