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 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 Platform-Instanz erstellen, um auf die Codeausführung zuzugreifen
  • Sandbox für Codeausführung 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 Codeausführungstool.

Hinweis

Richten Sie Ihr Projekt und Ihre Umgebung ein.

Projekt einrichten

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit 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.

  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform 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

  5. 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

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Gemini Enterprise Agent Platform 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

    8.

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 verwenden (z. B. Colab).

Bibliotheken installieren

Installieren Sie das Vertex AI SDK:

  pip install google-cloud-aiplatform>=1.112.0

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

Um die Codeausführung zu verwenden, müssen Sie zuerst eine Agent Platform-Instanz erstellen. Sie müssen keinen Agent bereitstellen, um die Codeausführung 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. Unterstützte Regionen

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 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/INSTANCE_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 Platform-Instanz. Unterstützte Regionen

  • INSTANCE_ID: Die ID für Ihre Agent Platform-Instanz.

Es 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("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 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

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

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

Nächste Schritte