Guia de início rápido sobre uso de computador

Nesta página, mostramos como fazer chamadas de API diretas para criar e usar um ambiente de sandbox de uso do computador. Neste guia de início rápido, você vai realizar as seguintes tarefas:

• Crie uma instância da Agent Platform para acessar o sandbox.
• Crie um sandbox de uso de computador.
• Gere um token de acesso para o sandbox.
• Envie uma solicitação para verificar o status.
• Limpar recursos.

Antes de começar

Configurr o projeto e o ambiente.

Criar o projeto

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

Ter os papéis necessários

Para usar o sandbox e gerar tokens, você precisa dos seguintes papéis:

• Usuário da Agent Platform (roles/aiplatform.user) no projeto.
• Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço usada para gerar tokens.
• A conta de serviço usada para gerar o token também precisa ter o papel de Usuário da Plataforma de Agentes (roles/aiplatform.user) no projeto.

Instalar bibliotecas

Instale o SDK da Agent Platform:

pip install google-cloud-agentplatform>=2.0.1

Criar uma instância da Agent Platform

Para usar o sandbox, primeiro crie uma instância da plataforma de agentes.

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

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud .
• LOCATION: a região da instância (como us-central1).

Para criptografar os dados do sandbox usando chaves de criptografia gerenciadas pelo cliente (CMEK), configure a CMEK ao criar a instância da plataforma de agentes. Para mais informações, consulte Configurar chaves de criptografia gerenciadas pelo cliente (CMEK).

Criar um modelo para o uso do computador

Crie um modelo de sandbox que será usado ao criar um sandbox de uso do computador.

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

Criar um sandbox de uso do computador

Crie um ambiente de sandbox com base no modelo.

Observação: por padrão, os sandboxes expiram após duas horas. É possível personalizar o ciclo de vida do sandbox definindo o campo ttl ao criar um sandbox.

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

Gerar um token de acesso

Para interagir com o sandbox, gere um token de acesso JSON Web Token (JWT) usando uma conta de serviço.

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

Substitua SERVICE_ACCOUNT_EMAIL pelo e-mail da conta de serviço que tem o papel de Criador de Token da Conta de Serviço.

Enviar uma solicitação para o sandbox

Envie uma solicitação GET HTTP ao servidor de API de sandbox para verificar o status.

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

Envie uma solicitação POST HTTP para navegar até uma 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
)

A tabela a seguir lista outros métodos e caminhos que podem ser enviados para o sandbox:

Método	Caminho	Descrição
GET	/	Recebe a verificação de integridade do sandbox
POST	/tabs	Cria uma nova guia e retorna os detalhes dela.
GET	/tabs	Lista detalhes de todas as guias abertas.
POST	/tabs/{tab_id}/activate	Define uma guia como ativa e a traz para o primeiro plano.
EXCLUIR	/tabs/{tab_id}	Fecha uma guia específica.
GET	/cdp_ws_endpoint	Retorna o caminho do endpoint do WebSocket do CDP.
POST	/cdp	Executa um comando do CDP na guia ativa.
POST	/cdps	Executa vários comandos do CDP na guia ativa.

Para mais informações sobre os comandos e o formato do CDP compatíveis, consulte o site do CDP.

Limpar

Para evitar cobranças, exclua os recursos criados neste guia de início rápido.

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

A seguir

• Visão geral dos sandboxes do Computer Use
• Configurar o VPC Service Controls
• Configurar chaves de criptografia gerenciadas pelo cliente (CMEK)