Umgebung einrichten

Bevor Sie mit Agent Runtime arbeiten, müssen Sie Ihre Umgebung einrichten. Sie benötigen ein Google Cloud -Projekt mit aktivierter Abrechnung, die erforderlichen Berechtigungen und Sie müssen einen Cloud Storage-Bucket einrichten und das Agent Platform SDK für Python installieren. Bereiten Sie sich auf die folgenden Themen vor, damit Sie die Arbeit mit Agent Runtime beginnen können.

Ein Terraform-Referenzbeispiel zur Optimierung der Einrichtung und Bereitstellung der Agent Runtime-Umgebung finden Sie im agent-starter-pack.

Mit Google Cloudeinrichten

Sie können Google Cloud für Agent Runtime einrichten, indem Sie ein Google Cloud -Projekt erstellen.

Google Cloud -Projekt

Jedes Projekt kann auf zwei Arten identifiziert werden: über die Projektnummer oder die Projekt-ID. Die PROJECT_NUMBER wird beim Erstellen des Projekts automatisch erstellt, während die PROJECT_ID von Ihnen oder dem Ersteller des Projekts erstellt wird. So richten Sie ein Projekt ein:

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

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

  3. Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are 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 APIs

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 Agent Runtime 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.

Identität und Berechtigungen für den KI-Agenten einrichten

Sie haben die folgenden Optionen, wenn Sie Identität und Berechtigungen einrichten:

  • Agentenidentität (empfohlen) Verwenden Sie die IAM-Agentenidentität (Identity Access Management), um Sicherheits- und Zugriffsverwaltungsfunktionen bereitzustellen, wenn Sie Agenten in der Agent Runtime verwenden. Die Identität eines KI-Agenten ist an den jeweiligen KI-Agenten gebunden. Standardmäßig haben KI-Agenten die Rolle Agent Platform Agent Default Access (roles/aiplatform.agentDefaultAccess), die nur grundlegende Berechtigungen für das projektweite Logging und den Modellaufruf enthält, sowie die Rolle Agent Platform Agent Context Editor (roles/aiplatform.agentContextEditor), die den Zugriff eines KI-Agenten auf seine eigenen Sitzungen, gemerkten Informationen und Sandboxes beschränkt.

    Hinweis: Einige Funktionen, auf die mit dieser Rolle zugegriffen werden kann, befinden sich möglicherweise in der Vorschau.

  • Dienstkonten: Dienstkonten werden von allen Agenten gemeinsam genutzt, die Sie in Agent Runtime bereitstellen. Sie haben zwei Optionen für das Dienstkonto:

    • Standard-Dienst-Agent: Standardmäßig verwenden KI-Agenten den AI Platform Reasoning Engine-Dienst-Agenten. Dieses von Google verwaltete Dienstkonto hat die Rolle Gemini Enterprise Agent Platform Reasoning Engine-Dienst-Agent (roles/aiplatform.reasoningEngineServiceAgent), die die Standardberechtigungen für bereitgestellte Agenten enthält.
    • Benutzerdefiniertes Dienstkonto: Sie können ein eigenes Dienstkonto für die Agents angeben. So haben Sie eine genauere Kontrolle über die Berechtigungen, die den Agenten gewährt werden.

Agentenidentität

Wenn Sie IAM-Richtlinien vor der Bereitstellung des KI-Agenten einrichten möchten, können Sie eine KI-Agentenidentität erstellen, ohne den KI-Agenten-Code bereitzustellen. Erstellen Sie dazu eine Agent Platform-Instanz, die nur das Feld identity_type enthält:

remote_app = client.agent_engines.create(
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

Nachdem Sie die Agent Platform-Instanz mit der Agentenidentität erstellt haben, können Sie Folgendes tun:

  1. Weisen Sie der Agentenidentität nach Bedarf zusätzliche Rollen für Ihren Anwendungsfall zu.

  2. Fügen Sie Agentencode mit agent_engine.update(...) hinzu.

Standard-Dienst-Agent

Der KI-Plattform Reasoning Engine Dienst-Agent wird standardmäßig verwendet. Eine vollständige Liste der Standardberechtigungen finden Sie in der IAM-Dokumentation.

Wenn Ihr Agent Berechtigungen benötigt, die über die Standardberechtigungen hinausgehen, können Sie diesem Dienst-Agent zusätzliche Rollen zuweisen:

  1. Rufen Sie die Seite IAM auf und markieren Sie das Kästchen „Von Google bereitgestellte Rollenzuweisungen einschließen“.

    IAM aufrufen

  2. Suchen Sie das Hauptkonto, das mit service-PROJECT_NUMBER@gcp-sa-aiplatform-re. übereinstimmt.

  3. Fügen Sie dem Hauptkonto die erforderlichen Rollen hinzu. Klicken Sie dazu auf den Button „Bearbeiten“ und dann auf den Button „Speichern“.

Standarddienst-Agent manuell generieren

Der Reasoning Engine Service Agent wird zwar bei der Bereitstellung der Agent Runtime automatisch bereitgestellt, es kann aber Fälle geben, in denen Sie ihn vorher manuell generieren müssen. Das ist besonders wichtig, wenn Sie dem Dienst-Agenten bestimmte Rollen zuweisen müssen, damit der Bereitstellungsprozess die erforderlichen Berechtigungen hat und potenzielle Bereitstellungsfehler vermieden werden.

So erstellen Sie einen Reasoning Engine Service Agent manuell:

  1. Generieren Sie den Reasoning Engine-Dienst-Agent mit der Google Cloud CLI.

    gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

  2. Rufen Sie die Seite IAM auf und klicken Sie auf Zugriff erlauben.

    IAM aufrufen

  3. Geben Sie im Abschnitt Hauptkonten hinzufügen im Feld Neue Hauptkonten den Wert service-PROJECT_NUMBER@gcp-sa-aiplatform-re. ein.

  4. Suchen Sie im Bereich Rollen zuweisen nach den gewünschten Rollen und wählen Sie sie aus.

  5. Klicken Sie auf Speichern.

Benutzerdefiniertes Dienstkonto

Wenn Sie Ihr eigenes Dienstkonto verwenden möchten, müssen Sie ihm die erforderlichen Berechtigungen zum Ausführen des Agents gewähren. Ihr benutzerdefiniertes Dienstkonto benötigt wahrscheinlich die Rolle Agent Platform User (roles/aiplatform.user).

  1. Wenn Sie kein Dienstkonto haben, erstellen Sie eins. Siehe Dienstkonten erstellen.

  2. Weisen Sie dem Dienstkonto die Rolle Agent Platform User (roles/aiplatform.user) zu.

  3. Weisen Sie dem Dienstkonto alle anderen Rollen zu, die für Ihren Agent-Code erforderlich sind.

  4. Wenn Sie Ihren Agent mit diesem Dienstkonto bereitstellen möchten, weisen Sie sich selbst die Rolle Dienstkontonutzer (roles/iam.serviceAccountUser) für dieses benutzerdefinierte Dienstkonto zu.

  5. Geben Sie beim Bereitstellen des Agents die E-Mail-Adresse Ihres benutzerdefinierten Dienstkontos an. Weitere Informationen finden Sie unter Benutzerdefiniertes Dienstkonto konfigurieren.

Projektübergreifendes benutzerdefiniertes Dienstkonto

Wenn Ihr benutzerdefiniertes Dienstkonto aus einem anderen Projekt stammt, sind zusätzliche Konfigurationen sowohl im Projekt, in dem sich das Dienstkonto befindet, als auch im Projekt, in dem Sie den Agent bereitstellen, erforderlich.

  1. Organisationsrichtlinie „Projektübergreifende Dienstkontonutzung deaktivieren“: Achten Sie darauf, dass die Organisationsrichtlinie iam.disableCrossProjectServiceAccountUsage im Projekt, in dem sich das Dienstkonto befindet, NICHT erzwungen wird. Weitere Informationen finden Sie unter Erzwingung der projektübergreifenden Dienstkontonutzung deaktivieren.

  2. Berechtigungen für den Agent Platform-Dienst-Agenten gewähren: Weisen Sie dem Agent Platform-Dienst-Agenten (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.) des Projekts, in dem Sie den Agenten bereitstellen möchten, im Projekt, in dem sich das Dienstkonto befindet, die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) zu.

  3. Berechtigungen für das benutzerdefinierte Dienstkonto gewähren: Gewähren Sie dem benutzerdefinierten Dienstkonto im Projekt, in dem Sie den Agenten bereitstellen möchten, die erforderlichen Rollen. Dazu gehören in der Regel die Rolle Agent Platform User (roles/aiplatform.user) und alle anderen Rollen, die für Ihren Agent-Code erforderlich sind.

(Optional) Cloud Storage-Bucket erstellen

Ob ein Cloud Storage-Bucket erforderlich ist, hängt davon ab, ob das Agent Platform SDK für Python einen Ort zum Bereitstellen Ihres Agent-Codes vor der Bereitstellung benötigt:

  • Aus Quelldateien bereitstellen: Der Agent ist als Dateien vorhanden. Das Agent Platform SDK für Python kann diese Dateien bündeln und direkt in den Bereitstellungsdienst hochladen, sodass kein Cloud Storage-Staging-Bucket erforderlich ist.

  • Aus Agent-Objekt bereitstellen: Der Agent ist im Arbeitsspeicher vorhanden. Das Agent Platform SDK für Python verpackt dieses Objekt und lädt es in einen Cloud Storage-Bucket hoch, der als Staging-Bereich für den Bereitstellungsdienst dient.

Über Quelldateien bereitstellen

Wenn Sie einen Agent aus Quelldateien bereitstellen, ist kein Cloud Storage-Bucket erforderlich.

Über Objekt bereitstellen

Wenn Sie aus einem Agent-Objekt bereitstellen, stellt Agent Runtime die Artefakte Ihrer bereitgestellten Agenten im Rahmen des Bereitstellungsprozesses in einem Cloud Storage-Bucket bereit. Achten Sie darauf, dass das Hauptkonto, das für die Verwendung der Gemini Enterprise Agent Platform authentifiziert ist (entweder Sie selbst oder ein Dienstkonto), Storage Admin-Zugriff auf diesen Bucket hat. Dies ist erforderlich, da das Agent Platform SDK für Python Ihren Code in diesen Bucket schreibt.

Wenn Sie bereits einen Bucket eingerichtet haben, können Sie diesen Schritt überspringen. Andernfalls können Sie der Standardanleitung zum Erstellen eines Buckets folgen.

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage-Administrator (roles/storage.admin) für Ihr Projekt zuzuweisen.

Google Cloud Console

  1. Wechseln Sie in der Google Cloud Console unter „Cloud Storage“ zur Seite Buckets.

    Buckets aufrufen

  2. Klicken Sie auf Erstellen.
  3. Geben Sie auf der Seite Bucket erstellen die Bucket-Informationen ein. Klicken Sie auf Weiter, um mit dem nächsten Schritt fortzufahren.
    1. Führen Sie im Abschnitt Einstieg die folgenden Schritte aus:
      • Geben Sie einen global eindeutigen Namen ein, der den Anforderungen für Bucket-Namen entspricht.
      • So fügen Sie ein Bucket-Label hinzu: Maximieren Sie den Abschnitt Labels (), klicken Sie auf Label hinzufügen und geben Sie key und value für Ihr Label an.
    2. Gehen Sie im Abschnitt Speicherort für Daten auswählen so vor:
      1. Standorttyp auswählen.
      2. Wählen Sie im Drop-down-Menü Standorttyp einen Standort aus, an dem die Daten Ihres Buckets dauerhaft gespeichert werden sollen.
        • Wenn Sie den Standorttyp Dual-Region auswählen, können Sie auch die Turboreplikation aktivieren, indem Sie das entsprechende Kästchen anklicken.
      3. Wenn Sie die Bucket-übergreifende Replikation einrichten möchten, wählen Sie Bucket-übergreifende Replikation über Storage Transfer Service hinzufügen aus und führen Sie die folgenden Schritte aus:

        Bucket-übergreifende Replikation einrichten

        1. Wählen Sie im Menü Bucket einen Bucket aus.

        2. Klicken Sie im Bereich Replikationseinstellungen auf Konfigurieren, um die Einstellungen für den Replikationsjob zu konfigurieren.

          Der Bereich Bucket-übergreifende Replikation konfigurieren wird angezeigt.

          • Wenn Sie die zu replizierenden Objekte nach dem Objektnamenspräfix filtern möchten, geben Sie ein Präfix ein, mit dem Sie Objekte ein- oder ausschließen möchten, und klicken Sie dann auf Präfix hinzufügen.
          • Wenn Sie eine Speicherklasse für die replizierten Objekte festlegen möchten, wählen Sie im Menü Speicherklasse eine Speicherklasse aus. Wenn Sie diesen Schritt überspringen, verwenden die replizierten Objekte standardmäßig die Speicherklasse des Ziel-Buckets.
          • Klicken Sie auf Fertig.
    3. Gehen Sie im Bereich Speicherort für Daten auswählen so vor:
      1. Wählen Sie eine Standardspeicherklasse für den Bucket oder Autoclass für die automatische Speicherklassenverwaltung der Daten Ihres Buckets aus.
      2. Wenn Sie den hierarchischen Namespace aktivieren möchten, wählen Sie im Abschnitt Speicher für datenintensive Arbeitslasten optimieren die Option Hierarchischen Namespace für diesen Bucket aktivieren aus.
    4. Wählen Sie im Abschnitt Zugriff auf Objekte steuern aus, ob der Bucket die Verhinderung des öffentlichen Zugriffs durchsetzt, und wählen Sie eine Zugriffssteuerungsmethode für die Objekte Ihres Buckets aus.
    5. Gehen Sie im Bereich Auswählen, wie Objektdaten geschützt werden so vor:
      • Wählen Sie unter Datenschutz die Optionen aus, die Sie für Ihren Bucket festlegen möchten.
        • Wenn Sie das vorläufige Löschen aktivieren möchten, klicken Sie auf das Kästchen Richtlinie für vorläufiges Löschen (zur Datenwiederherstellung) und geben Sie die Anzahl der Tage an, die Objekte nach dem Löschen aufbewahrt werden sollen.
        • Wenn Sie die Objektversionsverwaltung festlegen möchten, klicken Sie auf das Kästchen Objektversionsverwaltung (zur Versionsverwaltung) und geben Sie die maximale Anzahl von Versionen pro Objekt sowie die Anzahl der Tage an, nach denen die nicht aktuellen Versionen ablaufen.
        • Wenn Sie die Aufbewahrungsrichtlinie für Objekte und Buckets aktivieren möchten, klicken Sie auf das Kästchen Aufbewahrung (für Compliance) und gehen Sie so vor:
          • Klicken Sie zum Aktivieren der Objektaufbewahrungssperre auf das Kästchen Objektaufbewahrung aktivieren.
          • Wenn Sie die Bucket-Sperre aktivieren möchten, klicken Sie auf das Kästchen Aufbewahrungsrichtlinie für Bucket festlegen und wählen Sie eine Zeiteinheit und eine Zeitdauer für die Aufbewahrungsdauer aus.
      • Um auszuwählen, wie Ihre Objektdaten verschlüsselt werden, maximieren Sie den Bereich Datenverschlüsselung () und wählen Sie eine Methode für die Datenverschlüsselung aus.
  4. Klicken Sie auf Erstellen.

Befehlszeile

    Erstellen Sie einen Cloud Storage-Bucket und konfigurieren Sie ihn so:
    • Ersetzen Sie STORAGE_CLASS durch die gewünschte Speicherklasse.
    • Ersetzen Sie LOCATION durch den gewünschten Standort (ASIA, EU oder US).
    • Ersetzen Sie BUCKET_NAME durch einen Bucket-Namen, der die Anforderungen für Bucket-Namen erfüllt. 
    gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Agent Platform SDK für Python installieren und initialisieren

In diesem Abschnitt wird davon ausgegangen, dass Sie eine Python-Entwicklungsumgebung eingerichtet haben oder Colab (oder eine andere geeignete Laufzeit, die die Umgebung für Sie eingerichtet hat) verwenden.

Optional: Virtuelle Umgebung einrichten

Wir empfehlen außerdem, eine virtuelle Umgebung einzurichten, um Ihre Abhängigkeiten zu isolieren.

Installation

Um die Anzahl der zu installierenden Abhängigkeiten zu minimieren, haben wir die Abhängigkeiten in folgende Gruppen unterteilt:

  • agent_engines: die Pakete, die für die Bereitstellung in Agent Runtime erforderlich sind.
  • adk: die kompatiblen ADK-Pakete (Agent Development Kit).
  • langchain: die kompatiblen LangChain- und LangGraph-Pakete.
  • ag2: die kompatiblen AG2-Pakete.
  • llama_index: die kompatiblen LlamaIndex-Pakete.

Wenn Sie das Agent Platform SDK für Python installieren, können Sie die erforderlichen Abhängigkeiten (durch Kommas getrennt) angeben. So installieren Sie alle:

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.112.0

Wenn Sie Agent2Agent (A2A) auf der Agent Platform verwenden möchten , müssen Sie auch das Paket „a2a-sdk“ installieren:

pip install google-adk[a2a]

Authentifizierung

Colab

Führen Sie den folgenden Code aus:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

Es sind keine weiteren Schritte erforderlich.

Lokale Shell

Führen Sie dazu diesen Befehl aus:

gcloud auth application-default login

SDK importieren und initialisieren

Führen Sie den folgenden Code aus, um das SDK für Agent Runtime zu importieren und zu initialisieren:

Google Cloud -Projekt 

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

Dabei gilt:

(Optional) Eigenen Container verwenden (Bring your own Container, BYOC)

Standardmäßig erstellt die Agent Runtime im Rahmen des Bereitstellungsprozesses einen Container für Sie. Wenn Sie einen benutzerdefinierten Container für die Bereitstellung erstellen möchten, folgen Sie der Anleitung in diesem Abschnitt.

Führen Sie die folgenden allgemeinen Aufgaben aus, um Ihren Agent mit einem benutzerdefinierten Container bereitzustellen:

  1. Erstellen Sie Ihr Container-Image und übertragen Sie es per Push an Artifact Registry.
  2. Identität und Berechtigungen für den Agent einrichten
  3. Weisen Sie dem Standard-Dienst-Agenten von Agent Runtime die Rolle „Artifact Registry-Leser“ zu.

Container-Image erstellen und per Push übertragen

Folgen Sie der Anleitung unter Docker-Image mit Cloud Build erstellen und per Push übertragen, um Ihr Container-Image zu erstellen und per Push zu übertragen.

Identität und Berechtigungen für Agent Runtime einrichten

Der Standard-Dienst-Agent der Agent Runtime ist erforderlich, um Container aus Ihrem Artifact Registry-Repository zu importieren.

Der Dienst-Agent wird standardmäßig automatisch in Ihrem Projekt generiert. Wenn es nicht vorhanden ist, folgen Sie der Anleitung unter Identität und Berechtigungen für Ihren Agent einrichten, um es zu erstellen und zu konfigurieren.

Rolle „Artifact Registry-Leser“ gewähren

Weisen Sie dem Standard-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.) die Rolle „Artifact Registry-Leser“ (roles/artifactregistry.reader) zu.

Führen Sie den folgenden Befehl aus, um dem Standard-Dienst-Agent die erforderliche Rolle zuzuweisen:

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-re." \
  --role="roles/artifactregistry.reader"

(Optional) Projektübergreifende Berechtigung gewähren

Eine projektübergreifende Berechtigung ist erforderlich, wenn Ihre Container-Images in einem Artifact Registry-Repository in einem anderen Google Cloud Projekt gespeichert sind als dem, in dem Ihre Agenten bereitgestellt werden.

Weisen Sie in diesem Fall dem Agent Platform-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform.) in Ihrem Artifact Registry-Repository-Projekt die Rolle „Artifact Registry-Leser“ zu.

gcloud projects add-iam-policy-binding AR_REPO_PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform." \
  --role="roles/artifactregistry.reader"

Nächste Schritte

Übersicht

Informationen zum Erstellen eines KI-Agenten mit der Agent Platform-Laufzeit

Fehlerbehebung

Hier erfahren Sie, wie Sie häufige Fehler beim Erstellen benutzerdefinierter KI-Agenten beheben können.

Ressource

Ressourcen und Support für die Google Agent Platform