Diese Seite wurde von der Cloud Translation API übersetzt.

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:

Agent Engine-Instanz erstellen, um auf die Codeausführung zuzugreifen
Code Execution-Sandbox erstellen
(Optional) Sandboxes auflisten und abrufen
Code in einer Sandbox ausführen
Mehr Code in derselben Sandbox ausführen Der Status der Sandbox wird automatisch beibehalten.
Bereinigen

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

Hinweise

Richten Sie Ihr Projekt und Ihre Umgebung ein.

Projekt einrichten

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 für die Verwendung 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()

Agent Engine-Instanz erstellen

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

Sandbox erstellen

Erstellen einer 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 Programmiersprache und 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 Agent Engine-Instanz. Unterstützte Regionen für Vertex AI Agent Engine
AGENT_ENGINE_ID: Die ID für Ihre Agent Engine-Instanz.

Während der Vorschau werden nur LANGUAGE_PYTHON und LANGUAGE_JAVASCRIPT unterstützt. Wenn machine_config nicht angegeben ist, lautet 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

Alle Sandboxes auflisten, 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 (TTL) der Sandbox zurück.
Die Ausgabe erfolgt in Rohbyte.
Jede Anfrage oder Antwort kann bis zu 100 MB an Dateien enthalten.

Mehr Code in einer Sandbox ausführen

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

python_code = """
with open("output.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":"",
        "output_files":[{"content":"SGVsbG9Xb3JsZAo=", "name":"output.txt"}],
      }',
      mime_type='application/json',
    ),
  ]
)

Die Antwort enthält eine Datei, die decodiert werden muss. Hier ein Beispiel für die Dekodierung 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

So bereinigen Sie die in dieser Kurzanleitung erstellten Ressourcen: Löschen Sie Ihre Sandbox und Ihre 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.

Hinweise

Projekt einrichten

Erforderliche Rollen abrufen

Umgebung einrichten

Bibliotheken installieren

Bei Vertex AI authentifizieren

Lokale Shell

Colab

Agent Engine-Instanz erstellen

Sandbox erstellen

(Optional) Sandboxes auflisten und abrufen

Code in einer Sandbox ausführen

Mehr Code in einer Sandbox ausführen

Bereinigen

Nächste Schritte

Kurzanleitung zur Codeausführung