Guida rapida alla sandbox della shell

Una sandbox shell è un container Linux gestito e isolato collegato a un'istanza di Agent Platform. La sandbox esegue un comando shell inviato dall'agente e restituisce stdout, stderr e un codice di uscita. Non viene eseguito nulla sulla tua infrastruttura e il container viene eliminato quando viene eliminata la sandbox.

Utilizza una sandbox shell quando un agente deve eseguire comandi shell non attendibili o generati, installare pacchetti, manipolare file o utilizzare strumenti da riga di comando senza esporre il tuo ambiente.

Limitazioni

• send_command() e execute_code() non funzionano con le sandbox shell. Questi metodi sono destinati alle sandbox di esecuzione del codice e inviano payload Python, che il container shell non accetta. Utilizza /exec con le sandbox shell.

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, devi disporre del seguente ruolo:

• Agent Platform User (roles/aiplatform.user) nel progetto.

Installa le librerie

Installa l'SDK con il modulo Agent Platform:

pip install "google-cloud-aiplatform[agent_engines]"

Autentica

Per eseguire l'autenticazione con le credenziali predefinite dell'applicazione:

gcloud auth application-default login

Crea un'istanza di Agent Platform

Per utilizzare una sandbox shell, devi prima creare un'istanza di Agent Platform. Non è necessario eseguire il deployment di un agente per utilizzare una sandbox shell. Senza il deployment, la creazione di un'istanza di Agent Platform dovrebbe richiedere alcuni secondi.

import vertexai

client = vertexai.Client(project='PROJECT_ID', location='LOCATION')

agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name

Sostituisci quanto segue:

• PROJECT_ID: l' Google Cloud ID progetto.

• LOCATION: La Google Cloud regione per l'istanza di Agent Platform. Vedi Regioni supportate.

Crea una sandbox shell

Quando crei una sandbox, devi fornire almeno uno dei seguenti elementi:

• spec con un ambiente impostato (shell_environment)
• config.sandbox_environment_template (se non viene specificato, viene creato un modello predefinito. Per ulteriori informazioni, vedi Riutilizzare i modelli nelle sandbox)
• config.sandbox_environment_snapshot

L'esempio seguente passa shell_environment nella specifica della sandbox:

engine = (
    "projects/PROJECT_ID/locations/LOCATION"
    "/reasoningEngines/INSTANCE_ID"
)

operation = client.agent_engines.sandboxes.create(
    name=engine,
    spec={"shell_environment": {}},
    config={
        "display_name": "my-shell-sandbox",
        "wait_for_completion": True,
        "ttl": "3600s",
    },
)
sandbox = operation.response
print(sandbox.name, sandbox.state)

Quando la sandbox è pronta, viene stampata una risposta simile alla seguente:

projects/.../sandboxEnvironments/1035360621853409280 SandboxState.STATE_RUNNING

In genere, una sandbox raggiunge lo stato STATE_RUNNING in circa 20 secondi.

Esegui un comando

Per eseguire un comando shell nella sandbox, utilizza la funzione helper execute_bash(), che invia il comando al container:

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="echo hello && whoami && pwd",
)
print(result)

Il comando restituisce stdout, stderr, returncode e duration_ms:

{'stdout': 'hello\nappuser\n/workspace\n', 'stderr': '', 'returncode': 0, 'duration_ms': 8}

execute_bash() esegue l'autenticazione con le tue credenziali, quindi non hai bisogno di un account di servizio o di un JWT firmato.

(Facoltativo) Puoi impostare esplicitamente cwd per scegliere la directory di lavoro e timeout per limitare la durata di esecuzione del comando. In caso contrario, la sandbox utilizza i propri valori predefiniti (/workspace e il limite di tempo della sandbox):

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="pytest -q",
    cwd="/workspace/app",
    timeout=120,
)

Per scoprire se un comando non va a buon fine, esamina returncode e stderr:

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="ls /nope",
)
print(result)

{'stdout': '', 'stderr': "ls: cannot access '/nope': No such file or directory\n", 'returncode': 2, 'duration_ms': 5}

Quando utilizzi l'ambiente container, tieni presente quanto segue:

• I comandi vengono eseguiti come utente senza privilegi appuser; non esiste sudo.
• Ogni comando viene eseguito in una nuova shell, quindi cd e le variabili shell non vengono trasferite tra le chiamate. Concatenali in un unico comando o scrivi lo stato in un file in /workspace.
• L'accesso a internet in uscita è disattivato, a meno che il modello non lo consenta.

Libera spazio

Per eliminare la sandbox ed evitare addebiti, esegui il comando seguente:

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

Passaggi successivi

• Gestire le sandbox
• Gestire i modelli di sandbox