Umgebung einrichten

Bevor Sie mit Vertex AI Agent Engine 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 Vertex AI SDK für Python installieren. Bereiten Sie sich auf die folgenden Themen vor, damit Sie die Arbeit mit Vertex AI Agent Engine beginnen können.

Ein Referenzbeispiel für Terraform zur Optimierung der Einrichtung und Bereitstellung der Vertex AI Agent Engine-Umgebung finden Sie im Agent-Starter-Pack.

Mit einrichten Google Cloud

Sie können mit Google Cloud für Vertex AI Agent Engine einrichten, indem Sie ein Projekt Google Cloud erstellen.

Google Cloud Projekt

Jedes Projekt kann auf zwei Arten identifiziert werden: über die Projektnummer oder die Projekt-ID. Die PROJECT_NUMBER wird automatisch erstellt, wenn Sie das Projekt erstellen, während die PROJECT_ID von Ihnen oder der Person erstellt wird, die das Projekt erstellt hat. So richten Sie ein Projekt ein:

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Google Cloud-Nutzer sind, erstellen Sie ein Konto, um zu sehen, wie sich unsere Produkte in realen Szenarien schlagen. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

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 APIs

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

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 APIs

Hinweis: Zum Aktivieren von APIs benötigen Sie die serviceusage.services.enable Berechtigung. Wenn Sie diese Berechtigung nicht haben, bitten Sie Ihren Administrator, Ihnen die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) zuzuweisen.

Erforderliche Rollen abrufen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle „Vertex AI-Nutzer “ (roles/aiplatform.user) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwenden 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.

Identität und Berechtigungen für Ihren Agent einrichten

Beim Einrichten von Identität und Berechtigungen haben Sie folgende Möglichkeiten:

• Agentenidentität (empfohlen) (Vorschau): Verwenden Sie die IAM-Agentenidentität (Identity Access Management), um Sicherheits- und Zugriffsverwaltungsfunktionen bereitzustellen, wenn Sie Agents in der Vertex AI Agent Engine-Laufzeit verwenden. Die Agentenidentität ist an jeden einzelnen Agent gebunden.

• Dienstkonten: Dienstkonten werden für alle Agents freigegeben, die Sie in Vertex AI Agent Engine bereitstellen. Sie haben zwei Optionen für das Dienstkonto:

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

Agentenidentität

Vorschau – Private Service Connect-Schnittstelle

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Wenn Sie IAM-Richtlinien einrichten möchten, bevor Sie den Agent bereitstellen, können Sie eine Agentenidentität erstellen, ohne den Agent-Code bereitzustellen. Erstellen Sie dazu eine Agent Engine-Instanz mit nur dem Feld identity_type:

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

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

1. Stellen Sie die Agentenidentität mit den folgenden empfohlenen Rollen bereit:

   • roles/serviceusage.serviceUsageConsumer: Gewähren Sie dem Agent die Berechtigung, das Kontingent des Projekts und das Vertex AI SDK zu verwenden.

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

3. Fügen Sie Agent-Code mit agent_engine.update(...) hinzu.

Standard-Dienst-Agent

Standardmäßig wird der AI Platform Reasoning Engine Service Agent verwendet. Die vollständige Liste der Standardberechtigungen finden Sie in der IAM-Dokumentation.

Wenn Ihr Agent Berechtigungen benötigt, die über die Standardeinstellungen 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 [e-mail] übereinstimmt.

3. Fügen Sie dem Hauptkonto die erforderlichen Rollen hinzu, indem Sie auf die Schaltfläche „Bearbeiten“ und dann auf die Schaltfläche „Speichern“ klicken.

Standard-Dienst-Agent manuell generieren

Der Reasoning Engine Service Agent wird zwar bei der Bereitstellung von Vertex AI Agent Engine 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-Agent 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 Service Agent mit der Google Cloud CLI.

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

   Hinweis: In der Antwort auf den Google Cloud CLI-Befehl wird möglicherweise nur der Vertex AI-Dienst-Agent angezeigt. Der Reasoning Engine Service Agent wird jedoch ebenfalls erstellt.

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

   IAM aufrufen

3. Geben Sie im Bereich Hauptkonten hinzufügen im Feld Neue Hauptkonten [e-mail] 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 ein 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 Vertex AI-Nutzer (roles/aiplatform.user).

1. Wenn Sie kein Dienstkonto haben, erstellen Sie eines. Weitere Informationen finden Sie unter Dienstkonten erstellen.

2. Weisen Sie dem Dienstkonto die Rolle „Vertex AI-Nutzer“ (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 Ihres Agents die E-Mail-Adresse Ihres benutzerdefinierten Dienstkontos an. Weitere Informationen finden Sie unter Benutzerdefiniertes Dienstkonto konfigurieren.

Projektübergreifendes benutzerdefiniertes Dienstkonto

Wenn sich Ihr benutzerdefiniertes Dienstkonto in einem anderen Projekt befindet, 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 Vertex AI-Dienst-Agent gewähren: Weisen Sie im Projekt, in dem sich das Dienstkonto befindet, dem Vertex AI-Dienst-Agent ([e-mail]) des Projekts, in dem Sie den Agent bereitstellen möchten, die Rolle Dienstkonto-Token-Ersteller (roles/iam.serviceAccountTokenCreator) zu.

3. Berechtigungen für das benutzerdefinierte Dienstkonto gewähren:Weisen Sie im Projekt, in dem Sie den Agent bereitstellen möchten, dem benutzerdefinierten Dienstkonto die erforderlichen Rollen zu. Dazu gehört in der Regel die Rolle Vertex AI-Nutzer (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 Vertex AI SDK für Python einen Ort benötigt, um Ihren Agent-Code vor der Bereitstellung bereitzustellen:

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

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

Aus Quelldateien bereitstellen

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

Aus Objekt bereitstellen

Wenn Sie aus einem Agent-Objekt bereitstellen, stellt Vertex AI Agent Engine die Artefakte Ihrer bereitgestellten Agents im Rahmen des Bereitstellungsprozesses in einem Cloud Storage-Bucket bereit. Achten Sie darauf, dass das Hauptkonto, das für die Verwendung von Vertex AI authentifiziert ist (entweder Sie selbst oder ein Dienstkonto), Storage Admin Zugriff auf diesen Bucket hat. Dies ist erforderlich, da das Vertex AI 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.

Hinweis: Wir empfehlen dringend, einen Cloud Storage-Bucket in demselben Projekt zu erstellen, in dem Sie Ihre Agents in Vertex AI Agent Engine bereitstellen. Wenn Sie einen Bucket in einem anderen Projekt verwenden, müssen Sie dem Vertex AI-Dienst-Agent ([e-mail]) manuell Leseberechtigungen für Ihren Cloud Storage-Bucket gewähren.

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. Gehen Sie im Bereich Erste Schritte so vor:
      • 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 Bereich Labels (), klicken Sie auf Label hinzufügen und geben Sie einen key und einen value für Ihr Label an.
   2. Gehen Sie im Bereich Speicherort für Daten auswählen so vor:
      1. Wählen Sie einen Standorttyp aus.
      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, wird für replizierte Objekte standardmäßig die Speicherklasse des Ziel-Buckets verwendet.
            • 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 Bereich Speicher für datenintensive Arbeitslasten optimieren die Option Hierarchischen Namespace für diesen Bucket aktivieren aus.
         Hinweis: Sie können den hierarchischen Namespace nicht in vorhandenen Buckets aktivieren.
   4. Im Abschnitt Zugriff auf Objekte steuern wählen Sie aus, ob der Bucket Verhinderung des öffentlichen Zugriffs durchsetzt, und wählen Sie eine Methode für die Zugriffssteuerung für die Objekte Ihres Buckets aus.
      Hinweis: Sie können die Einstellung Öffentlichen Zugriff verhindern nicht ändern, wenn diese Einstellung durch eine Organisationsrichtlinie erzwungen wird.
   5. Gehen Sie im Bereich Art des Schutzes der Objektdaten wählen so vor:
      • Wählen Sie eine der Optionen unter Datenschutz aus, die Sie für Ihren Bucket festlegen möchten.
        • Wenn Sie das vorläufige Löschen aktivieren möchten, klicken Sie das Kästchen Richtlinie für vorläufiges Löschen (zur Datenwiederherstellung) an, und geben Sie die Anzahl der Tage an, die Objekte nach dem Löschen aufbewahrt werden sollen.
        • Wenn Sie die Objektversionsverwaltung einrichten möchten, klicken Sie das Kästchen Objektversionierung (zur Versionsverwaltung) an und geben Sie die maximale Anzahl von Versionen pro Objekt und 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 das Kästchen Aufbewahrung (zur Compliance) an und gehen Sie so vor:
          • Wenn Sie die Objektaufbewahrungssperre aktivieren möchten, klicken Sie das Kästchen Objektaufbewahrung aktivieren an.
          • Wenn Sie die Bucket-Sperre aktivieren möchten, klicken Sie das Kästchen Aufbewahrungsrichtlinie für Bucket festlegen an 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 Datenverschlüsselung Bereich () und wählen Sie eine Datenverschlüsselung Methode 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 den Anforderungen für Bucket-Namen entspricht.

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Vertex AI 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) verwenden, die für Sie eingerichtet wurde.

Optional: Virtuelle Umgebung einrichten

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

Installation

Um die Anzahl der Abhängigkeiten zu minimieren, die Sie installieren müssen, haben wir die Abhängigkeiten in folgende Kategorien unterteilt:

• agent_engines: Die Gruppe der Pakete, die für die Bereitstellung in Vertex AI Agent Engine erforderlich sind.
• adk: Die Gruppe der kompatiblen Agent Development Kit-Pakete.
• langchain: Die Gruppe der kompatiblen LangChain- und LangGraph-Pakete.
• ag2: Die Gruppe der kompatiblen AG2-Pakete.
• llama_index: Die Gruppe der kompatiblen LlamaIndex-Pakete.

Beim Installieren des Vertex AI SDK für Python können Sie die erforderlichen Abhängigkeiten angeben (durch Kommas getrennt). So installieren Sie alle:

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

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

pip install a2a-sdk>=0.3.4

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 Vertex AI Agent Engine 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:

• PROJECT_ID ist die Google Cloud Projekt-ID, unter der Sie Agents entwickeln und bereitstellen, und
• LOCATION ist eine der unterstützten Regionen.

Nächste Schritte

• Agent entwickeln.
• Probleme beim Einrichten einer Umgebung beheben.
• Support anfordern.