Ospita un agente A2UI con Cloud Run

Questo tutorial spiega come eseguire il deployment di un agente Agent-to-Agent (A2A), creato con Google Agent Development Kit (ADK) e l'estensione A2UI, su Cloud Run. Scopri anche come registrare l'agente di cui è stato eseguito il deployment in Gemini Enterprise.

Il codice campione per questo tutorial ha la seguente struttura di cartelle.

Struttura delle cartelle del tutorial

Il progetto ha la seguente struttura di cartelle:

File/Directory Descrizione
examples/0.8/ Directory contenente configurazioni o dati di esempio.
__init__.py Contrassegna la directory come pacchetto Python.
agent.py Definisce l'agente, le sue competenze e il suo comportamento.
agent_executor.py Gestisce il flusso di esecuzione e le interazioni con gli strumenti.
contact_data.json Dati di esempio utilizzati dall'agente (ad esempio, contatti simulati).
deploy.sh Script per creare ed eseguire il deployment dell'agente su Cloud Run.
main.py L'entry point principale dell'applicazione (app FastAPI).
prompt_builder.py Helper per creare prompt per il modello.
pyproject.toml Configurazione e dipendenze del progetto.
tools.py Definisce gli strumenti (funzioni) che l'agente può utilizzare.

Prima di iniziare

Prima di iniziare, assicurati di avere quanto segue:

  • Il ruolo Amministratore di Discovery Engine.

  • Un'app Gemini Enterprise esistente. Per creare un'app, consulta Creare un'app.

  • Clona il repository e vai alla directory di esempio cloud_run:

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

Abilita API

Abilita le seguenti API per il tuo progetto:

Console

Abilita le seguenti API:

  • API Agent Platform
  • API Cloud Build
  • API Artifact Registry
  • API Cloud Run
  • API Cloud Logging
  • API Discovery Engine
  • API Storage Cloud
  • API Identity and Access Management (IAM)

Abilita API

REST

Puoi abilitare queste API dalla Google Cloud console o utilizzando il seguente comando gcloud CLI:

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

Concedi le autorizzazioni

Concedi l'autorizzazione al ruolo Cloud Run Invoker (roles/run.invoker).

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

Sostituisci quanto segue:

  • PROJECT_ID : l'ID progetto.
  • PROJECT_NUMBER: il Google Cloud numero del progetto.

Esegui il deployment dell'agente

Lo script deploy.sh automatizza la procedura di deployment. Per eseguire il deployment dell'agente, esegui lo script dalla directory del progetto con il tuo Google Cloud ID e un nome per il nuovo servizio. Facoltativamente, puoi anche specificare il modello Gemini da utilizzare.

Lo script esegue le seguenti azioni:

  1. Crea un'immagine container dal codice sorgente.
  2. Esegue il push dell'immagine in Artifact Registry.
  3. Esegue il deployment dell'immagine in Cloud Run.
  4. Imposta le variabili di ambiente, inclusi MODEL e l'URL pubblico AGENT_URL del servizio stesso.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • MODEL_NAME: (facoltativo). Questo è il terzo argomento dello script. I valori supportati sono gemini-2.5-pro e gemini-2.5-flash. Se non viene fornito, lo script utilizza per impostazione predefinita gemini-2.5-flash.

Al termine dello script, viene stampato l'URL del servizio dell'agente di cui è stato eseguito il deployment. Avrai bisogno di questo URL del servizio nel passaggio successivo.

Registra l'agente in Gemini Enterprise

Ora che l'agente è stato sottoposto a deployment, devi registrarlo in Gemini Enterprise per renderlo rilevabile.

Esegui il seguente comando curl, sostituendo i segnaposto con i tuoi valori:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

Sostituisci quanto segue:

  • PROJECT_NUMBER: il Google Cloud numero del progetto.
  • LOCATION: la regione multipla del tuo datastore: global, us o eu
  • ENGINE_ID: l'ID dell'app in cui vuoi registrare l'agente.
  • AGENT_URL: l'URL del servizio dell'agente di cui è stato eseguito il deployment.

Utilizza l'agente nell'app web Gemini Enterprise

Dopo aver creato e registrato un agente, puoi iniziare a utilizzarlo e interagire con esso nell'app web Gemini Enterprise.

Recupera l'URL dell'app web

Per utilizzare l'agente, devi prima recuperare l'URL dell'app web. Un amministratore di Gemini Enterprise può recuperare e condividere l'URL dell'app web seguendo questi passaggi:

  1. Nella Google Cloud console, vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app in cui hai registrato l'agente.

  3. Fai clic su Integrazioni.

  4. Copia il link all'app web e condividilo con gli utenti dell'organizzazione.

Utilizza l'agente

Per utilizzare l'agente e interagire con esso:

  1. Apri l'URL dell'app web in una nuova scheda del browser.
  2. Nel menu di navigazione dell'app web, fai clic su Agenti.
  3. Vai alla sezione Dalla tua organizzazione e fai clic sull'agente che hai creato.
  4. Si aprirà l'interfaccia conversazionale per l'agente. Inizia a porre domande e a interagire con l'agente.

Ad esempio, puoi chiedere all'agente di elencare tutti i contatti. L'agente utilizza lo strumento list_contacts per recuperare i contatti da contact_data.json e visualizza l'elenco nella chat utilizzando elementi dell'interfaccia utente personalizzati, come mostrato nell'esempio seguente:

Esempio di agente di contatti