Agent bereitstellen

Wenn Sie einen KI-Agenten in Vertex AI Agent Engine bereitstellen möchten, haben Sie folgende Möglichkeiten:

  • Über ein Agent-Objekt bereitstellen: Ideal für die interaktive Entwicklung in Umgebungen wie Colab, da die Bereitstellung von local_agent-Objekten im Arbeitsspeicher möglich ist. Diese Methode eignet sich am besten für Agents mit Strukturen, die keine komplexen, nicht serialisierbaren Komponenten enthalten.
  • Aus Quelldateien bereitstellen: Diese Methode eignet sich gut für automatisierte Workflows wie CI/CD-Pipelines und Infrastruktur-als-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.
  • Über Dockerfile bereitstellen: Diese Methode ähnelt der Methode zum Bereitstellen über Quelldateien. Sie stellen Ihren Agent direkt aus lokalem Quellcode bereit. Sie benötigen keinen Cloud Storage-Bucket. Diese Methode ist geeignet, wenn Sie den bereitgestellten API-Server definieren und steuern müssen.
  • Über Container-Image bereitstellen: Diese Methode ähnelt der Methode für die Bereitstellung über Dockerfile. Sie stellen ein Container-Image bereit, das in Artifact Registry gehostet wird. Verwenden Sie diese Methode, wenn Sie den Build-Prozess für das Container-Image steuern und die Bereitstellungslatenz verringern möchten.
  • Über Developer Connect bereitstellen: Empfohlen für Projekte, die in einem Git-Repository verwaltet werden, das über Developer Connect verknüpft ist. Diese Methode vereinfacht die Agentenbereitstellung 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.

So legen Sie los:

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

Sie können auch Agent Starter Pack-Vorlagen für die Bereitstellung verwenden.

Vorbereitung

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

  1. Richten Sie die Umgebung ein.
  2. Agent entwickeln.

(Optional) Agent für die Bereitstellung konfigurieren

Sie können die folgenden optionalen Konfigurationen für Ihren Agent vornehmen:

AgentEngine-Instanz erstellen

In diesem Abschnitt wird beschrieben, wie Sie eine AgentEngine-Instanz zum Bereitstellen eines Agents erstellen.

Sie haben folgende Möglichkeiten, einen Agenten in Vertex AI Agent Engine bereitzustellen:

  • Bereitstellung über ein Agent-Objekt für die interaktive Entwicklung
  • Bereitstellung über Developer Connect für Git-basierte Workflows.
  • Bereitstellung aus Quelldateien oder Dockerfile für dateibasierte Workflows.

  • Bereitstellung über Container-Image für bildbasierte Workflows.

Python-Objekt

Um den Agent in Vertex AI bereitzustellen, verwenden Sie client.agent_engines.create, um das local_agent-Objekt zusammen mit allen optionalen Konfigurationen zu übergeben:

remote_agent = client.agent_engines.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 hochgeladen (in den entsprechenden Ordner), um die Artefakte bereitzustellen.

  3. Die Cloud Storage-URIs für die jeweiligen Artefakte werden in der PackageSpec angegeben.

  4. Der Vertex AI Agent Engine-Dienst empfängt die Anfrage, erstellt Container und startet HTTP-Server im Backend.

Developer Connect

Wenn Sie die Bereitstellung über Developer Connect in Vertex AI vornehmen möchten, verwenden Sie client.agent_engines.create und geben Sie 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.

remote_agent = client.agent_engines.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 (erforderlich, dict): Die Konfiguration zum Abrufen von Quellcode. Weitere Informationen finden Sie unter Git-Repository-Link von Developer Connect einrichten.
    • git_repository_link (Erforderlich, str): Der Ressourcenname des Developer Connect-Git-Repository-Links.
    • revision (erforderlich, str): Die abzurufende Revision (Branch, Tag oder Commit-SHA).
    • dir (erforderlich, str): Das Stammverzeichnis des Agent-Codes im Repository.
  • entrypoint_module (erforderlich, str): Der Name des Python-Moduls, das den Einstiegspunkt des Agents enthält, relativ zum Verzeichnis, das in developer_connect_source.dir angegeben ist.
  • entrypoint_object (erforderlich, str): Der Name des aufrufbaren Objekts in der entrypoint_module, das die Agent-Anwendung darstellt (z. B. root_agent).
  • requirements_file (Optional, str): Der Pfad zu einer pip-Anforderungsdatei relativ zum Quell-Root. Die Standardeinstellung ist requirements.txt.

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

  1. Der Vertex AI Agent Engine-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.

Quelldateien

Wenn Sie aus Quelldateien in Vertex AI bereitstellen möchten, verwenden Sie client.agent_engines.create. Geben Sie dazu source_packages, entrypoint_module, entrypoint_object und class_methods im Konfigurations-Dictionary sowie andere optionale Konfigurationen an. Bei dieser Methode müssen Sie kein Agent-Objekt oder Cloud Storage-Bucket übergeben.

remote_agent = client.agent_engines.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 (erforderlich, list[str]): Eine Liste mit lokalen Datei- oder Verzeichnispfaden, die in die Bereitstellung aufgenommen werden sollen. Die Gesamtgröße der Dateien und Verzeichnisse in source_packages darf 8 MB nicht überschreiten.
  • entrypoint_module (erforderlich, str): Der voll qualifizierte Python-Modulname, der den Agent-Einstiegspunkt enthält (z. B. agent_dir.agent).
  • entrypoint_object (erforderlich, str): Der Name des aufrufbaren Objekts in der entrypoint_module, das die Agent-Anwendung darstellt (z. B. root_agent).

  • class_methods (erforderlich, list[dict]): Eine Liste von Dictionaries, die die verfügbaren Methoden des Agents definieren. Jedes Wörterbuch enthält die Felder name (erforderlich), api_mode (erforderlich) und 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": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file (Optional, str): Der Pfad zu einer pip-Anforderungsdatei in den in source_packages angegebenen Pfaden. 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. Das Vertex AI SDK erstellt ein tar.gz-Archiv der in source_packages angegebenen Pfade.
  2. Dieses Archiv wird codiert und direkt an die Vertex AI API gesendet.
  3. Der Vertex AI Agent Engine-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.

Im Folgenden finden Sie ein Beispiel für die Bereitstellung eines Agents aus Quellcode:

from google.cloud.aiplatform import vertexai

# 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.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

Dockerfile

Die Bereitstellung über ein Dockerfile in Vertex AI ähnelt der Bereitstellung über Quelldateien. Die einzige Stelle, die sich beim Bereitstellen ändert, ist, dass entrypoint_module, entrypoint_object und (optional) requirements_file in der Konfiguration durch ein image_spec ersetzt werden.

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

from google.cloud.aiplatform import vertexai

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

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

Container-Image

Wenn Sie die Bereitstellung über ein Container-Image vornehmen möchten, folgen Sie zuerst der Einrichtungsanleitung unter Eigenen Container verwenden. Achten Sie darauf, dass Sie eine Version von google-cloud-aiplatform installieren, die >=1.144 erfüllt. Führen Sie als Nächstes den folgenden Code aus:

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
    },
)

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 Vertex AI ausgeführt wird und abgefragt oder gelöscht werden kann.

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

Optional: Agent-Ressourcen-ID abrufen

Jeder bereitgestellte Agent hat eine eindeutige Kennung. Sie können den folgenden Befehl ausführen, um den Ressourcennamen für Ihren bereitgestellten Agenten abzurufen:

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 Agent ausgeführt wird.

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

Optional: Unterstützte Vorgänge auflisten

Jeder bereitgestellte Agent hat eine Liste der unterstützten Vorgänge. Mit AgentEngine.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 Wörterbuch, in dem die Informationen einer Methode für den Agenten dokumentiert sind, die Sie aufrufen können. Die unterstützten Vorgänge hängen vom Framework ab, das Sie zum Entwickeln Ihres Agenten 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.

Nächste Schritte