Computer Use quickstart

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. This feature provides a sandbox environment for AI Agents, and so the "Agentic AI Services" Service Specific Terms apply. To utilize this feature, you will need to enable full network access for your AI Agent so please consider applicable safeguards (including human supervision) and your organization's policies before doing so. For built-in computer use safeguards, consider the Agent Platform Computer Use Tool.

Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page demonstrates how to make direct API calls to create and use a Computer Use sandbox environment. In this quickstart, you perform the follow tasks:

• Create an Agent Platform instance to access the sandbox.
• Create a Computer Use sandbox.
• Generate an access token for the sandbox.
• Send a request to check status.
• Clean up resources.

Before you begin

Set up your project and environment.

Set up your project

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Get the required roles

To use the sandbox and generate tokens, you need the following roles:

• Agent Platform User (roles/aiplatform.user) on the project.
• Service Account Token Creator (roles/iam.serviceAccountTokenCreator) on the service account used for token generation.
• The service account used for token generation must also have the Agent Platform User (roles/aiplatform.user) role on the project.

Install libraries

Install the Agent Platform SDK: posix-terminal pip install google-cloud-aiplatform>=1.112.0

Create an Agent Platform instance

To use the sandbox, first create an Agent Platform instance.

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

Replace the following:

• 'PROJECT_ID': Your Google Cloud project ID.
• 'LOCATION': The region for your instance (such as us-central1).

Create a template for Computer Use

Create a sandbox template that you'll use when you create a Computer Use sandbox.

# 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 Computer Use sandbox

Create a sandbox environment from the template.

# 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}")

Generate an access token

To interact with the sandbox, generate a JSON web token (JWT) access token by using a service account.

service_account_email = "SERVICE_ACCOUNT_EMAIL"
access_token = client.agent_engines.sandboxes.generate_access_token(
    service_account_email=service_account_email,
)

Replace SERVICE_ACCOUNT_EMAIL with the email of the service account that has the Service Account Token Creator role.

Send a request to the sandbox

Send a HTTP GET request to the sandbox API server to check its status.

response = client.agent_engines.sandboxes.send_command(
    http_method="GET",
    access_token=access_token,
    sandbox_environment=sandbox
)
print(f"Sandbox response: {response.body}")

Clean up

To avoid incurring charges, delete the resources created in this quickstart.

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

What's next

• Explore Snapshots for sandbox lifecycle management.