Gestisci sandbox

Questa pagina mostra come gestire il ciclo di vita degli ambienti sandbox utilizzando l'SDK Python. Puoi elencare le sandbox esistenti, visualizzarne i dettagli, metterle in pausa e riprenderle o eliminarle quando non sono più necessarie.

Prima di iniziare

Per gestire le sandbox, devi disporre dei seguenti ruoli nel progetto:

  • Agent Platform User (roles/aiplatform.user)

Gestisci le sandbox

Puoi elencare, visualizzare i dettagli, mettere in pausa, riprendere ed eliminare gli ambienti sandbox associati a un'istanza Agent Platform. La messa in pausa e il ripristino ti consentono di annullare la pianificazione delle risorse di computing per le sandbox inattive e di riportarle online in un secondo momento senza perdere lo stato del file system o l'identità della connessione. Per modificare la configurazione di una sandbox esistente, devi eliminarla e crearne una nuova.

Elenco sandbox

Per elencare tutte le sandbox associate a un'istanza di Agent Platform:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione Google Cloud dell'istanza di Agent Platform. Consulta Regioni supportate.
  • INSTANCE_ID: l'ID istanza della piattaforma agentica.

Visualizza i dettagli della sandbox

Per visualizzare la configurazione e lo stato di una sandbox specifica:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione Google Cloud dell'istanza di Agent Platform. Consulta Regioni supportate.
  • INSTANCE_ID: l'ID istanza di Agent Platform che contiene la tua sandbox.
  • SANDBOX_ID: l'ID della sandbox esistente.

L'output include dettagli come l'ora di creazione, lo stato (ad esempio STATE_RUNNING) e la specifica della sandbox.

Metti in pausa una sandbox

La messa in pausa di una sandbox rilascia le relative risorse di computing, preservando lo stato del disco e i metadati di connessione. Le sandbox in pausa costano molto meno di quelle in esecuzione e possono essere riprese in pochi secondi. Utilizza la pausa quando una sandbox è inattiva per un periodo prolungato, ma vuoi conservare lo stato della sessione e l'identità della connessione per un utilizzo successivo.

Le sandbox in pausa hanno le seguenti caratteristiche:

  • Conservare l'ID sandbox, i metadati di connessione e qualsiasi endpoint Private Service Connect.
  • Conserva lo stato del file system all'interno del container al momento della pausa.
  • Transizione a STATE_PAUSED. Le richieste al loro endpoint del piano dati restituiscono errori finché non riprendi l'attività.

Per mettere in pausa una sandbox in esecuzione, esegui questo codice:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione Google Cloud dell'istanza di Agent Platform. Consulta Regioni supportate.
  • INSTANCE_ID: l'ID istanza di Agent Platform che contiene la tua sandbox.
  • SANDBOX_ID: l'ID della sandbox esistente.

Riprendi una sandbox

Il ripristino di una sandbox in pausa riporta online il relativo computing. La sandbox conserva lo stesso ID, lo stesso endpoint di connessione (incluso qualsiasi collegamento al servizio Private Service Connect) e lo stesso stato del file system che aveva al momento della pausa. Le richieste del piano dati possono essere inviate nuovamente alla sandbox non appena l'operazione di ripresa viene completata.

Per riprendere una sandbox in pausa, esegui questo codice:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione Google Cloud dell'istanza di Agent Platform. Consulta Regioni supportate.
  • INSTANCE_ID: l'ID istanza di Agent Platform che contiene la tua sandbox.
  • SANDBOX_ID: l'ID della sandbox in pausa.

Elimina una sandbox

Per eliminare esplicitamente un ambiente sandbox e liberare risorse:

client.sandboxes.delete(name=sandbox_name)
print("Sandbox deleted.")

Audit logging e monitoraggio

Quando gestisci ed esegui comandi nelle sandbox, Agent Platform registra l'attività a livello di API in Cloud Audit Logs con il nome del servizio aiplatform.googleapis.com e il tipo di risorsa monitorata audited_resource:

  • Log di attività di amministrazione (ADMIN_WRITE): registrati automaticamente per le mutazioni del ciclo di vita del control plane, tra cui CreateSandboxEnvironment, PauseSandboxEnvironment, ResumeSandboxEnvironment, SnapshotSandboxEnvironment e DeleteSandboxEnvironment (richiedono autorizzazioni IAM aiplatform.sandboxEnvironments.*).
  • Log di accesso ai dati (ADMIN_READ): registrati quando sono abilitati per le operazioni di lettura dei metadati, tra cui GetSandboxEnvironment e ListSandboxEnvironments.
  • Log di accesso ai dati (DATA_WRITE): registrati quando sono abilitati per le chiamate di esecuzione dei comandi e di autorizzazione di accesso del piano dati, tra cui ExecuteSandboxEnvironment, BidiExecuteSandboxEnvironment, AuthorizeSandboxEnvironmentAccess e ExecuteCode. Per le risorse protette dai Controlli di servizio VPC, i payload di richiesta e risposta vengono omessi dagli audit log.

Tieni presente i seguenti limiti di osservabilità e rilevamento delle minacce:

  • Attività di processo e stream nel container: Cloud Audit Logs registra la richiesta API che avvia l'esecuzione del comando o autorizza una connessione, ma non registra i singoli processi secondari generati all'interno del container, le modifiche al file system o i frame interattivi successivi inviati tramite una sessione WebSocket, Chrome DevTools Protocol (CDP) o PTY aperta.
  • Logging dei container stdout e stderr: la raccolta automatica di Cloud Logging per Agent Runtime (come reasoning_engine_stdout e reasoning_engine_stderr) si applica solo all'istanza ReasoningEngine principale e non raccoglie automaticamente i log dalle risorse secondarie della sandbox. L'output comando (stdout, stderr e codici di uscita) viene restituito nella risposta di esecuzione all'agente parent, dove puoi ispezionare e scrivere voci strutturate in Cloud Logging.
  • Rilevamento delle minacce e ispezione della rete: le sandbox applicano il contenimento tramite l'isolamento del kernel gVisor e un'identità non privilegiata all'interno della sandbox senza credenziali Google Cloud ambientali. Per monitorare comportamenti anomali o traffico in uscita dalla rete non autorizzato, combina gli audit log di DATA_WRITE con il rilevamento di anomalie dell'agente sull'agente parent e instrada il traffico in uscita dalla sandbox tramite un'interfaccia Private Service Connect con i log di flusso VPC, il logging delle regole di Cloud Next Generation Firewall (Cloud NGFW) e l'ispezione di Secure Web Proxy. Per maggiori dettagli, consulta Confini di sicurezza, identità e osservabilità.