Questo tutorial spiega come eseguire il deployment di un agente Agent-to-Agent (A2A), creato con l'Agent Development Kit (ADK) e l'estensione A2UI, su Cloud Run. Imparerai anche a registrare l'agente di cui è stato eseguito il deployment con Gemini Enterprise.
Questo esempio utilizza un codice campione disponibile pubblicamente. Il codice campione di 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 localmente. |
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 l'agente ed eseguirne il deployment in Cloud Run. |
examples/ |
Directory contenente esempi di modelli di componenti. |
gemini_enterprise_composite_catalog.json |
Catalogo dei componenti che definisce i componenti standard di Material e quelli personalizzati di Gemini Enterprise. |
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. |
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 disporre di quanto segue:
Il ruolo Discovery Engine Admin.
Un'app Gemini Enterprise esistente. Per creare un'app, consulta Crea 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 Cloud Storage
- API Identity and Access Management (IAM)
REST
Puoi abilitare queste API dalla console Google Cloud 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." \
--role="roles/run.invoker"
Sostituisci quanto segue:
- PROJECT_ID : l'ID progetto.
- PROJECT_NUMBER: il tuo numero di progetto Google Cloud .
Esegui il deployment dell'agente
Lo script deploy.sh automatizza il processo di deployment. Per eseguire il deployment dell'agente, esegui lo script dalla directory del progetto con l'ID Google Cloud e un nome per il nuovo servizio. Puoi anche specificare il modello Gemini
da utilizzare.
Lo script esegue le seguenti azioni:
- Crea un'immagine container dal tuo codice sorgente.
- Esegue il push dell'immagine in Artifact Registry.
- Esegue il deployment dell'immagine in Cloud Run.
- Imposta le variabili di ambiente, tra cui
MODELeAGENT_URLpubblico 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-proegemini-2.5-flash. Se non viene fornito, lo script utilizza per impostazione predefinitagemini-2.5-flash.
Al termine dello script, viene stampato l'URL del servizio dell'agente di cui è stato eseguito il deployment. Questo URL del servizio ti servirà nel passaggio successivo.
Registra l'agente con Gemini Enterprise
Ora che l'agente è stato distribuito, 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 tuo numero di progetto Google Cloud .LOCATION: la località multiregionale del datastore:global,usoeuENGINE_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 tuo numero di progetto Google Cloud .LOCATION: la località multiregionale del datastore:global,usoeuENGINE_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 a interagire con lui nell'app web Gemini Enterprise.
Recupera 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:
Nella console Google Cloud , vai alla pagina Gemini Enterprise.
Fai clic sul nome dell'app con cui hai registrato l'agente.
Fai clic su Integrations (Integrazioni).
Copia il link alla tua app web e condividilo con gli utenti dell'organizzazione.
Utilizza l'agente
Per utilizzare l'agente e interagire con questo:
- Apri l'URL dell'app web in una nuova scheda del browser.
- Nel menu di navigazione dell'app web, fai clic su Agenti.
- Vai alla sezione Dalla tua organizzazione e fai clic sull'agente che hai creato.
- Si aprirà l'interfaccia di conversazione per l'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 campionati. 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:
