KI-Agenten bereitstellen

Wenn Sie einen KI-Agenten in Agent Runtime bereitstellen, ist er remote verfügbar, um Anfragen zu bearbeiten. In diesem Dokument wird beschrieben, wie Sie einen Agent basierend auf Ihrem Entwicklungs-Workflow bereitstellen: über ein Ausführungsobjekt, lokale Quelldateien, ein Dockerfile, ein in Artifact Registry gehostetes Container-Image oder direkt über ein verbundenes Git-Repository.

Sie haben folgende Möglichkeiten, einen Agent in Agent Runtime bereitzustellen:

Developer Connect

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

Sie können diese Bereitstellungsmethode nur mit Python verwenden.

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 es ist kein Cloud Storage-Bucket erforderlich.

Sie können diese Bereitstellungsmethode nur mit Python verwenden.

Dockerfile

Ähnlich wie beim Bereitstellen aus Quelldateien. Sie stellen Ihren Agent 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 über ein 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, die die Bereitstellung von local_agent-In-Memory-Objekten ermöglicht. Diese Methode eignet sich am besten für Agents mit Strukturen, die keine komplexen, nicht serialisierbaren Komponenten enthalten.

So legen Sie los:

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

Vorbereitung

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

  1. Umgebung einrichten
  2. Agent erstellen

Optional: KI-Agent für die Bereitstellung konfigurieren

Sie können optionale Konfigurationen für Ihren Agent 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 Agents erstellen. Sie haben die Wahl zwischen den folgenden Methoden:

Developer Connect

Wenn Sie über Developer Connect auf der Agent Platform bereitstellen möchten, verwenden Sie client.runtimes.create. Geben Sie dazu developer_connect_source, entrypoint_module und entrypoint_object im Konfigurations-Dictionary sowie andere optionale Konfigurationen an. Mit dieser Methode können Sie Code direkt aus einem verbundenen Git-Repository bereitstellen.

Sie können diese Bereitstellungsmethode nur mit Python verwenden. 

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 von Quellcode. Weitere Informationen finden Sie unter Git-Repository-Link von Developer Connect einrichten.
    • git_repository_link (str): Der Ressourcennamen des Git-Repository-Links von Developer Connect.
    • revision (str): Die abzurufende Revision (Branch, Tag oder Commit-SHA).
    • dir (str): Das Stammverzeichnis des Agent-Codes im Repository.
  • entrypoint_module (str): Der Name des Python-Moduls, das den Einstiegspunkt des Agenten enthält, relativ zum im developer_connect_source.dir angegebenen Verzeichnis.
  • entrypoint_object (str): Der Name des aufrufbaren Objekts innerhalb von entrypoint_module, das die Agent-Anwendung darstellt (z. B. root_agent).
  • requirements_file (str): Optional: Der Pfad zu einer pip-Anforderungsdatei relativ zum Quellstamm. Die Standardeinstellung ist requirements.txt.

Die Bereitstellung dauert einige Minuten. Im Hintergrund werden dabei die folgenden Schritte ausgeführt:

  1. Der Agent Runtime-Dienst ruft den Quellcode aus der angegebenen Git-Repository-Revision ab.
  2. Der Dienst installiert Abhängigkeiten aus requirements_file (falls angegeben).
  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 remote_agent-Objekt entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Quelldateien

Wenn Sie die Bereitstellung über Quellcode-Dateien auf der Agent Platform vornehmen möchten, verwenden Sie client.runtimes.create. Geben Sie dazu source_packages, entrypoint_module, entrypoint_object und class_methods im Konfigurations-Dictionary an, zusammen mit anderen optionalen Konfigurationen. Bei dieser Methode müssen Sie kein Agent-Objekt oder Cloud Storage-Bucket übergeben.

Sie können diese Bereitstellungsmethode nur mit Python verwenden. 

# 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 der lokalen Datei- oder Verzeichnispfade, die in die Bereitstellung aufgenommen werden sollen. Die Gesamtgröße der Dateien und Verzeichnisse in source_packages darf 8 MB nicht überschreiten.
  • entrypoint_module (str): Der voll qualifizierte Python-Modulname, der den Einstiegspunkt des KI-Agenten enthält (z. B. agent_dir.agent).
  • entrypoint_object (str): Der Name des aufrufbaren Objekts innerhalb von entrypoint_module, das die Agent-Anwendung darstellt (z. B. root_agent).
  • class_methods (list[dict]): Eine Liste von Dictionaries, die die verfügbaren Methoden des Agenten definieren. Jedes Wörterbuch enthält die Felder name und api_mode sowie das optionale Feld parameters. Weitere Informationen zu den Methoden für einen benutzerdefinierten Agent 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 Datei mit Pip-Anforderungen innerhalb der in source_packages angegebenen Pfade. Standardmäßig ist requirements.txt im Stammverzeichnis der verpackten Quelle festgelegt.

Die Bereitstellung dauert einige Minuten. Im Hintergrund werden dabei die folgenden Schritte ausgeführt:

  1. Mit dem Agent Platform SDK wird ein tar.gz-Archiv der in source_packages angegebenen Pfade erstellt.
  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 angegeben) 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 remote_agent-Objekt entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Dockerfile

Die Bereitstellung über ein Dockerfile auf der Agent-Plattform ähnelt der Bereitstellung über Quellcode-Dateien. Der 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 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 remote_agent-Objekt 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 Bring Your Own Container und installieren Sie eine Version von google-cloud-aiplatform, 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 Agenten 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 remote_agent-Objekt entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Agent Platform SDK

Wenn Sie den Agent 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. Im Hintergrund werden dabei die folgenden Schritte ausgeführt:

  1. Lokal wird ein Bündel der folgenden Artefakte generiert:
  2. Das Bündel wird in Cloud Storage (in den 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 remote_agent-Objekt entspricht einer AgentRuntime-Klasse, die Folgendes enthält:

Optional: Agent-Ressourcen-ID 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 Google Cloud Projekt-ID, in der der bereitgestellte Agent ausgeführt wird.

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

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

Optional: Unterstützte Vorgänge auflisten

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

remote_agent.operation_schemas()

Das Schema für jeden Vorgang ist ein Dictionary, in dem die Informationen einer Methode für den Agent dokumentiert sind, die Sie aufrufen können. Die unterstützten Vorgänge hängen vom Framework ab, das Sie zum Entwickeln Ihres KI-Agents verwendet haben:

Optional: Berechtigungen für den bereitgestellten Agent erteilen

Wenn dem bereitgestellten Agent zusätzliche Berechtigungen erteilt werden müssen, folgen Sie der Anleitung unter Identität und Berechtigungen für Ihren Agent einrichten.

Optional: KI-Agenten mit Unternehmensinfrastruktur bereitstellen

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

Nächste Schritte

Leitfaden

Informationen zum Verwalten von KI-Agenten, die in der verwalteten Laufzeit der Agent Platform bereitgestellt wurden.

Leitfaden

Einen Agenten mit Agent Platform Runtime verwenden