電腦使用快速入門

本頁面示範如何直接呼叫 API，建立及使用電腦用途沙箱環境。在本快速入門導覽課程中，您將執行下列工作：

  • 建立 Agent Platform 執行個體，即可存取沙箱。
  • 建立電腦使用沙箱。
  • 產生沙箱的存取權杖。
  • 傳送要求來查看狀態。
  • 清理資源。

事前準備

設定專案和環境。

設定專案

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

取得必要角色

如要使用沙箱和產生權杖，您必須具備下列角色：

  • 專案的 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： 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.
# To customize the lifetime, set `ttl` to a duration string in seconds (for example, "3600s" for 1 hour).
create_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": 'DISPLAY_NAME',
        "ttl": "3600s",  # Optional. Overrides the default 2-hour sandbox lifetime.
    }
)
sandbox = create_operation.response
print(f"Created sandbox environment: {sandbox.name}")
print(f"Sandbox will expire at: {sandbox.expire_time}")

產生存取權杖

如要與沙箱互動，請使用服務帳戶產生 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}")

傳送 HTTP POST 要求，即可前往特定頁面。

data = {"command": "Page.navigate", "params": {"url": "https://example.com"}}

response = client.agent_engines.sandboxes.send_command(
    http_method="POST",
    path="cdp",
    access_token=access_token,
    request_dict=data,
    sandbox_environment=sandbox
)

下表列出可傳送至沙箱的其他方法和路徑：

方法 路徑 說明
GET / 取得沙箱健康狀態檢查
POST /tabs 建立新分頁並傳回詳細資料。
GET /tabs 列出所有開啟的分頁的詳細資料。
POST /tabs/{tab_id}/activate 將分頁設為有效並移至前景。
刪除 /tabs/{tab_id} 關閉特定分頁。
GET /cdp_ws_endpoint 傳回 CDP WebSocket 端點路徑。
POST /cdp 在現用分頁上執行 CDP 指令。
POST /cdps 在有效分頁上執行多個 CDP 指令。

如要進一步瞭解支援的 CDP 指令和格式，請參閱 CDP 網站。

清除所用資源

為避免產生費用，請刪除在本快速入門導覽課程中建立的資源。

client.agent_engines.sandboxes.delete(name=sandbox.name)
agent_instance.delete()

後續步驟

  • 如要瞭解沙箱生命週期管理，請參閱「快照」。