本頁面說明如何直接呼叫 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 使用者 (
roles/aiplatform.user)。 - 用於產生權杖的服務帳戶必須具備服務帳戶權杖建立者 (
roles/iam.serviceAccountTokenCreator) 角色。 - 用於產生權杖的服務帳戶也必須具備專案的 Agent Platform 使用者 (
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」：您的專案 ID。 Google Cloud
- 「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 Token (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 替換為具有「服務帳戶權杖建立者」角色的服務帳戶電子郵件地址。
傳送要求至沙箱
將 HTTP GET 要求傳送至沙箱 API 伺服器，檢查伺服器狀態。
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()
後續步驟
- 如要瞭解沙箱生命週期管理，請參閱「快照」。