Esegui il deployment degli agenti A2A in Cloud Run

Questo documento descrive come eseguire il deployment dell'agente A2A su Cloud Run. Questi passaggi garantiscono un funzionamento sicuro, efficiente e scalabile nell'ambiente cloud.

Prima di iniziare

  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.

    Go to project selector

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

  4. Install the Google Cloud CLI.

  5. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla gcloud CLI con la tua identità federata.

  6. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

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

  9. Install the Google Cloud CLI.

  10. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla gcloud CLI con la tua identità federata.

  11. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init
  12. Vai alla directory che contiene il codice sorgente dell'agente A2A:

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. Per i ruoli e le autorizzazioni IAM richiesti, consulta Ruoli e autorizzazioni IAM per gli agenti Cloud Run A2A.

    14. Configura l'autenticazione del servizio Cloud Run

    Dopo aver sviluppato completamente l'agente A2A e preparato il relativo ambiente di deployment, devi configurare l'autenticazione e utilizzare il comando gcloud run deploy per eseguire il deployment dell'agente in Cloud Run.

    Utilizza una delle seguenti opzioni per configurare l'accesso e l'autenticazione per il tuo servizio Cloud Run A2A:

    • Autenticazione basata su IAM per i client Google Cloud interni: Per i client che operano all'interno di Google Cloud, come i servizi interni come Agentspace, l'autenticazione basata su IAM è l'approccio sicuro consigliato. Questi client utilizzano service account e richiedono il ruolo Cloud Run Invoker (roles/run.invoker) per richiamare il servizio Cloud Run. Per saperne di più, consulta Autenticazione da servizio a servizio di Cloud Run.

      Per attivare l'autenticazione basata su IAM per il tuo servizio Cloud Run:

      • Devi utilizzare il flag --no-allow-unauthenticated durante il deployment.

    • Autenticazione a livello di agente per l'esposizione pubblica: se il tuo server A2A è progettato per l'accesso pubblico, gestisce l'autenticazione a livello di agente.

      Per consentire l'accesso pubblico al servizio Cloud Run:

    Esegui il deployment dell'agente A2A in Cloud Run

    Utilizza l'esempio di ADK esistente per eseguire il deployment dell'agente A2A. Specifica i seguenti parametri quando utilizzi il comando gcloud run deploy:

    • Configurazione dell'accesso:
      • Per utilizzare l'autenticazione del servizio basata su IAM, utilizza il flag --no-allow-unauthenticated.
      • Per rendere pubblici i servizi su internet, utilizza il flag --allow-unauthenticated.
    • Memoria: il requisito di memoria minimo per l'esecuzione dell'istanza del container è 1Gi.
    • Secret: per utilizzare i secret, specifica i parametri DB_USER e DB_PASS.
    • Service account: per specificare un account di servizio, utilizza il parametro a2a-service-account.
    • Variabili di ambiente: per specificare le variabili di ambiente, utilizza le seguenti variabili:
      • APP_URL
      • DB_INSTANCE
      • DB_NAME
      • GOOGLE_GENAI_USE_VERTEXAI = true

    Per i test locali, utilizza una configurazione TaskStore in memoria. Per il deployment del servizio in produzione, devi utilizzare l'archiviazione permanente per un server A2A di produzione. Vedi un esempio nella sezione Deployment di AlloyDB per PostgreSQL.

    Esegui il deployment con una configurazione TaskStore in memoria

    Per eseguire il deployment dell'agente A2A con una configurazione TaskStore in memoria, utilizza il seguente comando gcloud run deploy:

    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"

    Se non ti trovi nella directory che contiene il codice sorgente dell'agente A2A, aggiorna il flag --source con il percorso completo del codice dell'agente.

    Sostituisci quanto segue:

    • REGION: la regione Google Cloud in cui vuoi eseguire il deployment del servizio. Ad esempio europe-west1.
    • PROJECT_ID: il tuo ID progetto.
    • PROJECT_NUMBER: il numero di progetto.

    Esegui il deployment con AlloyDB per PostgreSQL

    Per rendere persistenti le attività A2A, utilizza AlloyDB per PostgreSQL. Per eseguire il deployment dell'agente A2A con AlloyDB per PostgreSQL per l'archiviazione persistente delle attività, utilizza il seguente comando gcloud run deploy:

    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"

    Se non ti trovi nella directory che contiene il codice sorgente dell'agente A2A, aggiorna il flag --source con il percorso completo del codice dell'agente.

    Sostituisci quanto segue:

    • REGION: la regione Google Cloud in cui vuoi eseguire il deployment del servizio. Ad esempio europe-west1.
    • PROJECT_ID: il tuo ID progetto.
    • PROJECT_NUMBER: il numero di progetto.
    • CLUSTER_NAME: il nome del cluster AlloyDB per PostgreSQL.

    Informazioni sull'URL dell'applicazione Cloud Run

    In caso di deployment riuscito, Cloud Run fornisce automaticamente un URL run.app che funge da endpoint per eseguire query sul servizio A2A attivo. L'URL è deterministico e prevedibile se il nome del servizio è sufficientemente breve.

    • Formato URL di Cloud Run: https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
    • URL di esempio: https://sample-a2a-agent-1234.europe-west1.run.app

    Eseguire il debug degli errori di deployment

    Per eseguire il debug degli errori di deployment di Cloud Run, considera quanto segue:

    • Log dettagliati:per i log di deployment dettagliati, imposta il flag --verbosity=info nel comando gcloud run deploy.

    • Mancata corrispondenza dell'URL:se l'URL run.app restituito dal comando di deployment differisce dall'URL deterministico previsto, aggiorna la variabile di ambiente APP_URL per il servizio Cloud Run:

      1. Utilizza il seguente comando per aggiornare la variabile di ambiente APP_URL:

        gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

        Sostituisci quanto segue:

        • SERVICE_NAME: il nome del tuo servizio Cloud Run.
        • PROJECT_ID: il tuo ID progetto.
        • REGION: la regione Google Cloud in cui vuoi eseguire il deployment del servizio. Ad esempio europe-west1.
        • CLOUD_RUN_SERVICE_URL: l'URL del tuo servizio Cloud Run.

      2. Verifica che APP_URL sia aggiornato correttamente descrivendo il servizio:

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