计算机使用快速入门

本页面演示了如何通过直接 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 the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

获取所需的角色

如需使用沙盒并生成令牌，您需要拥有以下角色：

• 项目的 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}")

发送 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
)

下表列出了您可以发送到沙盒的其他方法和路径：

如需详细了解支持的 CDP 命令和格式，请参阅 CDP 网站。

清理

为避免产生费用，请删除在本快速入门中创建的资源。

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

后续步骤

• 探索用于沙盒生命周期管理的快照。