Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Importare un agente Google ADK

Questa guida passo passo importa l’Agent Config di un’applicazione costruita sull’Agent Development Kit (ADK) di Google — un agente che risponde alle domande dei clienti sui loro ordini — e compila l’applicazione per Docker Compose. L’importazione abbozza ogni file letto dalla build: l’agente e il suo modello Gemini, la chiave che l’agente presenta al modello come riferimento a una variabile, e le realizzazioni di ciascuno. Chiede una sola volta l’unico valore che nessuna configurazione contiene, l’immagine in cui l’applicazione viene eseguita. Ogni file e ogni blocco di output riportati di seguito provengono da un’esecuzione reale; la configurazione e ogni fase della guida si trovano nell’esempio import-google-adk, dove uno script di verifica esegue di nuovo l’importazione, confronta ciò che scrive, ciò che stampa e i blocchi citati in questa pagina con i file conservati lì, e valida e compila ciò che l’importazione ha scritto.

Generare l’esempio

Puoi eseguire questa importazione con i comandi di questa pagina, oppure farla eseguire al tuo assistente AI.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example import-google-adk

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella; quello successivo, qui sotto, ti porta nella cartella source della nuova cartella, che contiene ciò che questa pagina importa ed è dove viene eseguita l’importazione:

Terminal window
cd import-google-adk

La cartella source dell’esempio generato aperta in Visual Studio Code, che mostra la configurazione dell’agente: support_agent su gemini-2.5-flash con lo strumento google_search.

Il progetto

ADK può dichiarare gli agenti di un’applicazione in file Agent Config invece che nel codice: adk create --type=config scrive root_agent.yaml, la configurazione dell’agente radice, e accanto a esso un file di ambiente. Questo, scritto per questa guida, dichiara un agente su gemini-2.5-flash di Gemini, con lo strumento Google Search fornito da ADK:

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: support_agent
model: gemini-2.5-flash
description: Answers a customer's question about their order.
instruction: |
You answer customers' questions about their orders. When a customer asks
where a parcel is, search the web for the tracking page of the company
shipping it.
tools:
- name: google_search

L’importazione non legge mai il file di ambiente, che di solito contiene la chiave che l’applicazione invia a Gemini, quindi l’esempio non ne contiene alcuno. Nella radice del progetto, un .aggrega-config.yaml rende la cartella uno spazio di lavoro:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside support_agent/.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

L’importazione fa riferimento ai Components del catalogo per l’agente ADK e per il modello Gemini, e --target abbozza un Manifest a partire dalle sue Recipes. Lo spazio di lavoro non indica alcuna cartella di catalogo, quindi l’importazione legge il catalogo della libreria standard dal registry da cui recupera il proprio importer: uno snapshot firmato del catalogo pubblicato, che la prima importazione recupera, verifica e conserva nella cache dei contenuti dello spazio di lavoro, e che il record scritto dall’importazione accanto alle sue bozze indica tramite il suo digest. Uno spazio di lavoro che indica le proprie cartelle di catalogo — in AGGREGA_CATALOG_DIRS, oppure sotto workspace.catalog_dirs — importa invece rispetto a quelle.

Cosa chiede l’importazione

Un Agent Config indica il modello dell’agente, mai l’immagine in cui l’applicazione viene eseguita: quell’immagine la costruisci a partire dal tuo progetto. Il catalogo non contiene alcuna immagine predefinita per un’applicazione costruita su ADK, quindi l’importazione la chiede. In un terminale la chiede e scrive la risposta nelle bozze e nel file delle risposte, import-answers.yaml, all’interno della directory che importa, support_agent/, così l’importazione successiva la legge da lì e non chiede nulla. Senza terminale — nell’integrazione continua o attraverso una pipe — non chiede nulla: scrive il file con la chiave vuota e si ferma, indicando il file. L’esempio contiene già il file, con l’immagine come risposta, ghcr.io/example/support-agent:1.0.0, che sta per l’immagine che costruisci:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# Container image running the application built on ADK, serving its API on infra.port on every
# interface.
spec.components.support-agent.infra.image: "ghcr.io/example/support-agent:1.0.0"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin: "google-api-key"

La seconda risposta serve per una build per Kubernetes, con --target helm: lì l’agente legge la chiave API di Gemini da un Secret di Kubernetes, e la risposta è il nome del Secret, google-api-key, mai la chiave. Una build per Docker Compose legge invece la chiave dalla tua shell, quindi questa importazione non usa quella risposta. Il file delle risposte dell’importazione descrive il file, le domande e le regole per la risposta relativa a un secret.

aggrega import elenca ogni flag accettato dal comando, tra cui --answers, che indica un file delle risposte conservato altrove.

Entra in source:

Terminal window
cd source

Eseguire l’importazione

Indica la directory dell’agente. L’importazione ne legge il root_agent.yaml:

Terminal window
aggrega import support_agent --target compose

Sullo standard output elenca ciò che ha scritto:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Sullo standard error, dove <workspace> sta per la cartella in cui l’hai eseguita:

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the google-adk format, with drafted paths relative to <workspace>
info: the answers file <workspace>/support_agent/import-answers.yaml also answers spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not applied
mapped support_agent (agent) to core/ai-agent/google-adk as a reference, NONE
mapped gemini-2.5-flash (model) to core/ai-model/gemini as a reference, NONE
made no choice for google_search (tool)
Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)

L’importazione eseguita dall’editor: l’Aggregate, la Release e il Manifest in bozza compaiono accanto alla configurazione dell’agente, l’output di Aggrega elenca come sono stati mappati l’agente e il suo modello e i file scritti, e una notifica indica che l’importazione ha prodotto 3 file in bozza, riconosciuti come google-adk.

  • La riga info indica la risposta che le bozze per Docker Compose non usano, conservata nel file delle risposte per una build per Kubernetes.
  • Le righe mapped dicono che l’agente è un’istanza dell’agente ADK della libreria standard, core/ai-agent/google-adk, e che il modello che nomina è un’istanza di core/ai-model/gemini. Il loro livello è NONE: l’importazione ADK fa riferimento a questi Components in base a ciò che la configurazione nomina, anziché valutare ciascuno rispetto al catalogo.
  • La riga made no choice dice che per lo strumento Google Search non viene abbozzato nulla: è uno strumento fornito da ADK e viene eseguito all’interno dell’applicazione.
  • La riga Pull complete è l’import che recupera ciò da cui dipende la Release generata in bozza, come fa aggrega pull, in release.lock, così che le bozze si validino e si compilino subito. Con --offline l’import non recupera nulla e indica il comando aggrega pull da eseguire.

Cosa scrive

L’Aggregate, la Release e il Manifest si chiamano imported/support-agent, dal name dell’agente radice, support_agent, ridotto a support-agent, nel namespace definito dall’impostazione target_namespace dell’importatore, imported a meno che tu non ne imposti un altro (Impostazioni).

aggregate.yaml — l’agente, collegato al modello con la chiave che presenta dichiarata sulla connessione, e il modello, preceduti da commenti che dicono cosa è stato letto e cosa no:

# Google ADK agent configurations read:
# - root_agent.yaml
# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.
# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-agent
version: 0.1.0
description: Draft Aggregate imported from a source in the google-adk format.
spec:
components:
# The agent tree of root_agent.yaml, served from its root agent support_agent.
# Tools ADK ships, which run inside the application, drafted as no Component: google_search.
support-agent:
type: core/ai-agent/google-adk
values:
description: "Answers a customer's question about their order."
uses:
model:
gemini-2-5-flash:
target: gemini-2-5-flash
# For the compose target, the lines below declare credential on gemini-2-5-flash: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
features:
credential:
type: core/secret-value
values:
key: GOOGLE_API_KEY
# The model gemini-2.5-flash.
gemini-2-5-flash:
type: core/ai-model/gemini
values:
model: "gemini-2.5-flash"

ADK serve un’applicazione a partire dal suo agente radice, quindi la bozza contiene un’istanza per ogni albero di agenti, con il nome del suo agente radice. L’instruction dell’agente non viene riportata: l’applicazione la legge dalla propria configurazione, che si trova nell’immagine.

ADK serve gemini-2.5-flash tramite la sua classe Gemini, che invia le richieste all’API Gemini, quindi la bozza collega il modello al socket model dell’agente, che ammette solo l’API Gemini. Gemini è un servizio ospitato, quindi il Component dell’agente rifiuta una connessione verso di esso che non porti alcuna credenziale; la connessione ne dichiara una, sotto la chiave GOOGLE_API_KEY. Un modello che ADK serve in qualsiasi altro modo — un nome come gpt-4o che ADK serve tramite una classe propria, o una stringa di modello LiteLLM come openai/gpt-4o — non viene collegato a nulla: un commento sopra l’istanza lo nomina, e la connessione è lasciata a te, come descrive Che cosa diventa un albero di agenti.

release.yaml — l’ambiente, l’immagine, la porta pubblicata e da dove proviene la chiave:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support-agent
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the google-adk format.
spec:
aggregate: imported/support-agent
manifest: imported/support-agent
components:
support-agent:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations
image: "ghcr.io/example/support-agent:1.0.0"
# Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal.
published_port: 8000
uses:
model:
gemini-2-5-flash:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential support-agent presents to gemini-2-5-flash on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${GOOGLE_API_KEY}"
gemini-2-5-flash: {}

L’ambiente, development, è un valore predefinito che l’importazione scrive perché nessuna configurazione ne indica uno; cambialo dove la Release viene distribuita altrove. L’immagine è la risposta che l’importazione ha letto da support_agent/import-answers.yaml. published_port è 8000, la porta su cui l’applicazione è in ascolto, quindi risponde a http://127.0.0.1:8000 sulla tua macchina; come dice il suo commento, qualsiasi processo su questa macchina può raggiungerla lì e nient’altro può farlo, ed eliminando la riga l’applicazione resta solo sulla rete dello stack. La configurazione non indica alcuna variabile per la chiave, quindi la connessione la legge da ${GOOGLE_API_KEY}, la variabile che leggono le librerie client dell’API Gemini, come riferimento a variabile e mai come valore.

manifest.yaml — la Recipe Compose di ciascun tipo, e la realizzazione che scrive il riferimento a variabile della chiave nel file Compose tale e quale:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/support-agent
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/google-adk: compose/google-adk
core/ai-model/gemini: compose/gemini
features:
type:
core/secret-value: compose/dotenv-secret

release.lock registra, per digest, le entità del catalogo in cui la Release si è risolta, e .aggrega-import.json è il registro di ciò che l’importazione ha scritto, che un successivo aggrega import --sync legge.

Convalidare e compilare

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

La Release in bozza aperta nell’editor dopo averla validata, con l’output di Aggrega e una notifica che non segnalano alcun problema.

La build della Release in bozza: nell’Explorer compare una cartella dist, l’output di Aggrega elenca il file Docker Compose scritto e una notifica indica che è stato scritto 1 file.

La convalida stampa:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

e la build, dove <workspace> indica la cartella in cui l’hai eseguita:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 1 file written to <workspace>/dist

La riga notice è informativa: la Feature del segreto accetta il suo origin dai values dell’Aggregate o dall’infra della Release, e l’avviso segnala che una foglia è dichiarata in entrambi. Non cambia alcun verdetto.

Il servizio dell’agente in dist/compose/docker-compose.yaml:

services:
support-agent:
image: ghcr.io/example/support-agent:1.0.0
environment:
PORT: "8000"
GOOGLE_API_KEY: ${GOOGLE_API_KEY}
ports:
- 127.0.0.1:8000:8000
[… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version]
networks:
- compose

L’applicazione riceve la porta su cui il suo server è in ascolto come PORT, e la chiave come GOOGLE_API_KEY, che il client Gemini di ADK invia all’API Gemini. Il modello non ha un servizio proprio: il client invia le sue richieste all’indirizzo dell’API Gemini stessa e non ne legge altri dal proprio ambiente. La chiave è un riferimento a variabile, valorizzato dalla tua shell all’avvio dello stack. La Recipe Compose dell’agente ADK pubblica una porta sulla tua macchina solo dove la Release imposta published_port nell’infra dell’agente, e in tal caso solo sull’indirizzo di loopback, 127.0.0.1; senza di essa, il servizio è raggiungibile solo sulla rete dello stack.

Con un assistente AI

Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `import-google-adk`, chiama una volta lo strumento `scaffold` con `example` impostato su `import-google-adk` e senza `dir`: scrive l’esempio in una nuova cartella `import-google-adk`, la cui cartella `source` contiene ciò che questa pagina importa. Poi chiama lo strumento `import` con `workspace_root` impostato su `import-google-adk/source`, `source` impostato su `support_agent` e `target` impostato su `compose`: legge le risposte di cui ha bisogno da `import-answers.yaml` nella cartella `support_agent`, scrive le sue bozze in `import-google-adk/source` ed esegue il pull di ciò di cui hanno bisogno. Poi chiama lo strumento `validate` con `workspace_root` impostato su `import-google-adk/source` e `release` impostato su `release.yaml`, e lo strumento `build` con `workspace_root` impostato su `import-google-adk/source`, `release` impostato su `release.yaml` e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `import-google-adk/source/dist/`.

Aprilo in VS Code

Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code la cartella import-google-adk/source, dove l’importazione ha scritto le sue bozze. La cartella contiene una sola Release, il release.yaml in bozza, quindi l’editor la seleziona per te e, mentre modifichi le bozze, le verifica rispetto a quella Release, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i suoi file nella dist/ della cartella. Usare Aggrega in Visual Studio Code descrive il resto.

Esecuzione

Docker Compose esegue la tua immagine come il servizio renderizzato qui sopra, PORT incluso. L’immagine deve restare in ascolto su quella porta su tutte le interfacce, non su 127.0.0.1, l’indirizzo predefinito del server API di ADK. Il server API di ADK stesso, adk api_server, serve la directory di configurazione così com’è, quindi l’immagine non richiede codice tuo. Un Dockerfile nella radice del progetto, accanto a support_agent/:

FROM python:3.12-slim
RUN pip install --no-cache-dir google-adk==2.13.0
COPY support_agent/ /app/agents/support_agent/
CMD ["sh", "-c", "exec adk api_server --host 0.0.0.0 --port \"$PORT\" --auto_create_session /app/agents"]

adk api_server serve le directory degli agenti presenti nella cartella che indica, e il comando gli passa PORT. --auto_create_session apre una sessione la prima volta che una richiesta a /run la nomina, così una sola richiesta raggiunge l’agente. Esegui la build dell’immagine, scrivi il suo nome al posto di ghcr.io/example/support-agent:1.0.0 in support_agent/import-answers.yaml e importa di nuovo con --sync, che scrive la nuova risposta nelle bozze ed esegue di nuovo il pull; poi esegui la build:

Terminal window
docker build -t support-agent:local .
aggrega import support_agent --sync
aggrega build --release release.yaml

Poi imposta la chiave nella tua shell e avvia lo stack:

Terminal window
export GOOGLE_API_KEY='your Gemini API key'
docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait

-p dà il nome al progetto, come spiega il passo di esecuzione di Come si svolge un’importazione. --wait ritorna non appena il container è in esecuzione, poiché la build non assegna al servizio alcun controllo di integrità, e il server risponde un attimo dopo, quindi ripeti una richiesta che rifiuta.

Eseguire il test

Invia un messaggio all’agente su http://127.0.0.1:8000, l’indirizzo che published_port pubblica. La richiesta indica un utente e una sessione, e /run apre la sessione al suo primo messaggio:

Terminal window
curl -sS -X POST http://127.0.0.1:8000/run -H 'Content-Type: application/json' \
-d '{"app_name": "support_agent", "user_id": "u1", "session_id": "s1", "new_message": {"role": "user", "parts": [{"text": "Where is my order 1234? Answer in one short sentence."}]}}'

La risposta, quella di Gemini, torna come elenco degli eventi che il turno ha aggiunto alla sessione. L’esecuzione ha usato un segnaposto per la chiave, quindi Gemini l’ha rifiutata: la richiesta ha risposto HTTP 500, Internal Server Error, e il log del servizio, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, indica il motivo:

google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'API key not valid. Please pass a valid API key.', 'status': 'INVALID_ARGUMENT', [… omitted: the error's details]}}

curl -sS http://127.0.0.1:8000/list-apps risponde ["support_agent"], gli agenti che il server contiene.

Arresta lo stack con:

Terminal window
docker compose -p support-agent -f dist/compose/docker-compose.yaml down

Su Kubernetes

Lo stesso agente si importa per Kubernetes con --target helm. Un cluster scarica le proprie immagini da un registry, quindi esegui il push dell’immagine che hai costruito in uno che il tuo cluster legge, e scrivi il suo nome al posto dell’immagine data come risposta in support_agent/import-answers.yaml; l’esecuzione l’ha inviata a un registry sulla macchina stessa del cluster, come localhost:5000/support-agent:1.0.0. La seconda risposta lì indica il Secret da cui l’agente legge la chiave API di Gemini, google-api-key. Le bozze per Docker Compose si trovano già in source, quindi genera queste in una cartella propria ed esegui la build da lì:

Terminal window
aggrega import support_agent --target helm --output-dir helm
cd helm
aggrega build --release release.yaml

La build scrive semplici manifest Kubernetes in dist/helm/ nella radice del workspace, source, che da helm è ../dist/helm/. Crea il Secret google-api-key nel namespace a cui applichi, con la chiave sotto la chiave di dati value, e applica la cartella come spiega la fase di esecuzione di Come si esegue un’importazione. Il Service dell’agente è support-agent-default: inoltra a esso una porta locale e lascia il comando in esecuzione:

Terminal window
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000

Da un altro terminale, il messaggio precedente raggiunge l’agente allo stesso indirizzo, invariato. L’esecuzione ha ottenuto lo stesso Internal Server Error, e kubectl logs -n <namespace> deploy/support-agent indica lo stesso rifiuto della chiave segnaposto.