Shell-Sandbox – Schnellstart

Eine Shell-Sandbox ist ein verwalteter, isolierter Linux-Container, der an eine Agent Platform-Instanz angehängt ist. In der Sandbox wird ein Shell-Befehl ausgeführt, der von Ihrem Agent gesendet wurde, und es werden „stdout“, „stderr“ und ein Exit-Code zurückgegeben. Es wird nichts in Ihrer eigenen Infrastruktur ausgeführt und der Container wird zerstört, wenn die Sandbox gelöscht wird.

Verwenden Sie eine Shell-Sandbox, wenn ein Agent nicht vertrauenswürdige oder generierte Shell-Befehle ausführen, Pakete installieren, Dateien bearbeiten oder Befehlszeilentools verwenden muss, ohne Ihre Umgebung preiszugeben.

Beschränkungen

• send_command() und execute_code() funktionieren nicht mit Shell-Sandboxes. Diese Methoden sind für Code Execution-Sandboxes vorgesehen und senden Python-Nutzlasten, die der Shell-Container nicht akzeptiert. Verwenden Sie /exec mit Shell-Sandboxes.

Hinweis

Richten Sie Ihr Projekt und Ihre Umgebung ein.

Projekt einrichten

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Konto bei Google Cloudhaben, erstellen Sie ein Konto, um die Leistung unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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

Erforderliche Rollen abrufen

Für die Verwendung der Sandbox benötigen Sie die folgende Rolle:

• Agent Platform User (roles/aiplatform.user) für das Projekt.

Bibliotheken installieren

Installieren Sie das SDK mit dem Agent Platform-Modul:

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

Authentifizieren

So authentifizieren Sie sich mit Standardanmeldedaten für Anwendungen:

gcloud auth application-default login

Agent Platform-Instanz erstellen

Wenn Sie eine Shell-Sandbox verwenden möchten, erstellen Sie zuerst eine Agent Platform-Instanz. Sie müssen keinen Agent bereitstellen, um eine Shell-Sandbox zu verwenden. Ohne Bereitstellung sollte das Erstellen einer Agent Platform-Instanz nur wenige Sekunden dauern.

import vertexai

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

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

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Google Cloud Projekt-ID

• LOCATION: Die Google Cloud Region für Ihre Agent Platform-Instanz. Siehe Unterstützte Regionen.

Shell-Sandbox erstellen

Sie müssen beim Erstellen einer Sandbox mindestens eines der folgenden Elemente angeben:

• spec mit einer festgelegten Umgebung (shell_environment)
• config.sandbox_environment_template (wenn keine Angabe erfolgt, wird eine Standardvorlage erstellt. Weitere Informationen finden Sie unter Vorlagen in Sandboxes wiederverwenden.)
• config.sandbox_environment_snapshot

Im folgenden Beispiel wird shell_environment in der Sandbox-Spezifikation übergeben:

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)

Wenn die Sandbox bereit ist, wird eine Antwort ähnlich der folgenden ausgegeben:

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

Eine Sandbox erreicht in der Regel nach etwa 20 Sekunden den Status STATE_RUNNING.

Befehl ausführen

Verwenden Sie die Hilfsfunktion execute_bash(), um einen Shell-Befehl in der Sandbox auszuführen. Dadurch wird der Befehl an den Container gesendet:

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

Der Befehl gibt stdout, stderr, returncode und duration_ms zurück:

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

execute_bash() authentifiziert sich mit Ihren eigenen Anmeldedaten. Sie benötigen also kein Dienstkonto oder signiertes JWT.

Optional können Sie cwd explizit festlegen, um das Arbeitsverzeichnis auszuwählen, und timeout, um die maximale Ausführungszeit des Befehls zu begrenzen. Andernfalls verwendet die Sandbox ihre eigenen Standardwerte (/workspace und das Zeitlimit der Sandbox):

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

Prüfen Sie returncode und stderr, um festzustellen, ob ein Befehl fehlgeschlagen ist:

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}

Beachten Sie bei Verwendung der Containerumgebung Folgendes:

• Befehle werden als nicht privilegierter Nutzer appuser ausgeführt. Es gibt kein sudo.
• Jeder Befehl wird in einer neuen Shell ausgeführt. Daher werden cd und Shell-Variablen nicht zwischen Aufrufen übertragen. Verketten Sie sie in einem Befehl oder schreiben Sie den Status in eine Datei unter /workspace.
• Der ausgehende Internetzugriff ist deaktiviert, es sei denn, er ist in der Vorlage aktiviert.

Bereinigen

Führen Sie Folgendes aus, um die Sandbox zu löschen und weitere Kosten zu vermeiden:

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

Nächste Schritte

• Sandboxes verwalten
• Sandbox-Vorlagen verwalten