Panoramica dell'hosting di agenti A2A su Cloud Run

Questa guida fornisce una panoramica su come preparare e configurare gli agenti Agent2Agent (A2A) per il deployment su Cloud Run. Vengono illustrati i passaggi essenziali, come la configurazione di un ambiente cloud, la configurazione dei ruoli Identity and Access Management (IAM) richiesti e la preparazione dell'agente per il deployment.

Prima di iniziare

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

Roadmap per l'implementazione dell'agente A2A

Per eseguire il deployment dell'agente, completa i seguenti passaggi:

Architettura di alto livello

Il nucleo dell'agente A2A è un livello di gestione e orchestrazione, ad esempio Cloud Run. Questo livello gestisce le interazioni con modelli di AI come Gemini e Vertex AI, archivi di memoria come AlloyDB e A2A TaskStore e strumenti esterni tramite API. I client interagiscono con l'agente inviando richieste, ad esempio "Get Agent Card" (Ottieni scheda agente) o "send message" (invia messaggio), e ricevono aggiornamenti sulle attività.

Il seguente diagramma illustra l'architettura di un sistema A2A Agent, che mostra un client A2A (utente o agente) che interagisce con l'agente A2A.

Architettura dell'agente A2A che mostra l'interazione del client con l'agente tramite un livello di serving e orchestrazione.
Architettura dell'agente A2A

Per informazioni sul ciclo di vita delle richieste A2A, consulta la sezione Ciclo di vita delle richieste A2A.

Ruoli e autorizzazioni IAM per gli agenti Cloud Run A2A

I ruoli IAM configurati correttamente sono importanti per il tuo servizio Cloud Run per interagire in modo sicuro con altri servizi Google Cloud. Crea un account di servizio dedicato e concedi le autorizzazioni specifiche elencate nelle sezioni seguenti per garantire sicurezza ed efficienza operative.

Crea un account di servizio Cloud Run

Prima di eseguire qualsiasi comando gcloud, assicurati di essere autenticato. Esegui il comando seguente per accedere al tuo account Google Cloud :

gcloud auth login

Crea un account di servizio specifico per l'istanza del servizio A2A di cui è stato eseguito il deployment. Utilizza il comando gcloud iam service-accounts create.

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

Sostituisci A2A_SERVICE_ACCOUNT_NAME con il nome del account di servizio.

Configurare i ruoli IAM per l'agente A2A

Assegna i seguenti ruoli IAM al tuo account di servizio in base ai servizi con cui interagisce l'agente A2A: Google Cloud

Accesso a Secret Manager per le credenziali sicure

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

  • Scopo:consente al account di servizio Cloud Run di recuperare in modo sicuro i secret, come le credenziali del database, da Secret Manager.

    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"

Accesso ai modelli Vertex AI per le funzionalità di AI

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

  • Scopo:necessario per l'account di servizio Cloud Run per richiamare le API di previsione sui modelli Vertex AI.

    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"

Accesso all'istanza AlloyDB per l'archiviazione permanente (se applicabile)

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

  • Scopo:consente all'identità del servizio Cloud Run di interagire con il cluster AlloyDB per l'archiviazione permanente delle attività, fondamentale per gli agenti A2A di produzione.

    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"

Prepara l'agente A2A per il deployment di Cloud Run

Questa sezione descrive le configurazioni necessarie per preparare l'agente A2A per il deployment su Cloud Run, garantendo un funzionamento sicuro, efficiente e scalabile nel cloud.

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 ulteriori informazioni, consulta Configurazione dei secret in Cloud Run.

Ad esempio, crea e gestisci i secret di password e utente del database all'interno di Google Secret Manager utilizzando la CLI gcloud. Per ulteriori informazioni, vedi Creare un secret.

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"

Crea 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 principale del progetto.

Di seguito è riportato un Dockerfile di esempio per il deployment dell'agente A2A:

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

Eseguire il deployment dal codice sorgente senza un Dockerfile

Per i repository di codice sorgente senza un Dockerfile, Cloud Run offre supporto integrato per alcuni linguaggi di programmazione più diffusi, semplificando il processo di containerizzazione.

Passaggi successivi