Guía de inicio rápido de Computer Use

En esta página, se muestra cómo realizar llamadas directas a la API para crear y usar un entorno de zona de pruebas de uso de la computadora. En esta guía de inicio rápido, realizarás las siguientes tareas:

• Crea una instancia de Agent Platform para acceder a la zona de pruebas.
• Crea una zona de pruebas de uso de la computadora.
• Genera un token de acceso para la zona de pruebas.
• Envía una solicitud para verificar el estado.
• Limpiar los recursos

Antes de comenzar

Configura tu proyecto y tu entorno.

Configura tu proyecto

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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, if it is not already enabled.

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

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, if it is not already enabled.

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

Obtén los roles necesarios

Para usar la zona de pruebas y generar tokens, necesitas los siguientes roles:

• Usuario de Agent Platform (roles/aiplatform.user) en el proyecto.
• Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) en la cuenta de servicio que se usa para generar tokens
• La cuenta de servicio que se usa para generar tokens también debe tener el rol de usuario de Agent Platform (roles/aiplatform.user) en el proyecto.

Instala bibliotecas

Instala el SDK de Agent Platform:

pip install google-cloud-agentplatform>=2.0.1

Crea una instancia de Agent Platform

Para usar la zona de pruebas, primero crea una instancia de Agent Platform.

import agentplatform
client = agentplatform.Client(
    project='PROJECT_ID',
    location='LOCATION',
    http_options={
        "api_version": "v1beta1",
    }
)
remote_agent = client.runtimes.create()
remote_agent_name = remote_agent.api_resource.name

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• LOCATION: Es la región de tu instancia (como us-central1).

Para encriptar tus datos de la zona de pruebas con claves de encriptación administradas por el cliente (CMEK), debes configurar las CMEK cuando crees tu instancia de Agent Platform. Para obtener más información, consulta Configura claves de encriptación administradas por el cliente (CMEK).

Crea una plantilla para el uso de computadoras

Crea una plantilla de zona de pruebas que usarás cuando crees una zona de pruebas de uso de la computadora.

# Create a default Computer Use sandbox template
templates_client = client.sandboxes.templates
tmplt_operation = templates_client.create(
    name=remote_agent_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}")

Crea una zona de pruebas de uso de la computadora

Crea un entorno de zona de pruebas a partir de la plantilla.

Nota: De forma predeterminada, las zonas de pruebas vencen después de 2 horas. Puedes personalizar la vida útil de la zona de pruebas configurando el campo ttl cuando creas una zona de pruebas.

# 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.sandboxes.create(
    name=remote_agent_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}")

Genera un token de acceso

Para interactuar con la zona de pruebas, genera un token de acceso web JSON (JWT) con una cuenta de servicio.

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

Reemplaza SERVICE_ACCOUNT_EMAIL por el correo electrónico de la cuenta de servicio que tiene el rol de creador de tokens de cuenta de servicio.

Envía una solicitud a la zona de pruebas

Envía una solicitud GET de HTTP al servidor de la API de la zona de pruebas para verificar su estado.

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

Envía una solicitud POST de HTTP para navegar a una página específica.

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

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

En la siguiente tabla, se enumeran los métodos y las rutas de acceso adicionales que puedes enviar a tu zona de pruebas:

Método	Ruta	Descripción
GET	/	Obtiene la verificación de estado de la zona de pruebas
POST	/tabs	Crea una pestaña nueva y devuelve sus detalles.
GET	/tabs	Muestra los detalles de todas las pestañas abiertas.
POST	/tabs/{tab_id}/activate	Establece una pestaña como activa y la lleva al primer plano.
BORRAR	/tabs/{tab_id}	Cierra una pestaña específica.
GET	/cdp_ws_endpoint	Muestra la ruta de acceso del extremo de WebSocket de CDP.
POST	/cdp	Ejecuta un comando de CDP en la pestaña activa.
POST	/cdps	Ejecuta varios comandos de CDP en la pestaña activa.

Para obtener más información sobre los comandos y el formato de CDP compatibles, consulta el sitio de CDP.

Realiza una limpieza

Para evitar que se generen cargos, borra los recursos que creaste en esta guía de inicio rápido.

client.sandboxes.delete(name=sandbox.name)
remote_agent.delete()

¿Qué sigue?

• Descripción general de las zonas de pruebas de Computer Use
• Configura los Controles del servicio de VPC
• Configura claves de encriptación administradas por el cliente (CMEK)