Ospita un agente A2UI con Cloud Run

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

Questo esempio utilizza codice campione disponibile pubblicamente. 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
/samples/community/agent/adk/gemini_enterprise/v0_9 Directory contenente configurazioni e dati di esempio per questo tutorial.
__init__.py Contrassegna la directory come pacchetto Python.
__main__.py Il punto di contatto per eseguire l'agente in locale.
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.
deploy.sh Script per creare ed eseguire il deployment dell'agente su Cloud Run.
examples/ Directory contenente esempi di modelli di componenti.
gemini_enterprise_composite_catalog.json Catalogo dei componenti che definisce i componenti Material standard e Gemini Enterprise personalizzati.
main.py Il punto di contatto principale dell'applicazione (app FastAPI).
prompt_builder.py Utilità per creare prompt per il modello.
pyproject.toml Configurazione e dipendenze del progetto.
examples/0.9/material_table_orders.json Modello di UI di esempio contenente il layout e i dati fittizi per la demo degli ordini recenti.
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 v0_9:

    git clone https://github.com/a2ui-project/a2ui.git
cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9

Abilita API

Abilita le seguenti API per il tuo progetto:

Console

Abilita le seguenti API:

  • API Vertex AI
  • 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 su 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 PROJECT_ID a2ui-demo-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.

Una volta completato lo 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 con Gemini Enterprise

Ora che l'agente è stato sottoposto a deployment, devi registrarlo con 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": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
    }
}'

Sostituisci quanto segue:

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

Annulla la registrazione dell'agente (facoltativo)

Se vuoi annullare la registrazione dell'agente, esegui il seguente comando curl:

curl -X DELETE -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/AGENT_ID

Sostituisci quanto segue:

  • PROJECT_NUMBER: il Google Cloud numero del progetto.
  • LOCATION: la multiregione del datastore: global, us o eu
  • ENGINE_ID: l'ID dell'app con cui è registrato l'agente.
  • AGENT_ID: l'ID dell'agente che vuoi eliminare.

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.

Ottieni l'URL dell'app web

Per utilizzare l'agente, devi prima ottenere l'URL dell'app web. Un amministratore di Gemini Enterprise può ottenere 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 con 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 dell'agente. Inizia a porre domande e a interagire con l'agente.

Ad esempio, puoi utilizzare un prompt come Show me the recent orders table per ottenere informazioni sugli ordini recenti che fanno parte dei dati di esempio. L'agente recupera le informazioni sull'ordine da material_table_orders.json e visualizza l'elenco nella chat utilizzando componenti UI personalizzati, come mostrato nell'esempio seguente:

Esempio di tabella degli ordini recenti