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 Terraform-Beispiel zur Optimierung der Einrichtung und Bereitstellung der Vertex AI Agent Engine-Umgebung finden Sie im Agent-Starter-Pack.

Mit Google Cloudeinrichten

Sie können Google Cloud für Vertex AI Agent Engine einrichten, indem Sie ein Google Cloud -Projekt erstellen oder sich für Vertex AI im Expressmodus registrieren:

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:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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, and Cloud Trace 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, and Cloud Trace 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 Berechtigung serviceusage.services.enable. Wenn Sie diese Berechtigung nicht haben, bitten Sie Ihren Administrator, Ihnen die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) zuzuweisen.

Expressmodus

Folgen Sie der Anleitung unter Vertex AI im Express-Modus, um Vertex AI Agent Engine im Express-Modus einzurichten.

Nachdem Sie Vertex AI Agent Engine im Express-Modus eingerichtet haben, können Sie mit dem Schritt Vertex AI SDK für Python installieren und initialisieren fortfahren.

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 für die Verwendung 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 den Agent einrichten

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

• Agent-Identität (empfohlen) (Vorabversion): Verwenden Sie die IAM-Agent-Identität (Identity Access Management), um Sicherheits- und Zugriffsverwaltungsfunktionen zu nutzen, wenn Sie Agents in der Vertex AI Agent Engine-Laufzeit verwenden. Die Identität des Kundenservicemitarbeiters ist an jeden einzelnen Kundenservicemitarbeiter 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-Dienst-Agent. Dieses von Google verwaltete Dienstkonto hat die Rolle Vertex AI Reasoning Engine-Dienst-Agent (roles/aiplatform.reasoningEngineServiceAgent), die die Standardberechtigungen enthält, die für bereitgestellte Agents erforderlich sind.
  • Benutzerdefiniertes Dienstkonto:Sie können ein eigenes Dienstkonto für die Agents angeben. So haben Sie mehr Kontrolle über die Berechtigungen, die den Agents gewährt werden.

Agent-Identität

Vorschau

Diese Funktion unterliegt den Bedingungen für Pre‑GA-Angebote im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Wenn Sie IAM-Richtlinien vor der Bereitstellung des Agents einrichten möchten, können Sie eine Agent-Identität erstellen, ohne den Agent-Code bereitzustellen. Erstellen Sie dazu eine Agent Engine-Instanz mit nur dem Feld identity_type:

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

Nachdem Sie die Agent Engine-Instanz mit der Agent-Identität erstellt haben, haben Sie folgende Möglichkeiten:

1. Stellen Sie die Agent-Identität mit den folgenden empfohlenen Rollen bereit:

   • roles/aiplatform.expressUser: Zugriff auf die Ausführung von Inferenz, Sitzungen und Arbeitsspeicher gewähren.

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

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

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

Standard-Service-Agent

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

Wenn Ihr Agent Berechtigungen benötigt, die über den Standardsatz 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. Klicken Sie dazu auf die Schaltfläche „Bearbeiten“ und dann auf die Schaltfläche „Speichern“.

Standard-Dienst-Agent manuell generieren

Der Reasoning Engine Service Agent wird zwar bei der Bereitstellung der 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 Abschnitt Hauptkonten hinzufügen im Feld Neue Hauptkonten [e-mail] ein.

4. Suchen Sie im Bereich Rollen zuweisen nach den benötigten 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 erteilen. Ihr benutzerdefiniertes Dienstkonto benötigt wahrscheinlich die Rolle Vertex AI-Nutzer (roles/aiplatform.user).

1. Wenn Sie kein Dienstkonto haben, erstellen Sie eins. 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 Agenten 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 in dem Projekt, in dem sich das Dienstkonto befindet, als auch in dem Projekt erforderlich, in dem Sie den Agent bereitstellen.

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

2. Vertex AI-Dienst-Agent Berechtigungen erteilen: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 Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) zu.

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

• Aus Quelldateien bereitstellen: Der Agent ist als Datei vorhanden. Mit dem Vertex AI SDK für Python können diese Dateien direkt gebündelt und in den Bereitstellungsdienst hochgeladen werden. Ein Cloud Storage-Staging-Bucket ist also nicht erforderlich.

• Über 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 Staging-Bereich für den Bereitstellungsdienst dient.

Über Quelldateien bereitstellen

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

Über Objekt bereitstellen

Wenn Sie über ein 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 im selben 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.

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets

Click Create.

On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.

1. In the Get started section, do the following:
   • Enter a globally unique name that meets the bucket naming requirements.
   • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
2. In the Choose where to store your data section, do the following:
   1. Select a Location type.
   2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
      • If you select the dual-region location type, you can also choose to enable turbo replication by using the relevant checkbox.
   3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

      Set up cross-bucket replication

      1. In the Bucket menu, select a bucket.

      2. In the Replication settings section, click Configure to configure settings for the replication job.

         The Configure cross-bucket replication pane appears.

         • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
         • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
         • Click Done.
3. In the Choose how to store your data section, do the following:
   1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
   2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
      Note: You cannot enable hierarchical namespace in existing buckets.
4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
   Note: You cannot change the Prevent public access setting if this setting is enforced at an organization policy.
5. In the Choose how to protect object data section, do the following:
   • Select any of the options under Data protection that you want to set for your bucket.
     • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
     • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
     • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
       • To enable Object Retention Lock, click the Enable object retention checkbox.
       • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
   • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.

Click Create.

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 Laufzeitumgebung, in der die Umgebung für Sie eingerichtet wurde) verwenden.

(Optional) Virtuelle Umgebung einrichten

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

Installation

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

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

Wenn Sie das Vertex AI 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) in Agent Engine verwenden möchten, müssen Sie auch das a2a-sdk-Paket 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

Expressmodus

Wenn Sie Vertex AI im Express-Modus verwenden, sind keine Maßnahmen erforderlich.

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.
• LOCATION ist eine der unterstützten Regionen.

Expressmodus

Wenn Sie Vertex AI im Express-Modus verwenden, führen Sie den folgenden Code aus:

import vertexai
from vertexai import agent_engines # For the prebuilt ADK template

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY"
)

Dabei ist API_KEY der API-Schlüssel, den Sie zur Authentifizierung des Agents verwenden.

Nächste Schritte

• Agent entwickeln.
• Fehlerbehebung beim Einrichten einer Umgebung
• Support anfordern