Esegui il deployment degli agenti A2A in Cloud Run

Prepara e configura gli agenti Agent2Agent (A2A) per il deployment su Cloud Run.

Questa guida illustra i passaggi essenziali per il deployment degli agenti A2A:

Esamina la specifica A2A e gli agenti di esempio

Prima di iniziare a sviluppare e implementare l'agente A2A, acquisisci familiarità con i seguenti concetti e risorse:

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.

    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. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a 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.

    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. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  11. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  12. Per creare un service account, esegui il comando seguente:
    13. gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

    Sostituisci i seguenti valori:

    • A2A_SERVICE_ACCOUNT_NAME: il nome del account di servizio

    • DESCRIPTION: una descrizione facoltativa del account di servizio

    • DISPLAY_NAME: un nome del account di servizio da visualizzare nella console Google Cloud

    Concedi i ruoli del account di servizio

    Per concedere i ruoli IAM richiesti al tuo account nel tuo progetto:

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

    Sostituisci:

    • PROJECT_ID: il tuo ID progetto
    • A2A_SERVICE_ACCOUNT_NAME: il nome del account di servizio
    • ROLE: il ruolo che stai aggiungendo al account di servizio

    Ruoli obbligatori

    Per ottenere le autorizzazioni necessarie per eseguire il deployment degli agenti A2A, chiedi all'amministratore di concederti i seguenti ruoli IAM:

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

    Concedi i ruoli

    Console

    1. Nella console Google Cloud , vai alla pagina IAM.

      Vai a IAM
    2. Seleziona il progetto.
    3. Fai clic su Concedi l'accesso.

    4. Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'indirizzo email utilizzato per il deployment del servizio Cloud Run.

    5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
    6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
    7. Fai clic su Salva.

    gcloud

    Per concedere i ruoli IAM richiesti al tuo account nel tuo progetto:

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

    Sostituisci:

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud .
    • PROJECT_ID con l'ID progetto Google Cloud .
    • PRINCIPAL con l'account per il quale stai aggiungendo l'associazione. In genere si tratta dell'indirizzo email utilizzato per eseguire il deployment del servizio Cloud Run.
    • ROLE con il ruolo che stai aggiungendo all'account deployer.

    Prepararsi al deployment di Cloud Run

    Questa sezione descrive le configurazioni necessarie per preparare l'agente A2A per il deployment su Cloud Run per un esempio di codice Python.

    Prepara l'agente A2A

    1. Recupera il esempio di codice clonando il repository dell'app di esempio sulla tua macchina locale:

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

    2. Passa alla directory che contiene il codice di esempio:

      cd a2a-samples/samples/python/agents/adk_cloud_run

    Configura i secret per i servizi Cloud Run

    Fornisci tutte le credenziali sensibili, come chiavi API e password del database, al tuo server A2A utilizzando un meccanismo sicuro. Cloud Run supporta la fornitura di secret come variabili di ambiente o volumi montati dinamicamente. Per saperne di più, consulta Configura i secret in Cloud Run.

    Gli agenti hanno bisogno dell'accesso a servizi esterni per completare le loro attività. I secret sono il meccanismo sicuro per concedere l'accesso. Quando esegui il deployment con AlloyDB per PostgreSQL, hai bisogno dell'utente e della password. Crea e gestisci i secret del nome utente e della password del database in Secret Manager eseguendo i seguenti comandi in gcloud CLI:

    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"

    Per saperne di più, consulta Creare un secret.

    Dockerfile per la containerizzazione

    Cloud Run può eseguire il deployment dei servizi da immagini container già ospitate o direttamente dal codice sorgente. Quando esegui il deployment dal codice sorgente, Cloud Run crea automaticamente un'immagine container se è presente un Dockerfile nella directory root del progetto.

    Il Dockerfile determina i dettagli dell'immagine container. Di seguito è riportato il Dockerfile dell'agente A2A di esempio che hai clonato in precedenza:

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

    Esegui il deployment dal codice sorgente senza un Dockerfile

    Per i repository del codice sorgente senza Dockerfile, Cloud Run offre supporto integrato per alcuni linguaggi di programmazione popolari, semplificando il processo di containerizzazione.

    Esegui il deployment dell'agente A2A in Cloud Run

    Esegui il deployment dell'applicazione A2A con una configurazione TaskStore in memoria o con AlloyDB per PostgreSQL.

    • Una configurazione TaskStore in memoria archivia tutti i dati esclusivamente all'interno dell'istanza container Cloud Run. Ciò significa che tutti i dati delle attività vengono persi quando l'istanza del contenitore viene arrestata, ridimensionata o riavviata.
    • AlloyDB per PostgreSQL fornisce la persistenza dei dati, consentendo agli agenti di scalare in orizzontale e garantendo che le attività sopravvivano ai riavvii dei container, agli eventi di scalabilità e ai deployment.

    Una configurazione TaskStore in memoria è adatta per sviluppare agenti A2A nell'ambiente locale, mentre AlloyDB per PostgreSQL è adatta per scalare l'agente A2A in produzione.

    I seguenti comandi mostrano come utilizzare l'autenticazione basata su IAM per il servizio Cloud Run. L'utilizzo del flag --no-allow-unauthenticated al momento del deployment è l'approccio consigliato per configurare l'autenticazione per i client Google Cloud interni, come Gemini Enterprise.

    Se il tuo server A2A è progettato per l'accesso pubblico e deve gestire l'autenticazione a livello di agente, puoi specificare il flag --allow-unauthenticated durante il deployment. Per ulteriori dettagli, consulta Autenticazione dell'accesso pubblico di Cloud Run. Per consentire l'accesso pubblico al servizio Cloud Run, devi anche fornire informazioni di autenticazione cruciali nella scheda dell'agente A2A utilizzando i parametri securitySchemes e security. Per saperne di più, consulta Specifiche A2A: dettagli dell'oggetto SecurityScheme.

    Esegui il deployment con una configurazione TaskStore in memoria

    Per eseguire il deployment dell'agente A2A con una configurazione TaskStore in memoria, esegui questo comando nella directory che contiene il codice sorgente dell'agente A2A:

    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"

    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.
    • A2A_SERVICE_ACCOUNT_NAME: il nome del tuo service account A2A.

    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 permanente delle attività, utilizza il seguente comando:

    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"

    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.
    • A2A_SERVICE_ACCOUNT_NAME: il nome del tuo service account A2A.

    Eseguire il debug degli errori di deployment

    Se si verificano errori o 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'run.app URL 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 deployare il 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"

    Informazioni sull'URL dell'applicazione Cloud Run

    In caso di deployment riuscito, Cloud Run fornisce automaticamente un run.app URL, 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

    Testa e monitora il deployment dell'agente A2A

    Dopo aver eseguito il deployment dell'agente A2A in Cloud Run, testane a fondo la funzionalità. Stabilisci solide pratiche di monitoraggio per garantire prestazioni e affidabilità continue.

    A2A inspector: valida la conformità dell'agente

    Utilizza lo strumento a2a-inspector per ispezionare, eseguire il debug e convalidare l'agente Google A2A di cui è stato eseguito il deployment. Questo strumento garantisce che l'agente sia pienamente conforme alla specifica A2A e funzioni correttamente.

    Una volta stabilita la connessione, lo strumento di ispezione esegue le seguenti azioni:

    • Mostra la scheda dell'agente:mostra automaticamente la scheda dell'agente.
    • Convalida la conformità:verifica che la carta soddisfi le specifiche A2A.
    • Attiva la chat live:ti consente di inviare e ricevere messaggi con l'agente.
    • Mostra i dati non elaborati:mostra i messaggi JSON-RPC 2.0 non elaborati in una console per il debug.

    Interazione della CLI con un agente A2A di cui è stato eseguito il deployment

    Utilizza gli strumenti dell'interfaccia a riga di comando (CLI) del repository di esempi A2A per interagire con il servizio di cui è stato eseguito il deployment. Questa CLI supporta l'autenticazione basata su token di autenticazione.

    Se il tuo servizio utilizza l'autenticazione basata su IAM, esporta il token gcloud per un'interazione riuscita:

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

    Sostituisci CLOUD_RUN_SERVICE_URL con l'URL del servizio Cloud Run di cui hai eseguito il deployment.

    Test locale dei servizi A2A di cui è stato eseguito il deployment

    Puoi testare il servizio Cloud Run di cui è stato eseguito il deployment localmente. Ciò è particolarmente utile quando implementi l'autenticazione basata su IAM.

    Testare l'autenticazione basata su IAM per gli agenti Cloud Run

    I client che interagiscono con il servizio Cloud Run protetto da Identity and Access Management (IAM) devono disporre del ruolo IAM roles/run.invoker.

    Testa localmente il flusso di autenticazione del servizio di cui è stato eseguito il deployment utilizzando il comando gcloud auth print-identity-token:

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

    Sostituisci CLOUD_RUN_SERVICE_URL con l'URL del servizio Cloud Run di cui hai eseguito il deployment.