Importer un agent Google ADK
Ce guide pas à pas importe l’Agent Config d’une application construite sur l’Agent Development Kit (ADK) de Google — un agent qui répond aux questions des clients sur leurs commandes — et construit l’application pour Docker Compose. L’import rédige en brouillon chaque fichier que lit le build : l’agent et son modèle Gemini, la clé que l’agent présente au modèle sous forme de référence à une variable, et les réalisations de chacun. Il demande une seule fois l’unique valeur qu’aucune configuration ne contient, l’image dans laquelle s’exécute l’application. Chaque fichier et chaque bloc de sortie ci-dessous proviennent d’une exécution réelle ; la configuration et chaque étape du guide se trouvent dans l’exemple import-google-adk, où un script de vérification relance l’import, compare ce qu’il écrit, ce qu’il affiche et les blocs que cite cette page avec les fichiers qui y sont conservés, puis valide et construit ce que l’import a écrit.
Générer l’exemple
Vous pouvez exécuter cette importation avec les commandes de cette page, ou la faire exécuter par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example import-google-adkElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier ; la suivante, ci-dessous, vous place dans le dossier source du nouveau dossier, qui contient ce que cette page importe et où s’exécute l’import :
cd import-google-adk
Le projet
ADK peut déclarer les agents d’une application dans des fichiers Agent Config plutôt que dans le code : adk create --type=config écrit root_agent.yaml, la configuration de l’agent racine, et un fichier d’environnement à côté. Celui-ci, écrit pour ce guide, déclare un agent sur gemini-2.5-flash de Gemini, avec l’outil Google Search fourni par ADK :
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.jsonname: support_agentmodel: gemini-2.5-flashdescription: 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_searchL’import ne lit jamais le fichier d’environnement, qui contient généralement la clé que l’application envoie à Gemini ; l’exemple n’en contient donc aucun. À la racine du projet, un .aggrega-config.yaml fait du dossier un espace de travail :
# 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.aiL’import référence les Components du catalogue pour l’agent ADK et le modèle Gemini, et --target rédige un brouillon de Manifest à partir de ses Recipes. L’espace de travail n’indique aucun dossier de catalogue ; l’import lit donc le catalogue de la bibliothèque standard depuis le registre dont il récupère son importateur : un instantané signé du catalogue publié, que le premier import récupère, vérifie et conserve dans le cache de contenu de l’espace de travail, et que l’enregistrement écrit par l’import à côté de ses brouillons désigne par son condensé. Un espace de travail qui indique ses propres dossiers de catalogue — dans AGGREGA_CATALOG_DIRS, ou sous workspace.catalog_dirs — importe plutôt en s’appuyant sur ceux-ci.
Ce que demande l’importation
Une Agent Config nomme le modèle de l’agent, jamais l’image dans laquelle s’exécute l’application : cette image, vous la construisez à partir de votre projet. Le catalogue ne contient aucune image par défaut pour une application construite sur ADK ; l’import la demande donc. Dans un terminal, il la demande et écrit la réponse dans les brouillons et dans le fichier de réponses, import-answers.yaml, à l’intérieur du répertoire qu’il importe, support_agent/, de sorte que l’import suivant la lit à cet endroit et ne demande rien. Sans terminal — en intégration continue, ou à travers un pipe — il ne demande rien : il écrit le fichier avec la clé vide, puis s’arrête en nommant le fichier. L’exemple contient déjà le fichier, avec l’image renseignée, ghcr.io/example/support-agent:1.0.0, qui représente l’image que vous construisez :
# 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 seconde réponse sert à un build pour Kubernetes, avec --target helm : l’agent y lit la clé d’API Gemini depuis un Secret Kubernetes, et la réponse est le nom du Secret, google-api-key, jamais la clé. Un build pour Docker Compose lit plutôt la clé depuis votre shell ; cet import n’utilise donc pas cette réponse. Le fichier de réponses de l’import décrit le fichier, les questions et les règles applicables à la réponse d’un secret.
aggrega import liste toutes les options que prend la commande, dont --answers, qui nomme un fichier de réponses conservé ailleurs.
Placez-vous dans source :
cd sourceLancer l’importation
Indiquez le répertoire de l’agent. L’import lit son root_agent.yaml :
aggrega import support_agent --target composeSur la sortie standard, elle liste ce qu’elle a écrit :
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonSur la sortie d’erreur standard, où <workspace> désigne le dossier dans lequel vous l’avez lancée :
[… 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 appliedmapped support_agent (agent) to core/ai-agent/google-adk as a reference, NONEmapped gemini-2.5-flash (model) to core/ai-model/gemini as a reference, NONEmade no choice for google_search (tool)Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
- La ligne
infonomme la réponse que les brouillons Docker Compose n’utilisent pas, conservée dans le fichier de réponses pour une compilation pour Kubernetes. - Les lignes
mappedindiquent que l’agent est une instance de l’agent ADK de la bibliothèque standard,core/ai-agent/google-adk, et que le modèle qu’il nomme est une instance decore/ai-model/gemini. Leur niveau indiqueNONE: l’import ADK référence ces Components d’après ce que nomme la configuration, plutôt qu’en évaluant chacun par rapport au catalogue. - La ligne
made no choiceindique que rien n’est rédigé pour l’outil Google Search : c’est un outil fourni par ADK, et il s’exécute à l’intérieur de l’application. - La ligne
Pull completecorrespond à l’import qui récupère ce dont dépend la Release rédigée, comme le faitaggrega pull, dansrelease.lock, de sorte que les brouillons se valident et se construisent immédiatement. Avec--offline, l’import ne récupère rien et indique la commandeaggrega pullà exécuter.
Ce qu’elle écrit
L’Aggregate, la Release et le Manifest sont nommés imported/support-agent, d’après le name de l’agent racine, support_agent, réduit à support-agent, sous le namespace que fixe le paramètre target_namespace de l’importeur, imported sauf si vous en fixez un autre (Paramètres).
aggregate.yaml — l’agent, relié au modèle avec la clé qu’il présente déclarée sur la connexion, et le modèle, précédés de commentaires qui indiquent ce qui a été lu et ce qui ne l’a pas été :
# 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/v1beta1kind: Aggregatemetadata: 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 sert une application à partir de son agent racine ; le brouillon contient donc une instance par arbre d’agents, nommée d’après son agent racine. L’instruction de l’agent n’est pas reprise : l’application la lit dans sa propre configuration, que contient l’image.
ADK sert gemini-2.5-flash au moyen de sa classe Gemini, qui envoie ses requêtes à l’API Gemini, si bien que l’ébauche relie le modèle au socket model de l’agent, qui n’admet que l’API Gemini. Gemini est un service hébergé, si bien que le Component de l’agent refuse une connexion vers lui qui ne porte aucun identifiant ; la connexion en déclare un, sous la clé GOOGLE_API_KEY. Un modèle qu’ADK sert de toute autre manière — un nom comme gpt-4o qu’ADK sert au moyen d’une classe qui lui est propre, ou une chaîne de modèle LiteLLM comme openai/gpt-4o — n’est relié à rien : un commentaire au-dessus de l’instance le nomme, et la connexion vous est laissée, comme le décrit Ce que devient une arborescence d’agents.
release.yaml — l’environnement, l’image, le port publié et la provenance de la clé :
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: 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’environnement, development, est une valeur par défaut que l’import écrit parce qu’aucune configuration n’en nomme un ; modifiez-le là où la Release est déployée ailleurs. L’image est la réponse que l’import a lue dans support_agent/import-answers.yaml. published_port vaut 8000, le port sur lequel l’application écoute ; elle répond donc à http://127.0.0.1:8000 sur votre machine ; comme le dit son commentaire, tout processus de cette machine peut l’y joindre et rien d’autre ne le peut, et supprimer la ligne garde l’application sur le seul réseau de la stack. La configuration ne nomme aucune variable pour la clé, si bien que la connexion la lit depuis ${GOOGLE_API_KEY}, la variable que lisent les bibliothèques clientes de l’API Gemini, sous forme de référence de variable et jamais de valeur.
manifest.yaml — la Recipe Compose de chaque type, et la réalisation qui écrit la référence de variable de la clé telle quelle dans le fichier Compose :
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/support-agent version: 0.1.0spec: mappings: components: type: core/ai-agent/google-adk: compose/google-adk core/ai-model/gemini: compose/gemini features: type: core/secret-value: compose/dotenv-secretrelease.lock enregistre, par digest, les entités du catalogue vers lesquelles la Release a été résolue, et .aggrega-import.json est l’enregistrement de ce que l’importation a écrit, que lit un aggrega import --sync ultérieur.
Valider et compiler
aggrega validate --release release.yamlaggrega build --release release.yaml

La validation affiche :
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)et le build, où <workspace> désigne le dossier dans lequel vous l’avez exécuté :
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>/distLa ligne notice est indicative : la Feature de secret accepte son origin depuis les values de l’Aggregate ou l’infra de la Release, et la notice signale qu’une feuille est déclarée dans les deux. Elle ne change aucun verdict.
Le service de l’agent dans 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: - composeL’application reçoit le port sur lequel son serveur écoute sous la forme de PORT, et la clé sous la forme de GOOGLE_API_KEY, que le client Gemini d’ADK envoie à l’API Gemini. Le modèle n’a pas de service propre : le client envoie ses requêtes à l’adresse propre de l’API Gemini et n’en lit aucune autre dans son environnement. La clé est une référence de variable, remplie depuis votre shell au démarrage de la stack. La Recipe Compose de l’agent ADK ne publie un port sur votre machine que là où la Release définit published_port dans l’infra de l’agent, et alors sur la seule adresse de bouclage, 127.0.0.1 ; sans cela, le service n’est joignable que sur le réseau de la stack.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-y ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier Workspace ne contient pas encore de dossier `import-google-adk`, appelez une fois l’outil `scaffold` avec `example` défini sur `import-google-adk` et sans `dir` : il écrit l’exemple dans un nouveau dossier `import-google-adk`, dont le dossier `source` contient ce que cette page importe. Appelez ensuite l’outil `import` avec `workspace_root` défini sur `import-google-adk/source`, `source` défini sur `support_agent` et `target` défini sur `compose` : il lit les réponses dont il a besoin dans `import-answers.yaml` à l’intérieur du dossier `support_agent`, écrit ses ébauches dans `import-google-adk/source` et récupère ce dont elles ont besoin. Appelez ensuite l’outil `validate` avec `workspace_root` défini sur `import-google-adk/source` et `release` défini sur `release.yaml`, puis l’outil `build` avec `workspace_root` défini sur `import-google-adk/source`, `release` défini sur `release.yaml` et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `import-google-adk/source/dist/`.L’ouvrir dans VS Code
Avec l’extension Aggrega pour Visual Studio Code installée, ouvrez dans VS Code le dossier import-google-adk/source, où l’import a écrit ses ébauches. Le dossier contient une seule Release, le release.yaml ébauché ; l’éditeur la sélectionne donc pour vous, et il vérifie les ébauches par rapport à cette Release pendant que vous les modifiez, en signalant ce qu’il trouve dans le fichier et dans le panneau Problèmes. Aggrega: Show topology graph, dans la palette de commandes, dessine les composants de la Release et les connexions entre eux. Aggrega: Build, Aggrega: Preview build et Aggrega: Pull agissent sur la même Release, et chacune est aussi un bouton du panneau Commands de la vue Aggrega dans la barre d’activité ; Build écrit ses fichiers dans le dist/ du dossier. Utiliser Aggrega dans Visual Studio Code couvre le reste.
Exécution
Docker Compose exécute votre image comme le service rendu ci-dessus, PORT compris. L’image doit écouter sur ce port sur toutes les interfaces, et non sur 127.0.0.1, l’adresse par défaut du serveur d’API d’ADK. Le serveur d’API propre à ADK, adk api_server, sert le répertoire de configuration tel quel, de sorte que l’image ne nécessite aucun code de votre part. Un Dockerfile à la racine du projet, à côté de support_agent/ :
FROM python:3.12-slimRUN pip install --no-cache-dir google-adk==2.13.0COPY 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 sert les répertoires d’agents du dossier qu’il désigne, et la commande lui transmet PORT. --auto_create_session ouvre une session la première fois qu’une requête à /run la nomme, si bien qu’une seule requête atteint l’agent. Construisez l’image, écrivez son nom à la place de ghcr.io/example/support-agent:1.0.0 dans support_agent/import-answers.yaml, puis relancez l’import avec --sync, qui écrit la nouvelle réponse dans les ébauches et refait le pull ; lancez ensuite le build :
docker build -t support-agent:local .aggrega import support_agent --syncaggrega build --release release.yamlDéfinissez ensuite la clé dans votre shell et démarrez la pile :
export GOOGLE_API_KEY='your Gemini API key'docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait-p nomme le projet, comme l’explique l’étape d’exécution de Déroulement d’une importation. --wait rend la main dès que le conteneur s’exécute, puisque le build ne donne au service aucun contrôle d’état, et le serveur répond un instant plus tard ; répétez donc une requête qu’il refuse.
Tester
Envoyez un message à l’agent à http://127.0.0.1:8000, l’adresse que published_port publie. La requête nomme un utilisateur et une session, et /run ouvre la session à son premier message :
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 réponse, celle de Gemini, revient sous la forme d’une liste des événements que le tour a ajoutés à la session. L’exécution a utilisé un espace réservé pour la clé, si bien que Gemini l’a refusée : la requête a répondu HTTP 500, Internal Server Error, et le journal du service, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, en donne la raison :
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 répond ["support_agent"], les agents que le serveur contient.
Arrêtez la pile avec :
docker compose -p support-agent -f dist/compose/docker-compose.yaml downSur Kubernetes
Le même agent s’importe pour Kubernetes avec --target helm. Un cluster récupère ses images depuis un registre : poussez donc l’image que vous avez construite vers un registre que votre cluster lit, et écrivez son nom à la place de l’image donnée en réponse dans support_agent/import-answers.yaml ; l’exécution l’a poussée vers un registre situé sur la machine même du cluster, sous le nom localhost:5000/support-agent:1.0.0. La seconde réponse de ce fichier nomme le Secret dans lequel l’agent lit la clé d’API Gemini, google-api-key. Les brouillons pour Docker Compose se trouvent déjà dans source : rédigez donc ceux-ci dans un dossier à part, et lancez le build depuis celui-ci :
aggrega import support_agent --target helm --output-dir helmcd helmaggrega build --release release.yamlLe build écrit de simples manifestes Kubernetes sous dist/helm/ à la racine de l’espace de travail, source, qui depuis helm est ../dist/helm/. Créez le Secret google-api-key dans le namespace auquel vous appliquez, contenant la clé sous la clé de données value, et appliquez le dossier comme l’explique l’étape d’exécution de Comment se déroule un import. Le Service de l’agent est support-agent-default : redirigez-y un port local, et laissez la commande s’exécuter :
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000Depuis un autre terminal, le message ci-dessus atteint l’agent à la même adresse, sans modification. L’exécution a obtenu la même Internal Server Error, et kubectl logs -n <namespace> deploy/support-agent indique le même refus de la clé fictive.