Guida rapida all'uso del computer

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Questa funzionalità fornisce un ambiente sandbox per gli agenti AI, pertanto si applicano i Termini specifici dei servizi "Servizi di AI agentica". Per utilizzare questa funzionalità, devi abilitare l'accesso completo alla rete per il tuo agente AI, quindi valuta le misure di salvaguardia applicabili (inclusa la supervisione umana) e le norme della tua organizzazione prima di farlo. Per le misure di salvaguardia integrate per l'utilizzo del computer, valuta lo strumento di utilizzo del computer della piattaforma dell'agente.

Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questa pagina mostra come effettuare chiamate API dirette per creare e utilizzare un ambiente sandbox per l'utilizzo del computer. In questa guida rapida, eseguirai le seguenti attività:

• Crea un'istanza di Agent Platform per accedere alla sandbox.
• Crea una sandbox Utilizzo del computer.
• Genera un token di accesso per la sandbox.
• Invia una richiesta per controllare lo stato.
• Libera spazio.

Prima di iniziare

Configura il progetto e l'ambiente.

Configura il progetto

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

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

Ottenere i ruoli richiesti

Per utilizzare la sandbox e generare token, devi disporre dei seguenti ruoli:

• Agent Platform User (roles/aiplatform.user) sul progetto.
• Creatore token service account (roles/iam.serviceAccountTokenCreator) sull'account di servizio utilizzato per la generazione dei token.
• Il account di servizio utilizzato per la generazione dei token deve disporre anche del ruolo Utente della piattaforma Agent (roles/aiplatform.user) nel progetto.

Installare le librerie

Installa l'SDK Agent Platform: posix-terminal pip install google-cloud-aiplatform>=1.112.0

Crea un'istanza di Agent Platform

Per utilizzare la sandbox, crea prima un'istanza di 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

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto Google Cloud .
• LOCATION: la regione dell'istanza (ad esempio us-central1).

Crea un modello per l'utilizzo del computer

Crea un modello di sandbox da utilizzare quando crei una sandbox Utilizzo del computer.

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

Crea una sandbox di utilizzo del computer

Crea un ambiente sandbox dal modello.

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

Generare un token di accesso

Per interagire con la sandbox, genera un token di accesso JWT (JSON Web Token) utilizzando un account di servizio.

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

Sostituisci SERVICE_ACCOUNT_EMAIL con l'email del service account che dispone del ruolo Creatore token service account.

Inviare una richiesta alla sandbox

Invia una richiesta GET HTTP al server API sandbox per verificarne lo stato.

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

Invia una richiesta POST HTTP per andare a una pagina specifica.

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
)

La tabella seguente elenca altri metodi e percorsi che puoi inviare alla tua sandbox:

Metodo	Percorso	Descrizione
GET	/	Ottiene il controllo di integrità della sandbox
POST	/tabs	Crea una nuova scheda e restituisce i relativi dettagli.
GET	/tabs	Elenca i dettagli di tutte le schede aperte.
POST	/tabs/{tab_id}/activate	Imposta una scheda come attiva e la porta in primo piano.
ELIMINA	/tabs/{tab_id}	Chiude una scheda specifica.
GET	/cdp_ws_endpoint	Restituisce il percorso dell'endpoint WebSocket CDP.
POST	/cdp	Esegue un comando CDP nella scheda attiva.
POST	/cdps	Esegue più comandi CDP nella scheda attiva.

Per ulteriori informazioni sui comandi e sul formato CDP supportati, visita il sito CDP.

Esegui la pulizia

Per evitare addebiti, elimina le risorse create in questa guida rapida.

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

Passaggi successivi

• Esplora gli snapshot per la gestione del ciclo di vita della sandbox.