Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

A2A-Agents in Cloud Run bereitstellen

Bereiten Sie Agent2Agent-Agenten (A2A) für die Bereitstellung in Cloud Run vor und konfigurieren Sie sie.

In dieser Anleitung werden die wichtigsten Schritte für die Bereitstellung von A2A-Agenten beschrieben:

Projekt konfigurieren
IAM-Rollen einrichten
Cloud-Umgebung konfigurieren
Agent bereitstellen
Fehlerbehebung bei Bereitstellungsfehlern
Testen und beobachten

A2A-Spezifikation und Beispiel-Agenten ansehen

Bevor Sie mit der Entwicklung und Bereitstellung Ihres A2A-Agenten beginnen, sollten Sie sich mit den folgenden Konzepten und Ressourcen vertraut machen:

Lesen Sie die offizielle A2A-Spezifikation und Konzepte für die Agentenkommunikation.
Sehen Sie sich vorhandene Beispiel-Agenten an.
Sehen Sie sich das ADK-Cloud Run-Beispiel an.

Hinweis

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Google Cloud, Konto haben, erstellen Sie eines, 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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

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

Verify that billing is enabled for your Google Cloud project.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Standardmäßig empfehlen wir, Ihrem Agenten eine sichere, vom System verwaltete Agentenidentität zuzuweisen. Übergeben Sie dazu bei der Bereitstellung die --functional-type=agent und --identity-type=agent-identity Flags. Eine Anleitung finden Sie unter Funktionen der Agentenplattform konfigurieren. Wenn Sie Ihren Agenten mit einem Standarddienstkonto bereitstellen müssen, können Sie ein nutzerverwaltetes Dienstkonto erstellen und bei der Bereitstellung das Flag --service-account übergeben.

Dienstkonto Rollen zuweisen

So weisen Sie Ihrem Konto in Ihrem Projekt die erforderlichen IAM-Rollen zu:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

Ersetzen Sie:

PROJECT_ID: Ihre Projekt-ID
A2A_SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos
ROLE: die Rolle, die Sie dem Dienstkonto hinzufügen

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Bereitstellen von A2A-Agenten benötigen:

Cloud Run Source Developer (roles/run.sourceDeveloper) für das Projekt
Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin) für das Projekt
Secret Manager-Administrator (roles/secretmanager.admin) für das Projekt
Dienstkontonutzer (roles/iam.serviceAccountUser) für die Dienstidentität
Zugriffsperson für Secret Manager-Secret (roles/secretmanager.secretAccessor) für das Dienstkonto
Vertex AI User (roles/aiplatform.user) für das Dienstkonto
Wenn Sie mit AlloyDB for PostgreSQL bereitstellen, weisen Sie die folgenden Rollen zu:
- AlloyDB for PostgreSQL-Client (roles/alloydb.client) für das Dienstkonto
- Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin) für das Dienstkonto

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.

Rollen zuweisen

Console

Rufen Sie in der Google Cloud Console die Seite IAM auf.
IAM aufrufen
Wählen Sie das Projekt aus.
Klicken Sie auf Zugriffsrechte erteilen.
Geben Sie im Feld Neue Hauptkonten Ihre Nutzer-ID ein. In der Regel ist das die E-Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.
Wählen Sie in der Liste Rolle auswählen eine Rolle aus.
Klicken Sie auf Weitere Rolle hinzufügen, wenn Sie weitere Rollen zuweisen möchten.
Klicken Sie auf Speichern.

gcloud

So weisen Sie Ihrem Konto in Ihrem Projekt die erforderlichen IAM-Rollen zu:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

Ersetzen Sie:

PROJECT_NUMBER durch Ihre Google Cloud Projekt nummer.
PROJECT_ID durch Ihre Google Cloud Projekt-ID.
PRINCIPAL durch das Konto, für das Sie die Bindung hinzufügen. In der Regel ist das die E-Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.
ROLE durch die Rolle, die Sie dem Konto des Bereitstellers hinzufügen.

Auf die Cloud Run-Bereitstellung vorbereiten

In diesem Abschnitt werden die Konfigurationen beschrieben, die erforderlich sind, um Ihren A2A-Agenten für die Bereitstellung in Cloud Run für ein Python-Codebeispiel vorzubereiten.

A2A-Agent vorbereiten

Rufen Sie das Codebeispiel ab, indem Sie das Repository der Beispiel-App auf Ihren lokalen Computer klonen:
```
git clone https://github.com/a2aproject/a2a-samples
```
Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:
```
cd a2a-samples/samples/python/agents/adk_cloud_run
```

Secrets für Cloud Run-Dienste konfigurieren

Geben Sie alle sensiblen Anmeldedaten wie API-Schlüssel und Datenbankpasswörter über einen sicheren Mechanismus an Ihren A2A-Server weiter. Cloud Run unterstützt die Bereitstellung von Secrets als Umgebungsvariablen oder dynamisch bereitgestellte Volumes. Weitere Informationen finden Sie unter Secrets in Cloud Run konfigurieren.

Agenten benötigen Zugriff auf externe Dienste, um ihre Aufgaben zu erledigen. Secrets sind der sichere Mechanismus, um diesen Zugriff zu gewähren. Bei der Bereitstellung mit AlloyDB for PostgreSQL benötigen Sie den Nutzer und das Passwort. Erstellen und verwalten Sie die Secrets für Datenbanknutzer und ‑passwörter im Secret Manager, indem Sie die folgenden Befehle in der gcloud CLI ausführen:

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

Weitere Informationen finden Sie unter Secret erstellen.

Dockerfile für die Containerisierung

Cloud Run kann Dienste entweder aus bereits gehosteten Container-Images oder direkt aus Ihrem Quellcode bereitstellen. Wenn Sie aus Quellcode bereitstellen, erstellt Cloud Run automatisch ein Container-Image, wenn sich im Stammverzeichnis Ihres Projekts ein Dockerfile befindet.

Das Dockerfile bestimmt die Details des Container-Images. Das folgende Dockerfile stammt vom Beispiel-A2A-Agenten, den Sie zuvor geklont haben:

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

Aus Quellcode ohne Dockerfile bereitstellen

Für Quellcode-Repositories ohne Dockerfile bietet Cloud Run integrierte Unterstützung für bestimmte gängige Programmiersprachen, wodurch der Containerisierungsprozess vereinfacht wird.

Python-Anwendungen in Cloud Run: Cloud Run sucht nach einer main.py Datei, um Python-Dienste zu erstellen und bereitzustellen. Weitere Informationen finden Sie in der Kurzanleitung Python-Dienst in Cloud Run bereitstellen.
Node.js-Anwendungen in Cloud Run:Cloud Run sucht nach einer index.js-Datei, um Node.js-Dienste zu erstellen und bereitzustellen. Weitere Informationen finden Sie in der Kurzanleitung Node.js-Dienst in Cloud Run bereitstellen.

A2A-Agent in Cloud Run bereitstellen

Informationen zum Zuweisen einer vom System verwalteten Identität zu Ihrem A2A-Agenten und zum Registrieren in der Agent Platform finden Sie unter Funktionen der Agentenplattform für Cloud Run konfigurieren.

Stellen Sie Ihre A2A-Anwendung mit einer TaskStore-Konfiguration im Arbeitsspeicher oder mit AlloyDB for PostgreSQL bereit.

Bei einer TaskStore-Konfiguration im Arbeitsspeicher werden alle Daten ausschließlich in der Cloud Run-Containerinstanz gespeichert. Das bedeutet, dass alle Aufgabendaten verloren gehen, wenn die Containerinstanz heruntergefahren, skaliert oder neu gestartet wird.
AlloyDB for PostgreSQL bietet Datenpersistenz, ermöglicht die horizontale Skalierung von Agenten und sorgt dafür, dass Aufgaben Containerneustarts, Skalierungsereignisse und Bereitstellungen überstehen.

Eine TaskStore-Konfiguration im Arbeitsspeicher eignet sich für die Entwicklung von A2A-Agenten in der lokalen Umgebung und AlloyDB for PostgreSQL für die Skalierung des A2A-Agenten in der Produktion.

Die folgenden Befehle zeigen, wie Sie die IAM-basierte Authentifizierung für Ihren Cloud Run-Dienst verwenden. Die Verwendung des --no-allow-unauthenticated Flags bei der Bereitstellung ist der empfohlene Ansatz zum Konfigurieren der Authentifizierung für interne Google Cloud Clients wie Gemini Enterprise.

Wenn Ihr A2A-Server für den öffentlichen Zugriff konzipiert ist und die Authentifizierung auf Agentenebene verarbeiten muss, können Sie bei der Bereitstellung das Flag --allow-unauthenticated angeben. Weitere Informationen finden Sie unter Authentifizierung für öffentlichen Zugriff auf Cloud Run. Um den öffentlichen Zugriff auf Ihren Cloud Run-Dienst zu ermöglichen, müssen Sie außerdem wichtige Authentifizierungsinformationen in der Karte Ihres A2A-Agenten mit den Parametern securitySchemes und security angeben. Weitere Informationen finden Sie unter A2A-Spezifikation: Details zum SecurityScheme-Objekt.

Mit einer `TaskStore`-Konfiguration im Arbeitsspeicher bereitstellen

Führen Sie den folgenden Befehl in dem Verzeichnis aus, das den Quellcode Ihres A2A-Agenten enthält, um Ihren A2A-Agenten mit einer TaskStore-Konfiguration im Arbeitsspeicher bereitzustellen:

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --functional-type=agent \
    --identity-type=agent-identity \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

Ersetzen Sie Folgendes:

REGION: die Google Cloud Region, in der Sie Ihren Dienst bereitstellen möchten, z. B. europe-west1.
PROJECT_ID: Ihre Projekt-ID.
PROJECT_NUMBER: Ihre Projektnummer.

Mit AlloyDB for PostgreSQL bereitstellen

Verwenden Sie AlloyDB for PostgreSQL, um A2A-Aufgaben zu speichern. Verwenden Sie den folgenden Befehl, um Ihren A2A-Agenten mit AlloyDB for PostgreSQL für die persistente Aufgabenspeicherung bereitzustellen:

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --functional-type=agent \
    --identity-type=agent-identity \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

Ersetzen Sie Folgendes:

REGION: die Google Cloud Region, in der Sie Ihren Dienst bereitstellen möchten, z. B. europe-west1.
PROJECT_ID: Ihre Projekt-ID.
PROJECT_NUMBER: Ihre Projektnummer.
CLUSTER_NAME: der Name Ihres AlloyDB for PostgreSQL -Clusters.

Fehlerbehebung bei Bereitstellungsfehlern

Wenn Fehler oder Cloud Run-Bereitstellungsfehler auftreten, beachten Sie Folgendes:

Detaillierte Logs:Wenn Sie detaillierte Bereitstellungslogs benötigen, legen Sie das Flag --verbosity=info in Ihrem Befehl gcloud run deploy fest.
URL-Konflikt: Wenn sich die run.app von dem Bereitstellungsbefehl zurückgegebene URL von der erwarteten deterministischen URL unterscheidet, aktualisieren Sie die APP_URL Umgebungsvariable für Ihren Cloud Run-Dienst:
1. Verwenden Sie den folgenden Befehl, um die Umgebungsvariable APP_URL zu aktualisieren:
```
gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"
```
  Ersetzen Sie Folgendes:
  - SERVICE_NAME: der Name Ihres Cloud Run Dienstes.
  - PROJECT_ID: Ihre Projekt-ID.
  - REGION: die Google Cloud Region, in der Sie Ihren Dienst bereitstellen möchten. Beispiel: europe-west1.
  - CLOUD_RUN_SERVICE_URL: die URL Ihres Cloud Run-Dienstes.
2. Prüfen Sie, ob APP_URL korrekt aktualisiert wurde, indem Sie den Dienst beschreiben:
```
gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"
```

Informationen zur Cloud Run-Anwendungs-URL

Nach der erfolgreichen Bereitstellung stellt Cloud Run automatisch eine run.app -URL bereit, die als Endpunkt für Abfragen Ihres aktiven A2A-Dienstes dient. Die URL ist deterministisch und vorhersehbar, wenn Ihr Dienstname kurz genug ist.

Cloud Run-URL-Format https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
Beispiel-URL:https://sample-a2a-agent-1234.europe-west1.run.app

Bereitstellung von A2A-Agenten testen und beobachten

Nachdem Sie Ihren A2A-Agenten erfolgreich in Cloud Run bereitgestellt haben, testen Sie seine Funktionalität gründlich. Richten Sie ein umfassendes Monitoring ein, um eine kontinuierliche Leistung und Zuverlässigkeit zu gewährleisten.

A2A-Prüftool: Agentenkonformität prüfen

Mit dem Tool a2a-inspector können Sie Ihren bereitgestellten Google A2A-Agenten prüfen, Fehler beheben und validieren. Dieses Tool sorgt dafür, dass Ihr Agent vollständig der A2A-Spezifikation entspricht und korrekt funktioniert.

Nach einer erfolgreichen Verbindung führt das Prüftool die folgenden Aktionen aus:

Agentenkarte anzeigen:Zeigt automatisch die Karte Ihres Agenten an.
Konformität prüfen:Prüft, ob die Karte den A2A-Spezifikationen entspricht.
Live-Chat aktivieren:Ermöglicht das Senden und Empfangen von Nachrichten mit dem Agenten.
Rohdaten anzeigen:Zeigt Rohdaten im JSON-RPC 2.0-Format in einer Konsole zur Fehlerbehebung an.

CLI-Interaktion mit einem bereitgestellten A2A-Agenten

Verwenden Sie die Befehlszeilentools aus dem A2A-Beispiel-Repository um mit Ihrem bereitgestellten Dienst zu interagieren. Diese CLI unterstützt die Authentifizierung auf Basis von Bearertokens.

Wenn Ihr Dienst die IAM-basierte Authentifizierung verwendet, exportieren Sie das gcloud-Token für eine erfolgreiche Interaktion:

export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

Ersetzen Sie CLOUD_RUN_SERVICE_URL durch die URL Ihres bereitgestellten Cloud Run-Dienstes.

Hinweis: Nach der erfolgreichen Bereitstellung und dem Aufruf wird die Agentenkarte angezeigt, eine neue Aufgabe wird gestartet und Sie werden zur Eingabe aufgefordert. Jedes Ereignis in der CLI enthält Details wie die Aufgaben-ID, den Status und den Zeitstempel.

Lokales Testen bereitgestellter A2A-Dienste

Sie können Ihren bereitgestellten Cloud Run-Dienst lokal testen. Dies ist besonders nützlich bei der Implementierung der IAM-basierten Authentifizierung.

IAM-basierte Authentifizierung für Cloud Run-Agenten testen

Clients, die mit Ihrem durch Identity and Access Management (IAM) geschützten Cloud Run-Dienst interagieren, müssen die IAM-Rolle roles/run.invoker haben.

Testen Sie den Authentifizierungsablauf Ihres bereitgestellten Dienstes lokal mit dem Befehl gcloud auth print-identity-token:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json