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 AI agentici". Per utilizzare questa funzionalità, dovrai abilitare l'accesso completo alla rete per il tuo agente AI, quindi prima di farlo valuta le misure di sicurezza applicabili (inclusa la supervisione umana) e le norme della tua organizzazione. Per le misure di sicurezza integrate per l'utilizzo del computer, prendi in considerazione lo strumento di utilizzo del computer di Agent Platform .

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 di utilizzo del computer. In questa guida rapida, svolgi le seguenti attività:

• Crea un'istanza di Agent Platform per accedere alla sandbox.
• Crea una sandbox di 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 Google Cloud account. 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

Ottieni 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 account di servizio (roles/iam.serviceAccountTokenCreator) sul service account utilizzato per la generazione dei token.
• Il account di servizio utilizzato per la generazione dei token deve disporre anche del ruolo Agent Platform User (roles/aiplatform.user) sul progetto.

Installa 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' Google Cloud ID progetto.
• LOCATION: la regione per l'istanza (ad esempio us-central1).

Crea un modello per l'utilizzo del computer

Crea un modello di sandbox da utilizzare quando crei una sandbox di 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.

Nota: per impostazione predefinita, le sandbox scadono dopo 2 ore. Puoi personalizzare la durata della sandbox impostando il campo ttl durante la creazione di una 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.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}")

Genera un token di accesso

Per interagire con la sandbox, genera un token di accesso JSON Web Token (JWT) 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'indirizzo email del service account che ha il ruolo Creatore token account di servizio.

Invia una richiesta alla sandbox

Invia una richiesta GET HTTP al server API della 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 HTTP POST per passare 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 sandbox:

Metodo	Percorso	Descrizione
GET	/	Ottiene il controllo di integrità della sandbox
POST	/tabs	Crea una nuova scheda e ne restituisce i 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 sulla scheda attiva.
POST	/cdps	Esegue più comandi CDP sulla scheda attiva.

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

Libera spazio

Per evitare che ti vengano addebitati dei costi, elimina le risorse create in questa guida rapida.

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

Passaggi successivi

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