A2A-Agents in Cloud Run bereitstellen

In diesem Dokument wird beschrieben, wie Sie Ihren A2A-Agent in Cloud Run bereitstellen. Diese Schritte sorgen für einen sicheren, effizienten und skalierbaren Betrieb in der Cloud-Umgebung.

Hinweise

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

Install the 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 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 (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.

Install the 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 folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

1. Wechseln Sie in das Verzeichnis, das den Quellcode Ihres A2A-Agents enthält:

     cd PATH_TO_YOUR_AGENT_DIRECTORY
     

2. Informationen zu den erforderlichen IAM-Rollen und ‑Berechtigungen finden Sie unter IAM-Rollen und ‑Berechtigungen für Cloud Run A2A-Agents.

Authentifizierung für Cloud Run-Dienste konfigurieren

Nachdem Ihr A2A-Agent vollständig entwickelt und seine Bereitstellungsumgebung vorbereitet wurde, müssen Sie die Authentifizierung konfigurieren und den Befehl gcloud run deploy verwenden, um den Agent in Cloud Run bereitzustellen.

Verwenden Sie eine der folgenden Optionen, um den Zugriff und die Authentifizierung für Ihren A2A Cloud Run-Dienst zu konfigurieren:

• IAM-basierte Authentifizierung für interne Google Cloud Clients:Für Clients, die in Google Cloudbetrieben werden, z. B. interne Dienste wie Agentspace, ist die IAM-basierte Authentifizierung der empfohlene sichere Ansatz. Diese Clients verwenden Dienstkonten und benötigen die Rolle „Cloud Run Invoker“ (roles/run.invoker), um Ihren Cloud Run-Dienst aufzurufen. Weitere Informationen finden Sie unter Dienst-zu-Dienst-Authentifizierung für Cloud Run.

  So aktivieren Sie die IAM-basierte Authentifizierung für Ihren Cloud Run-Dienst:

  • Sie müssen das Flag --no-allow-unauthenticated bei der Bereitstellung verwenden.

• Authentifizierung auf Agent-Ebene für die öffentliche Nutzung:Wenn Ihr A2A-Server für den öffentlichen Zugriff konzipiert ist, wird die Authentifizierung auf Agent-Ebene verarbeitet.

  So lassen Sie öffentlichen Zugriff auf Ihren Cloud Run-Dienst zu:

  • Sie müssen wichtige Authentifizierungsinformationen auf der Karte Ihres A2A-Agents mit den Parametern securitySchemes und security angeben. Weitere Informationen finden Sie unter A2A Specification: SecurityScheme Object Details.
  • Verwenden Sie das Flag --allow-unauthenticated während der Bereitstellung. Weitere Informationen dazu, wie Sie öffentlichen Zugriff auf Ihren Cloud Run-Dienst zulassen, finden Sie unter Authentifizierung für öffentlichen Zugriff auf Cloud Run.

A2A-Agent in Cloud Run bereitstellen

Verwenden Sie das vorhandene ADK-Beispiel, um Ihren A2A-Agent bereitzustellen. Geben Sie die folgenden Parameter an, wenn Sie den Befehl gcloud run deploy verwenden:

• Zugriffskonfiguration:
  • Wenn Sie die IAM-basierte Dienstauthentifizierung verwenden möchten, fügen Sie das Flag --no-allow-unauthenticated hinzu.
  • Verwenden Sie das Flag --allow-unauthenticated, um die Dienste im Internet öffentlich zu machen.
• Arbeitsspeicher: Die Mindestanforderung an den Arbeitsspeicher für die Ausführung der Containerinstanz beträgt 1Gi.
• Secrets: Wenn Sie Secrets verwenden möchten, geben Sie die Parameter DB_USER und DB_PASS an.
• Dienstkonto: Verwenden Sie den Parameter a2a-service-account, um ein Dienstkonto anzugeben.
• Umgebungsvariablen: Verwenden Sie die folgenden Variablen, um Umgebungsvariablen anzugeben:
  • APP_URL
  • DB_INSTANCE
  • DB_NAME
  • GOOGLE_GENAI_USE_VERTEXAI = true

Verwenden Sie für lokale Tests eine TaskStore-Konfiguration im Speicher. Wenn Sie Ihren Dienst in der Produktion bereitstellen möchten, müssen Sie nichtflüchtigen Speicher für einen Produktions-A2A-Server verwenden. Ein Beispiel finden Sie im Abschnitt AlloyDB for PostgreSQL-Bereitstellung.

Mit einer In-Memory-TaskStore-Konfiguration bereitstellen

Verwenden Sie den folgenden gcloud run deploy-Befehl, um Ihren A2A-Agent mit einer In-Memory-TaskStore-Konfiguration bereitzustellen:

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

Wenn Sie sich nicht in dem Verzeichnis befinden, das den Quellcode Ihres A2A-Agents enthält, aktualisieren Sie das Flag --source mit dem vollständigen Pfad zu Ihrem Agent-Code.

Ersetzen Sie Folgendes:

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

Mit AlloyDB for PostgreSQL bereitstellen

Verwenden Sie AlloyDB for PostgreSQL, um A2A-Aufgaben beizubehalten. Wenn Sie Ihren A2A-Agent mit AlloyDB for PostgreSQL für die persistente Speicherung von Aufgaben bereitstellen möchten, verwenden Sie den folgenden gcloud run deploy-Befehl:

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 \
    --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"

Wenn Sie sich nicht in dem Verzeichnis befinden, das den Quellcode Ihres A2A-Agents enthält, aktualisieren Sie das Flag --source mit dem vollständigen Pfad zu Ihrem Agent-Code.

Ersetzen Sie Folgendes:

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

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

Bereitstellungsfehler beheben

Bei der Fehlerbehebung bei Cloud Run-Bereitstellungsfehlern 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.

• Falsche URL: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"