Guida rapida all'uso del computer

Questa pagina mostra come effettuare chiamate API dirette per creare e utilizzare un ambiente sandbox per l'utilizzo del computer. In questa guida rapida imparerai a:

• Crea un'istanza di Agent Platform per accedere alla sandbox.
• Crea una sandbox di Computer Use.
• Genera un token di accesso per la sandbox.
• Invia una richiesta per controllare lo stato.
• Esegui la pulizia delle risorse.

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

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

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) sull'account di servizio utilizzato per la generazione dei token.
• Il account di servizio utilizzato per la generazione dei token deve avere anche il ruolo Agent Platform User (roles/aiplatform.user) nel progetto.

Installa le librerie

Installa l'SDK Agent Platform:

pip install google-cloud-agentplatform>=2.0.1

Crea un'istanza di Agent Platform

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

Sostituisci quanto segue:

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

Per criptare i dati della sandbox utilizzando le chiavi di crittografia gestite dal cliente (CMEK), devi configurare CMEK quando crei l'istanza della piattaforma dell'agente. Per saperne di più, consulta Configura le chiavi di crittografia gestite dal cliente (CMEK).

Crea un template per Computer Use

Crea un template della sandbox che utilizzerai quando crei una sandbox per l'utilizzo del computer.

# 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 sandbox per l'utilizzo del computer

Crea un ambiente sandbox dal template.

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.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 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.sandboxes.generate_access_token(
    service_account_email=service_account_email,
)

Sostituisci SERVICE_ACCOUNT_EMAIL con l'indirizzo email del service account con 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.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.sandboxes.send_command(
    http_method="POST",
    path="cdp",
    access_token=access_token,
    request_dict=data,
    sandbox_environment=sandbox
)

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

Metodo	Percorso	Descrizione
GET	/	Recupera 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 nella scheda attiva.

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

Esegui la pulizia

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

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

Passaggi successivi

• Panoramica delle sandbox per l'utilizzo del computer
• Configura i Controlli di servizio VPC
• Configura le chiavi di crittografia gestite dal cliente (CMEK)