A2A-Agents in Cloud Run bereitstellen

A2A-Agents (Agent2Agent) für die Bereitstellung in Cloud Run vorbereiten und konfigurieren.

In diesem Leitfaden werden die wichtigsten Schritte zum Bereitstellen von A2A-Agenten beschrieben:

A2A-Spezifikation und Beispiel-Agents ansehen

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

Hinweise

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

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

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

  4. Install the Google Cloud CLI.

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

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

    gcloud init

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

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

  9. Install the Google Cloud CLI.

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

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

    gcloud init

  12. Führen Sie den folgenden Befehl aus, um ein Dienstkonto zu erstellen:
    13. gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

    Ersetzen Sie die folgenden Werte:

    • A2A_SERVICE_ACCOUNT_NAME: der Name des Dienstkontos

    • DESCRIPTION: Eine optionale Beschreibung des Dienstkontos.

    • DISPLAY_NAME: ein Dienstkontoname, der in der Google Cloud Console angezeigt werden soll

    Dienstkonto Rollen zuweisen

    So weisen Sie Ihrem Konto die erforderlichen IAM-Rollen für Ihr Projekt 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, damit Sie die nötigen Berechtigungen zum Bereitstellen von A2A-Agents haben:

    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

    1. Rufen Sie in der Google Cloud Console die Seite IAM auf.

      IAM aufrufen
    2. Wählen Sie das Projekt aus.
    3. Klicken Sie auf Zugriffsrechte erteilen.

    4. Geben Sie im Feld Neue Hauptkonten Ihre Nutzer-ID ein. Dies ist in der Regel die E-Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.

    5. Wählen Sie in der Liste Rolle auswählen eine Rolle aus.
    6. Wenn Sie weitere Rollen zuweisen möchten, klicken Sie auf Weitere Rolle hinzufügen und fügen Sie weitere Rollen hinzu.
    7. Klicken Sie auf Speichern.

    gcloud

    So weisen Sie Ihrem Konto die erforderlichen IAM-Rollen für Ihr Projekt zu:

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

    Ersetzen Sie:

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

    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

    1. Rufen Sie den Beispielcode ab, indem Sie das Repository der Beispiel-App auf Ihren lokalen Computer klonen:

      git clone https://github.com/a2aproject/a2a-samples

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

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

    KI-Agenten benötigen Zugriff auf externe Dienste, um ihre Aufgaben zu erledigen. Secrets sind der sichere Mechanismus zum Gewähren dieses Zugriffs. Bei der Bereitstellung mit AlloyDB for PostgreSQL benötigen Sie den Nutzer und das Passwort. Erstellen und verwalten Sie die Secrets für den Datenbanknutzer und das Passwort in 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 Dockerfile aus dem zuvor geklonten A2A-Beispielagenten sieht so aus:

    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 die Containerisierung vereinfacht wird.

    A2A-Agent in Cloud Run bereitstellen

    Stellen Sie Ihre A2A-Anwendung mit einer TaskStore-In-Memory-Konfiguration 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, sodass Agents horizontal skaliert werden können und Aufgaben Containerneustarts, Skalierungsereignisse und Bereitstellungen überstehen.

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

    Die folgenden Befehle zeigen, wie Sie die IAM-basierte Authentifizierung für Ihren Cloud Run-Dienst verwenden. Die Verwendung des Flags --no-allow-unauthenticated bei der Bereitstellung ist die empfohlene Methode 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 Agent-Ebene verarbeiten muss, können Sie das Flag --allow-unauthenticated bei der Bereitstellung angeben. Weitere Informationen finden Sie unter Authentifizierung für öffentlichen Zugriff auf Cloud Run. Damit öffentlich auf Ihren Cloud Run-Dienst zugegriffen werden kann, müssen Sie auch wichtige Authentifizierungsinformationen in der Karte Ihres A2A-Agents mit den Parametern securitySchemes und security angeben. Weitere Informationen finden Sie unter A2A Specification: SecurityScheme Object Details.

    Mit einer In-Memory-TaskStore-Konfiguration bereitstellen

    Wenn Sie Ihren A2A-Agenten mit einer In-Memory-TaskStore-Konfiguration bereitstellen möchten, führen Sie den folgenden Befehl in dem Verzeichnis aus, das den Quellcode Ihres A2A-Agenten enthält:

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --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.
    • A2A_SERVICE_ACCOUNT_NAME: der Name Ihres A2A-Dienstkontos.

    Mit AlloyDB for PostgreSQL bereitstellen

    Wenn Sie A2A-Aufgaben beibehalten möchten, verwenden Sie AlloyDB for PostgreSQL. Verwenden Sie den folgenden Befehl, um Ihren A2A-Agent mit AlloyDB for PostgreSQL für die persistente Speicherung von Aufgaben 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 \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --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.
    • A2A_SERVICE_ACCOUNT_NAME: der Name Ihres A2A-Dienstkontos.

    Bereitstellungsfehler beheben

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

    • Detaillierte Logs:Wenn Sie detaillierte Bereitstellungslogs erhalten möchten, legen Sie das Flag --verbosity=info in Ihrem gcloud run deploy-Befehl fest.

    • URL-Konflikt:Wenn sich die vom Bereitstellungsbefehl zurückgegebene run.app-URL von der erwarteten deterministischen URL unterscheidet, aktualisieren Sie die Umgebungsvariable APP_URL 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 richtig aktualisiert wurde, indem Sie den Dienst beschreiben:

        gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"

    Cloud Run-Anwendungs-URL

    Bei erfolgreicher 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

    A2A-Agenten bereitstellen und überwachen

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

    A2A-Prüftool: Agent-Compliance validieren

    Mit dem Tool a2a-inspector können Sie Ihren bereitgestellten Google A2A-Agenten prüfen, debuggen und validieren. Mit diesem Tool können Sie sicherstellen, dass Ihr Agent die A2A-Spezifikation vollständig erfüllt und korrekt funktioniert.

    Nach einer erfolgreichen Verbindung führt der Inspector die folgenden Aktionen aus:

    • Agent-Karte anzeigen:Die Karte Ihres Agenten wird automatisch angezeigt.
    • Compliance wird geprüft:Es wird geprüft, ob die Karte den A2A-Spezifikationen entspricht.
    • Livechat aktivieren:Sie können Nachrichten mit dem Kundenservicemitarbeiter senden und empfangen.
    • Rohdaten anzeigen:Rohdaten von JSON-RPC 2.0-Nachrichten werden in einer Konsole zur Fehlerbehebung angezeigt.

    CLI-Interaktion mit einem bereitgestellten A2A-Agent

    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.

    Bereitgestellte A2A-Dienste lokal testen

    Sie können Ihren bereitgestellten Cloud Run-Dienst lokal testen. Dies ist besonders nützlich, wenn Sie die IAM-basierte Authentifizierung implementieren.

    IAM-basierte Authentifizierung für Cloud Run-Agents 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

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