Kurzanleitung zur Codeausführung

Auf dieser Seite wird gezeigt, wie Sie direkte API-Aufrufe an die Codeausführung von Vertex AI Agent Engine senden, um nicht vertrauenswürdigen Code in einer isolierten Sandbox-Umgebung auszuführen. Direkte API-Aufrufe sind nützlich, wenn Sie nicht möchten, dass das Agent-Framework Aufrufe für Sie orchestriert, oder wenn Sie die Codeausführung in andere Agent-Frameworks einbinden möchten.

In dieser Kurzanleitung führen Sie die folgenden Aufgaben aus:

Vertex AI Agent Engine-Instanz erstellen, um auf die Codeausführung zuzugreifen
Sandbox für die Codeausführung erstellen
Optional: Sandboxes auflisten und abrufen
Code in einer Sandbox ausführen
Weitere Codeausführung in derselben Sandbox Die Sandbox behält automatisch ihren Status bei.
Bereinigen

Weitere Informationen zur Verwendung der Codeausführung mit dem Agent Development Kit (ADK) finden Sie unter Tool zur Codeausführung mit Vertex AI Agent Engine.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Erforderliche Rollen abrufen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle „Vertex AI-Nutzer “ (roles/aiplatform.user) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwenden von Vertex AI Agent Engine benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Umgebung einrichten

In diesem Abschnitt wird davon ausgegangen, dass Sie eine Python-Entwicklungsumgebung eingerichtet haben, oder eine Laufzeit mit einer Python-Entwicklungsumgebung verwenden (z. B. Colab).

Bibliotheken installieren

Installieren Sie das Vertex AI SDK:

  pip install google-cloud-aiplatform>=1.112.0

Bei Vertex AI authentifizieren

So authentifizieren Sie sich:

Lokale Shell

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Vertex AI Agent Engine-Instanz erstellen

Um die Codeausführung zu verwenden, erstellen Sie zuerst eine Vertex AI Agent Engine-Instanz. Sie müssen keinen Agent bereitstellen, um die Codeausführung zu verwenden. Ohne Bereitstellung sollte das Erstellen einer Vertex AI Agent Engine-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 Vertex AI Agent Engine-Instanz. Informationen zu unterstützten Regionen für Vertex AI Agent Engine

Sandbox erstellen

Erstellen Sie eine Sandbox für die Codeausführung.

operation = client.agent_engines.sandboxes.create(
    spec={"code_execution_environment": {}},
    name=agent_engine_name,
    config=types.CreateAgentEngineSandboxConfig(display_name=SANDBOX_DISPLAY_NAME)
)

sandbox_name = operation.response.name

Ersetzen Sie Folgendes:

SANDBOX_DISPLAY_NAME: Der für Nutzer lesbare Name der Sandbox-Umgebung für die Codeausführung.

Sie können auch die Sandbox-Einstellungen wie die Programmiersprache und die Maschinenkonfiguration konfigurieren:

operation = client.agent_engines.sandboxes.create(
   spec={
       "code_execution_environment": {
            "code_language": "LANGUAGE_JAVASCRIPT",
            "machine_config": "MACHINE_CONFIG_VCPU4_RAM4GIB"
        }
   },
   name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID',
   config=types.CreateAgentEngineSandboxConfig(
       display_name=sandbox_display_name, ttl="3600s"),
)

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Google Cloud Projekt-ID
LOCATION: Die Google Cloud Region für Ihre Vertex AI Agent Engine Instanz. Informationen zu unterstützten Regionen für Vertex AI Agent Engine
AGENT_ENGINE_ID: Die ID für Ihre Vertex AI Agent Engine-Instanz.

Nur LANGUAGE_PYTHON und LANGUAGE_JAVASCRIPT werden unterstützt. Wenn machine_config nicht angegeben ist, ist die Standardkonfiguration 2 vCPUs und 1,5 GB RAM. Wenn Sie MACHINE_CONFIG_VCPU4_RAM4GIB angeben, hat die Sandbox 4 vCPUs und 4 GB RAM.

Optional: Sandboxes auflisten und abrufen

Listen Sie alle Sandboxes auf, die der angegebenen Agent Engine-Instanz zugeordnet sind:

sandboxes = client.agent_engines.sandboxes.list(name=agent_engine_name)

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Hier ist die Beispielausgabe:

SandboxEnvironment(
  create_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC)),
  display_name='test_sandbox',
  name=SANDBOX_NAME,
  spec=SandboxEnvironmentSpec(
    code_execution_environment=SandboxEnvironmentSpecCodeExecutionEnvironment()
  ),
  state=<State.STATE_RUNNING: 'STATE_RUNNING'>,
  update_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC))
)

So rufen Sie eine vorhandene Sandbox ab:

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

pprint.pprint(sandbox)

Hier ist die Beispielausgabe:

SandboxEnvironment(
  create_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC)),
  display_name='test_sandbox',
  name=SANDBOX_NAME,
  spec=SandboxEnvironmentSpec(
    code_execution_environment=SandboxEnvironmentSpecCodeExecutionEnvironment()
  ),
  state=<State.STATE_RUNNING: 'STATE_RUNNING'>,
  update_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC))
)

Code in einer Sandbox ausführen

Rufen Sie execute_code auf, um Code auszuführen:

my_code = """
with open("input.txt", "r") as input:
   with open("output.txt", "w") as output:
       for line in input:
           print(line)
           output.write(line)
"""
input_data = {
   "code": my_code,
   "files": [{
       "name": "input.txt",
       "content": b"Hello, world!"
   }]
}


response = client.agent_engines.sandboxes.execute_code(
   name = sandbox_name,
   input_data = input_data
)

Hier ist die Beispielausgabe:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
      }',
      mime_type='application/json',
    ),
    chunk(
data=b"hello world!",
        mime_type="text/plain"
        attributes={
          "file_name":"output.txt"
        }
    )
  ]
)

Wichtige Hinweise:

execute_code setzt die Gültigkeitsdauer (Time-to-Live, TTL) der Sandbox zurück.
Die Ausgabe erfolgt in Rohbytes.
Jede Anfrage oder Antwort kann bis zu 100 MB an Dateien enthalten.

Weitere Codeausführung in einer Sandbox

Um zu zeigen, dass die Sandbox ihren Status beibehält, führen Sie weiteren Code in derselben Sandbox aus:

python_code = """
with open("output2.txt", "w") as output:
    for line in lines:
        output.write(line + "World\n")
"""
input_data = {"code": python_code}

response = client.agent_engines.sandboxes.execute_code(
    name = sandbox_name,
    input_data = input_data
)

pprint.pprint(response)

Hier ist die Beispielausgabe:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
      }',
      mime_type='application/json',
    ),
    chunk(
      data=b"hello world!",
        mime_type="text/plain"
        attributes={
          "file_name":"output2.txt"
        }
    )

  ]
)

Die Antwort enthält eine Datei, die decodiert werden muss. Hier ein Beispiel für das Decodieren der Ausgabe:

import base64
import json

if response.outputs[0].mime_type=="application/json":
    json_output = json.loads(response.outputs[0].data.decode("utf-8"))
    output_file_content = json_output.get("output_files")[0].get("content")
    print(output_file_content.b64decode(output_file_content))

Hier ist die Beispielausgabe:

b'HelloWorld\n'

Bereinigen

Wenn Sie die in dieser Kurzanleitung erstellten Ressourcen bereinigen möchten, löschen Sie Ihre Sandbox und die Vertex AI Agent Engine-Instanz.

client.agent_engines.sandboxes.delete(name=sandbox_name)
agent_engine.delete()

Nächste Schritte

Fehlerbehebung bei der Codeausführung

Kurzanleitung zur Codeausführung Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Projekt einrichten

Erforderliche Rollen abrufen

Umgebung einrichten

Bibliotheken installieren

Bei Vertex AI authentifizieren

Lokale Shell

Colab

Vertex AI Agent Engine-Instanz erstellen

Sandbox erstellen

Optional: Sandboxes auflisten und abrufen

Code in einer Sandbox ausführen

Weitere Codeausführung in einer Sandbox

Bereinigen

Nächste Schritte

Kurzanleitung zur Codeausführung