KI-Agenten bereitstellen

Wenn Sie einen KI-Agenten in der Agent Runtime bereitstellen, ist er remote verfügbar, um Anfragen zu verarbeiten. In diesem Dokument werden die Möglichkeiten zum Bereitstellen eines KI-Agenten basierend auf Ihrem Entwicklungsworkflow erläutert: über ein Ausführungsobjekt, lokale Quelldateien, ein Dockerfile, ein in Artifact Registry gehostetes Container-Image oder direkt über ein verbundenes Git-Repository.

Wenn Sie einen KI-Agenten in der Agent Runtime bereitstellen möchten, können Sie zwischen den folgenden Methoden wählen:

Developer Connect

Empfohlen für Projekte, die in einem Git-Repository verwaltet werden, das über Developer Connect verknüpft ist. Diese Methode optimiert die Bereitstellung von KI-Agenten direkt aus Ihrem Quellcode und unterstützt nativ die Versionsverwaltung, die Zusammenarbeit im Team und CI/CD-Pipelines. Bevor Sie diese Methode verwenden, müssen Sie Ihren Git-Repository-Link einrichten. Folgen Sie dazu der Anleitung unter Git-Repository-Link von Developer Connect einrichten.

Diese Bereitstellungsmethode kann nur mit Python verwendet werden.

Quelldateien

Gut geeignet für automatisierte Workflows wie CI/CD-Pipelines und Infrastructure as Code-Tools wie Terraform, die vollständig deklarative und automatisierte Bereitstellungen ermöglichen. Der Agent wird direkt aus dem lokalen Quellcode bereitgestellt und erfordert keinen Cloud Storage-Bucket.

Diese Bereitstellungsmethode kann nur mit Python verwendet werden.

Dockerfile

Ähnlich wie bei der Bereitstellung aus Quelldateien. Sie stellen Ihren Agenten direkt aus lokalem Quellcode bereit, ohne einen Cloud Storage-Bucket zu benötigen. Diese Methode ist geeignet, wenn Sie den bereitgestellten API-Server definieren und steuern müssen. Der bereitgestellte Container muss dem Laufzeitvertrag entsprechen.

Sie können diese Bereitstellungsmethode mit jeder Sprache verwenden. In den Beispielen auf dieser Seite wird Python verwendet.

Container-Image

Ähnlich wie bei der Bereitstellung aus einem Dockerfile. Sie stellen ein in Artifact Registry gehostetes Container-Image bereit. Verwenden Sie diese Methode, wenn Sie die Kontrolle über den Build-Prozess für das Container-Image und eine geringere Bereitstellungslatenz benötigen. Das Container-Image muss dem Laufzeitvertrag entsprechen.

Sie können diese Bereitstellungsmethode mit jeder Sprache verwenden. In den Beispielen auf dieser Seite wird Python verwendet.

Agent Platform SDK

Ideal für die interaktive Entwicklung in Umgebungen wie Colab, da local_agent-Objekte im Arbeitsspeicher bereitgestellt werden können. Diese Methode eignet sich am besten für Agenten mit Strukturen, die keine komplexen, nicht serialisierbaren Komponenten enthalten.

So gehts:

  1. Voraussetzungen erfüllen
  2. Optional: Agent für die Bereitstellung konfigurieren
  3. Gemini Enterprise Agent Platform-Instanz erstellen
  4. Optional: Agenten-Ressourcen-ID abrufen
  5. Optional: Unterstützte Vorgänge auflisten
  6. Optional: Berechtigungen für den bereitgestellten Agenten gewähren

Vorbereitung

Bevor Sie einen Agenten bereitstellen, müssen Sie die folgenden Aufgaben ausführen:

  1. Umgebung einrichten
  2. Agent erstellen

Optional: KI-Agenten für die Bereitstellung konfigurieren

Sie können optionale Konfigurationen für Ihren Agenten vornehmen. In den Beispielen in diesem Abschnitt wird Python verwendet.

Agent Platform-Instanz erstellen

In diesem Abschnitt wird beschrieben, wie Sie eine Agent Platform-Instanz zum Bereitstellen eines KI-Agenten erstellen. Sie können zwischen den folgenden Methoden wählen:

Developer Connect

Wenn Sie Developer Connect auf der Agent Platform bereitstellen möchten, verwenden Sie client.runtimes.create und geben Sie developer_connect_source, entrypoint_module und entrypoint_object im Konfigurationsverzeichnis zusammen mit anderen optionalen Konfigurationen an. Mit dieser Methode können Sie Code direkt aus einem verbundenen Git-Repository bereitstellen.

Diese Bereitstellungsmethode kann nur mit Python verwendet werden. 

remote_agent = client.runtimes.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Die Parameter für die Developer Connect-Bereitstellung sind:

  • developer_connect_source (dict): Die Konfiguration zum Abrufen des Quellcodes. Weitere Informationen finden Sie unter Git-Repository-Link von Developer Connect einrichten.
    • git_repository_link (str): Der Ressourcenname des Git-Repository-Links von Developer Connect.
    • revision (str): Die abzurufende Überarbeitung (Zweig, Tag oder Commit-SHA).
    • dir (str): Das Stammverzeichnis des Agent-Codes im Repository.
  • entrypoint_module (str): Der Name des Python-Moduls, das den Agent-Einstiegspunkt enthält, relativ zum in developer_connect_source.dir angegebenen Verzeichnis.
  • entrypoint_object (str): Der Name des aufrufbaren Objekts innerhalb der entrypoint_module, die die Agent-Anwendung darstellt (z. B. root_agent).
  • requirements_file (str): Optional: Der Pfad zu einer pip-Anforderungsdatei relativ zum Quellstammverzeichnis. Die Standardeinstellung ist requirements.txt.

Die Bereitstellung dauert einige Minuten. Währenddessen werden im Hintergrund die folgenden Schritte ausgeführt:

  1. Der Agent Runtime-Dienst ruft den Quellcode aus der angegebenen Git-Repository-Version ab.
  2. Der Dienst installiert Abhängigkeiten aus requirements_file (falls vorhanden).
  3. Der Dienst startet die Agent-Anwendung mit den angegebenen entrypoint_module und entrypoint_object.

Die Bereitstellungslatenz hängt von der Gesamtzeit ab, die für die Installation der erforderlichen Pakete benötigt wird. Nach der Bereitstellung entspricht remote_agent einer Instanz von local_agent, die auf der Agent Platform ausgeführt wird und abgefragt oder gelöscht werden kann.

Das Objekt remote_agent entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Quelldateien

Wenn Sie Quelldateien auf der Agent Platform bereitstellen möchten, verwenden Sie client.runtimes.create und geben Sie source_packages, entrypoint_module, entrypoint_object und class_methods im Konfigurationsverzeichnis zusammen mit anderen optionalen Konfigurationen an. Bei dieser Methode müssen Sie kein Agent-Objekt oder Cloud Storage-Bucket übergeben.

Diese Bereitstellungsmethode kann nur mit Python verwendet werden. 

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.runtimes.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

Die Parameter für die Bereitstellung von Inline-Quellen sind:

  • source_packages (list[str]): Eine Liste lokaler Datei- oder Verzeichnispfade, die in die Bereitstellung einbezogen werden sollen. Die Gesamtgröße der Dateien und Verzeichnisse in source_packages darf 8 MB nicht überschreiten.
  • entrypoint_module (str): Der vollständig qualifizierte Python-Modulname, der den Agent-Einstiegspunkt enthält (z. B. agent_dir.agent).
  • entrypoint_object (str): Der Name des aufrufbaren Objekts innerhalb der entrypoint_module, die die Agent-Anwendung darstellt (z. B. root_agent).
  • class_methods (list[dict]): Eine Liste von Wörterbüchern, die die offengelegten Methoden des Agenten definieren. Jedes Wörterbuch enthält die Felder name, api_mode und optional parameters. Weitere Informationen zu den Methoden für einen benutzerdefinierten KI-Agenten finden Sie unter Unterstützte Vorgänge auflisten.

    Beispiel:

    class_methods = [
    {
        "name": "method_name",
        "api_mode": "",  # Options: "", "async", "async_stream", "stream", "bidi_stream"
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "Description of param1"},
                "param2": {"type": "integer"}
            },
            "required": ["param1"]
        }
    }
]
  • requirements_file (str): Optional: Der Pfad zu einer pip-Anforderungsdatei innerhalb der in source_packages angegebenen Pfade. Standardmäßig ist requirements.txt im Stammverzeichnis der gepackten Quelle festgelegt.

Die Bereitstellung dauert einige Minuten. Währenddessen werden im Hintergrund die folgenden Schritte ausgeführt:

  1. Das Agent Platform SDK erstellt ein tar.gz-Archiv der in source_packages angegebenen Pfade.
  2. Dieses Archiv wird codiert und direkt an die Agent Platform API gesendet.
  3. Der Agent Runtime-Dienst empfängt das Archiv, extrahiert es, installiert Abhängigkeiten aus requirements_file (falls vorhanden) und startet die Agent-Anwendung mit den angegebenen entrypoint_module und entrypoint_object.

Die Bereitstellungslatenz hängt von der Gesamtzeit ab, die für die Installation der erforderlichen Pakete benötigt wird. Nach der Bereitstellung entspricht remote_agent einer Instanz von local_agent, die auf der Agent Platform ausgeführt wird und abgefragt oder gelöscht werden kann.

Das Objekt remote_agent entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Dockerfile

Die Bereitstellung aus einem Dockerfile auf der Agent-Plattform erfolgt ähnlich wie die Bereitstellung aus Quelldateien. Der einzige Unterschied besteht darin, dass Sie in der Konfiguration image_spec anstelle von entrypoint_module, entrypoint_object und requirements_file verwenden. Der aus dem Dockerfile erstellte Container muss dem Laufzeitvertrag entsprechen.

Sie können diese Bereitstellungsmethode mit jeder Sprache verwenden. Im Beispiel in diesem Abschnitt wird Python verwendet.

Im Folgenden finden Sie ein Beispiel für die Bereitstellung eines KI-Agenten mit einem Dockerfile:

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.runtimes.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

Die Bereitstellungslatenz hängt von der Gesamtzeit ab, die für die Installation der erforderlichen Pakete benötigt wird. Nach der Bereitstellung entspricht remote_agent einer Instanz von local_agent, die auf der Agent Platform ausgeführt wird und abgefragt oder gelöscht werden kann.

Das Objekt remote_agent entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Container-Image

Wenn Sie die Bereitstellung über ein Container-Image vornehmen möchten, folgen Sie zuerst der Einrichtungsanleitung für Eigene Container verwenden. Achten Sie darauf, eine Version von google-cloud-aiplatform zu installieren, die >=1.144 erfüllt. Das Container-Image muss dem Laufzeitvertrag entsprechen.

Sie können diese Bereitstellungsmethode mit jeder Sprache verwenden. Im Beispiel in diesem Abschnitt wird Python verwendet.

Im Folgenden finden Sie ein Beispiel für die Bereitstellung eines Agents mit einem Container-Image:

remote_agent = client.runtimes.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

Dabei entspricht CONTAINER_IMAGE_URI dem URI des Container-Images in Artifact Registry (z. B. us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

Die Bereitstellungslatenz hängt von der Gesamtzeit ab, die für die Installation der erforderlichen Pakete benötigt wird. Nach der Bereitstellung entspricht remote_agent einer Instanz von local_agent, die auf der Agent Platform ausgeführt wird und abgefragt oder gelöscht werden kann.

Das Objekt remote_agent entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Agent Platform SDK

Wenn Sie den Agenten auf der Agent Platform bereitstellen möchten, verwenden Sie client.runtimes.create, um das local_agent-Objekt zusammen mit allen optionalen Konfigurationen zu übergeben: 

remote_agent = client.runtimes.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

Die Bereitstellung dauert einige Minuten. Währenddessen werden im Hintergrund die folgenden Schritte ausgeführt:

  1. Lokal wird ein Bundle der folgenden Artefakte generiert:
  2. Das Bundle wird in Cloud Storage (im entsprechenden Ordner) hochgeladen, um die Artefakte bereitzustellen.
  3. Die Cloud Storage-URIs für die jeweiligen Artefakte werden in der PackageSpec angegeben.
  4. Der Agent Runtime-Dienst empfängt die Anfrage, erstellt Container und startet HTTP-Server im Backend.

Die Bereitstellungslatenz hängt von der Gesamtzeit ab, die für die Installation der erforderlichen Pakete benötigt wird. Nach der Bereitstellung entspricht remote_agent einer Instanz von local_agent, die auf der Agent Platform ausgeführt wird und abgefragt oder gelöscht werden kann.

Das Objekt remote_agent entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Optional: Ressourcen-ID des KI-Agenten abrufen

Jeder bereitgestellte KI-Agent hat eine eindeutige Kennung. Mit dem folgenden Befehl können Sie den Ressourcennamen für Ihren bereitgestellten Agenten abrufen:

remote_agent.api_resource.name

Die Antwort sollte in etwa so aussehen:

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

Dabei gilt:

  • PROJECT_ID ist die Projekt-ID von Google Cloud , in dem der bereitgestellte Agent ausgeführt wird.

  • LOCATION ist die Region, in der der bereitgestellte Agent ausgeführt wird.

  • RESOURCE_ID ist die ID des bereitgestellten KI-Agenten als reasoningEngine-Ressource.

Optional: Unterstützte Vorgänge auflisten

Jeder bereitgestellte Agent hat eine Liste der unterstützten Vorgänge. Mit dem AgentRuntime.operation_schemas können Sie die Liste der vom bereitgestellten Agenten unterstützten Vorgänge abrufen:

remote_agent.operation_schemas()

Das Schema für jeden Vorgang ist ein Wörterbuch, das die Informationen einer Methode für den Agenten dokumentiert, die Sie aufrufen können. Die unterstützten Vorgänge hängen vom Framework ab, das Sie zur Entwicklung Ihres KI-Agenten verwendet haben:

Optional: Dem bereitgestellten Agenten Berechtigungen gewähren

Wenn dem bereitgestellten Agenten zusätzliche Berechtigungen gewährt werden müssen, folgen Sie der Anleitung unter Identität und Berechtigungen für den Agenten einrichten.

Optional: KI-Agenten mit Unternehmensinfrastruktur bereitstellen

Wenn Sie Ihren Agenten mit einer vollständigen Umgebung bereitstellen möchten, die Sicherheits- und Governance-Ebenen enthält, kopieren Sie die folgenden Application Design Center-Vorlagen und passen Sie sie an:

Nächste Schritte

Anleitung

Hier erfahren Sie, wie Sie KI-Agenten verwalten, die in der verwalteten Laufzeit der Agent Platform bereitgestellt wurden.

Anleitung

Agenten mit Agent Platform Runtime verwenden