A2A-Agents in Cloud Run hosten – Übersicht

In diesem Leitfaden finden Sie eine Übersicht darüber, wie Sie Agent2Agent-Agents (A2A) für die Bereitstellung in Cloud Run vorbereiten und konfigurieren. Darin werden wichtige Schritte wie das Einrichten einer Cloud-Umgebung, das Konfigurieren der erforderlichen IAM-Rollen (Identity and Access Management) und das Vorbereiten Ihres Agents für die Bereitstellung behandelt.

Hinweise

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

Roadmap für die A2A-Agent-Bereitstellung

Führen Sie die folgenden Schritte aus, um Ihren Agent bereitzustellen:

Gesamtarchitektur

Das Herzstück des A2A-Agents ist eine Serving- und Orchestrierungsebene wie Cloud Run. Diese Ebene verwaltet die Interaktionen mit KI-Modellen wie Gemini und Vertex AI, Speichern wie AlloyDB und A2A TaskStore sowie externen Tools über APIs. Clients interagieren mit dem Agent, indem sie Anfragen wie „Get Agent Card“ (Agent-Karte abrufen) oder „send message“ (Nachricht senden) senden und Aufgabenaktualisierungen erhalten.

Das folgende Diagramm veranschaulicht die Architektur eines A2A-Agentsystems, in dem ein A2A-Client (Nutzer oder Agent) mit dem A2A-Agent interagiert.

A2A-Agent-Architektur, die die Clientinteraktion mit dem Agent über eine Bereitstellungs- und Orchestrierungsebene zeigt.
A2A-Agent-Architektur

Informationen zum Lebenszyklus von A2A-Anfragen finden Sie im Abschnitt Lebenszyklus von A2A-Anfragen.

IAM-Rollen und -Berechtigungen für Cloud Run A2A-Agents

Richtig konfigurierte IAM-Rollen sind wichtig, damit Ihr Cloud Run-Dienst sicher mit anderen Google Cloud-Diensten interagieren kann. Erstellen Sie ein dediziertes Dienstkonto und erteilen Sie die in den folgenden Abschnitten aufgeführten spezifischen Berechtigungen, um die Betriebssicherheit und Effizienz zu gewährleisten.

Cloud Run-Dienstkonto erstellen

Bevor Sie gcloud-Befehle ausführen, müssen Sie sich authentifizieren. Führen Sie den folgenden Befehl aus, um sich in Ihrem Google Cloud Konto anzumelden:

gcloud auth login

Erstellen Sie ein Dienstkonto speziell für Ihre bereitgestellte A2A-Dienstinstanz. Führen Sie den Befehl gcloud iam service-accounts create aus.

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

A2A_SERVICE_ACCOUNT_NAME durch den Namen des Dienstkontos ersetzen.

IAM-Rollen für den A2A-Agent konfigurieren

Weisen Sie Ihrem Dienstkonto die folgenden IAM-Rollen zu, je nachdem, mit welchen Google CloudDiensten Ihr A2A-Agent interagiert:

Secret Manager-Zugriff für sichere Anmeldedaten

  • Rolle:Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • Zweck:Ermöglicht dem Cloud Run-Dienstkonto, Secrets wie Datenbankanmeldedaten sicher aus Secret Manager abzurufen.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Vertex AI-Modellzugriff für KI-Funktionen

  • Rolle:Vertex AI User (roles/aiplatform.user)

  • Zweck:Erforderlich, damit das Cloud Run-Dienstkonto Vorhersage-APIs für Vertex AI-Modelle aufrufen kann.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

AlloyDB-Instanzzugriff für persistenten Speicher (falls zutreffend)

  • Rollen:AlloyDB Client (roles/alloydb.client) und Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • Zweck:Ermöglicht der Cloud Run-Dienstidentität die Interaktion mit dem AlloyDB-Cluster für die dauerhafte Speicherung von Aufgaben, was für A2A-Agents in der Produktion von entscheidender Bedeutung ist.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

A2A-Agent für 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 vorzubereiten und so einen sicheren, effizienten und skalierbaren Betrieb in der Cloud zu gewährleisten.

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.

Sie können beispielsweise Datenbanknutzer- und Passwortgeheimnisse in Google Secret Manager mit der gcloud-Befehlszeile erstellen und verwalten. Weitere Informationen finden Sie unter Secret erstellen.

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"

Dockerfile für die Containerisierung erstellen

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 folgende Beispiel zeigt ein Dockerfile für die Bereitstellung eines A2A-Agents:

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.

Nächste Schritte