Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Kurzanleitung zur Codeausführung

Auf dieser Seite wird gezeigt, wie Sie direkte API-Aufrufe an die Codeausführung 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 Agenten-Framework Aufrufe für Sie orchestriert, oder wenn Sie die Codeausführung in andere Agenten-Frameworks einbinden möchten.

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

Agent Platform-Instanz erstellen, um auf die Codeausführung zuzugreifen
Sandbox für die Code-Ausführung erstellen
(Optional) Sandboxes auflisten und abrufen
Code in einer Sandbox ausführen
Führen Sie mehr Code in derselben Sandbox aus. Der Status der Sandbox wird automatisch beibehalten.
Bereinigen

Weitere Informationen zur Verwendung der Code-Ausführung mit dem Agent Development Kit (ADK) finden Sie unter Code-Ausführungstool.

Hinweis

Richten Sie Ihr Projekt und Ihre Umgebung ein.

Projekt einrichten

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, if it is not already enabled.
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

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Agent Platform User (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 (z. B. Colab) verwenden.

Bibliotheken installieren

Installieren Sie das Agent Platform SDK:

  pip install google-cloud-agentplatform>=2.0.1

Authentifizieren

So authentifizieren Sie sich:

Lokale Shell

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Agent Platform-Instanz erstellen

Wenn Sie die Code-Ausführung verwenden möchten, müssen Sie zuerst eine Agent Platform-Instanz erstellen. Sie müssen keinen Agenten bereitstellen, um die Codeausführung zu verwenden. Ohne Bereitstellung sollte das Erstellen einer Agent Platform-Instanz nur wenige Sekunden dauern.

import agentplatform
from agentplatform import types

client = agentplatform.Client(project=PROJECT_ID, location=LOCATION)

remote_agent = client.runtimes.create()
remote_agent_name = remote_agent.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.

Sandbox erstellen

Sandbox für die Codeausführung erstellen

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

sandbox_name = operation.response.name

Ersetzen Sie Folgendes:

SANDBOX_DISPLAY_NAME: der menschenlesbare Name der Sandbox-Umgebung für die Codeausführung.

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

operation = client.sandboxes.create(
   spec={
       "code_execution_environment": {
            "code_language": "LANGUAGE_JAVASCRIPT",
            "machine_config": "MACHINE_CONFIG_VCPU4_RAM4GIB"
        }
   },
   name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID',
   config=types.CreateRuntimeSandboxConfig(
       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 Platform-Instanz. Siehe Unterstützte Regionen.
INSTANCE_ID: Die ID Ihrer Agent Platform-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.sandboxes.list(name=remote_agent_name)

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Hier sehen Sie 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.sandboxes.get(name=sandbox_name)

pprint.pprint(sandbox)

Hier sehen Sie 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.sandboxes.execute_code(
   name = sandbox_name,
   input_data = input_data
)

Hier sehen Sie 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

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

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.sandboxes.execute_code(
    name = sandbox_name,
    input_data = input_data
)

pprint.pprint(response)

Hier sehen Sie 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 die Decodierung 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 sehen Sie die Beispielausgabe:

b'HelloWorld\n'

Bereinigen

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

client.sandboxes.delete(name=sandbox_name)
remote_agent.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

Authentifizieren

Lokale Shell

Colab

Agent Platform-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