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

Visualizar

Este recurso está sujeito aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Esse recurso oferece um ambiente de sandbox para agentes de IA. Portanto, os "Termos Específicos de Serviço de Serviços de IA Agêntica" se aplicam. Para usar este recurso, você precisa ativar o acesso total à rede para o agente de IA. Considere as proteções aplicáveis (incluindo a supervisão humana) e as políticas da sua organização antes de fazer isso. Para proteções de uso de computador integradas, considere a Agent Platform Ferramenta de Uso do Computador.

Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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

• Criar uma instância da Agent Platform para acessar a sandbox.
• Criar uma sandbox de uso de computador.
• Gerar um token de acesso para a sandbox.
• Enviar 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 Google Cloud conta do. Se você começou a usar o Google Cloud, 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.

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 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.

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 a 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 geração de token.
• A conta de serviço usada para geração de token também precisa ter o papel Usuário da Agent Platform (roles/aiplatform.user) no projeto.

Instalar bibliotecas

Instale o SDK da Agent Platform: posix-terminal pip install google-cloud-aiplatform>=1.112.0

Criar uma instância da Agent Platform

Para usar a sandbox, primeiro crie uma instância da 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

Substitua:

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

Criar um modelo para uso de computador

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

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

Criar uma sandbox de uso de computador

Crie um ambiente de sandbox com base no modelo.

Observação: por padrão, as sandboxes expiram após duas horas. É possível personalizar o tempo de vida da sandbox definindo o campo ttl ao criar uma.

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

Gerar um token de acesso

Para interagir com a 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.agent_engines.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 Criador de token da conta de serviço.

Enviar uma solicitação para a sandbox

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

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

Envie uma solicitação HTTP POST para navegar até uma página específica.

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
)

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

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

Para mais informações sobre os comandos e o formato do CDP com suporte, consulte o site do CDP.

Limpar

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

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

A seguir

• Confira os snapshots para o gerenciamento do ciclo de vida da sandbox.