Імпорт агента Google ADK
Цей покроковий посібник імпортує Agent Config застосунку, створеного на Agent Development Kit (ADK) від Google, — одного агента, який відповідає на запитання клієнтів про їхні замовлення, — і збирає застосунок для Docker Compose. Імпорт створює чернетку кожного файлу, який читає збірка: агента та його модель Gemini, ключ, який агент передає моделі як посилання на змінну, і реалізації кожного з них. Він один раз запитує єдине значення, якого не містить жодна конфігурація, — образ, у якому працює застосунок. Кожен файл і кожен блок виводу нижче взято зі справжнього запуску; конфігурація та кожен етап посібника є в прикладі import-google-adk, де скрипт перевірки знову запускає імпорт, порівнює те, що він записує, те, що він виводить, і блоки, які цитує ця сторінка, із файлами, що там зберігаються, а також перевіряє та збирає те, що записав імпорт.
Створення прикладу
Цей імпорт можна виконати командами з цієї сторінки або доручити його вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example import-google-adkПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку; наступна, нижче, переходить у її теку source, яка містить те, що імпортує ця сторінка, і де виконується імпорт:
cd import-google-adk
Проєкт
ADK може оголошувати агентів застосунку у файлах Agent Config замість коду: adk create --type=config записує root_agent.yaml, конфігурацію кореневого агента, і файл середовища поруч із ним. Цей файл, написаний для цього посібника, оголошує одного агента на gemini-2.5-flash від Gemini з інструментом Google Search, який постачається з 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_searchІмпорт ніколи не читає файл середовища, який зазвичай містить ключ, що його застосунок надсилає до Gemini, тому приклад його не містить. У корені проєкту файл .aggrega-config.yaml робить теку робочим простором:
# 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Імпорт посилається на сутності Components агента ADK і моделі Gemini з каталогу, а --target створює чернетку сутності Manifest із сутностей Recipes цього каталогу. Робочий простір не вказує жодної теки каталогу, тому імпорт читає каталог стандартної бібліотеки з реєстру, з якого отримує свій імпортер: підписаний знімок опублікованого каталогу, який перший імпорт отримує, перевіряє та зберігає в кеші вмісту робочого простору і який запис, що його імпорт пише поруч зі своїми чернетками, називає за дайджестом. Робочий простір, що вказує власні теки каталогу — у AGGREGA_CATALOG_DIRS або в workspace.catalog_dirs, — натомість імпортує на їх основі.
Що запитує імпорт
Agent Config називає модель агента, але ніколи не образ, у якому працює застосунок: цей образ ви збираєте зі свого проєкту. Каталог не містить образу за замовчуванням для застосунку, створеного на ADK, тому імпорт запитує його. У терміналі він запитує та записує відповідь у чернетки й у файл відповідей import-answers.yaml у теці, яку імпортує, support_agent/, тож наступний імпорт читає її звідти й нічого не запитує. Без термінала — у безперервній інтеграції або через конвеєр — він нічого не запитує: записує файл із порожнім ключем і зупиняється, називаючи файл. Приклад уже містить цей файл із відповіддю для образу, ghcr.io/example/support-agent:1.0.0, яка позначає образ, що ви збираєте:
# 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"Друга відповідь призначена для збірки для Kubernetes з --target helm: там агент читає ключ API Gemini з об’єкта Secret Kubernetes, а відповіддю є назва цього Secret, google-api-key, а не сам ключ. Збірка для Docker Compose натомість читає ключ із вашої оболонки, тому цей імпорт не використовує цю відповідь. Файл відповідей імпорту описує файл, запитання та правила для відповіді щодо секрету.
aggrega import перелічує кожен прапорець, який приймає команда, зокрема --answers, що вказує файл відповідей, збережений деінде.
Перейдіть у source:
cd sourceЗапуск імпорту
Укажіть теку агента. Імпорт читає її root_agent.yaml:
aggrega import support_agent --target composeУ стандартний вивід він виводить перелік записаного:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonУ стандартний потік помилок, де <workspace> позначає теку, у якій ви його запустили:
[… 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)
- Рядок
infoназиває відповідь, яку не використовують чернетки для Docker Compose і яка зберігається у файлі відповідей для збирання для Kubernetes. - Рядки
mappedозначають, що агент є екземпляром агента ADK зі стандартної бібліотеки,core/ai-agent/google-adk, а модель, яку він називає, є екземпляромcore/ai-model/gemini. Їхній рівень —NONE: імпорт ADK посилається на ці сутності Components за тим, що називає конфігурація, а не зважуючи кожну з них відносно каталогу. - Рядок
made no choiceозначає, що інструмент Google Search не потрапляє в чернетку ні в якому вигляді: це інструмент, який постачається з ADK, і він працює всередині застосунку. - Рядок
Pull completeозначає, що імпорт отримує те, від чого залежить чернетка сутності Release, як це робитьaggrega pull, уrelease.lock, щоб чернетки одразу проходили валідацію та збірку. З--offlineімпорт нічого не завантажує і називає командуaggrega pull, яку слід виконати.
Що він записує
Сутності Aggregate, Release і Manifest отримують назву imported/support-agent за полем name кореневого агента, support_agent, скороченим до support-agent, у просторі імен, який задає налаштування target_namespace імпортера, тобто imported, якщо ви не задасте інший (Налаштування).
aggregate.yaml — агент, з’єднаний із моделлю, із ключем, який він пред’являє, оголошеним на з’єднанні, і сама модель; на початку — коментарі про те, що було прочитано, а що ні:
# 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 обслуговує застосунок від його кореневого агента, тому чернетка містить один екземпляр на кожне дерево агентів, названий за його кореневим агентом. instruction агента не переноситься: застосунок читає його з власної конфігурації, яка міститься в образі.
ADK обслуговує gemini-2.5-flash через свій клас Gemini, який надсилає запити до Gemini API, тож чернетка під’єднує модель до сокета model агента, який приймає лише Gemini API. Gemini — це хостований сервіс, тож сутність Component агента відхиляє з’єднання з ним, яке не несе жодних облікових даних; з’єднання оголошує їх під ключем GOOGLE_API_KEY. Модель, яку ADK обслуговує будь-яким іншим способом, — назва на кшталт gpt-4o, яку ADK обслуговує через власний клас, або рядок моделі LiteLLM на кшталт openai/gpt-4o — ні до чого не під’єднується: коментар над екземпляром називає її, а з’єднання залишається за вами, як описує розділ Чим стає дерево агентів.
release.yaml — середовище, образ, опублікований порт і джерело ключа:
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: {}Середовище development — це типове значення, яке записує імпорт, бо жодна конфігурація не називає середовища; змініть його там, де сутність Release розгортається деінде. Образ — це відповідь, яку імпорт прочитав із support_agent/import-answers.yaml. published_port дорівнює 8000, порту, який слухає застосунок, тож він відповідає за адресою http://127.0.0.1:8000 на вашій машині; як каже його коментар, будь-який процес на цій машині може дістатися до нього там, а ніщо інше не може, і видалення рядка залишає застосунок лише в мережі стека. Конфігурація не називає змінної для ключа, тож з’єднання читає його з ${GOOGLE_API_KEY}, змінної, яку читають клієнтські бібліотеки Gemini API, як посилання на змінну, а ніколи не як значення.
manifest.yaml — сутність Recipe для Compose кожного типу і реалізація, яка записує посилання на змінну ключа у файл 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 фіксує за дайджестом сутності каталогу, до яких розв’язалася сутність Release, а .aggrega-import.json — це відомості про те, що записав імпорт; їх читає пізніший aggrega import --sync.
Перевірка та збирання
aggrega validate --release release.yamlaggrega build --release release.yaml

Перевірка виводить:
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)і збірка, де <workspace> позначає теку, у якій ви її запустили:
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Рядок notice має рекомендаційний характер: секретна сутність Feature приймає свій origin із values сутності Aggregate або з infra сутності Release, і повідомлення сповіщає, що один листок оголошено в обох. Воно не змінює жодного вердикту.
Сервіс агента в 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Застосунок отримує порт, який слухає його сервер, як PORT, а ключ — як GOOGLE_API_KEY, який клієнт Gemini з ADK надсилає до Gemini API. Модель не отримує власного сервісу: клієнт надсилає свої запити на власну адресу Gemini API і не зчитує жодної іншої зі свого середовища. Ключ — це посилання на змінну, яке заповнюється з вашої оболонки під час запуску стека. Сутність Recipe Compose для агента ADK публікує порт на вашій машині лише там, де сутність Release задає published_port в infra агента, і тоді лише на адресі зворотної петлі 127.0.0.1; без цього сервіс доступний лише в мережі стека.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте в нього цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте самостійно жодної теки. Якщо тека Workspace ще не містить теки `import-google-adk`, викличте один раз інструмент `scaffold` з `example`, встановленим на `import-google-adk`, і без `dir`: він записує приклад у нову теку `import-google-adk`, тека `source` якої містить те, що імпортує ця сторінка. Потім викличте інструмент `import` з `workspace_root`, встановленим на `import-google-adk/source`, `source`, встановленим на `support_agent`, і `target`, встановленим на `compose`: він читає потрібні йому відповіді з `import-answers.yaml` у теці `support_agent`, записує свої чернетки в `import-google-adk/source` і завантажує те, що їм потрібно. Потім викличте інструмент `validate` з `workspace_root`, встановленим на `import-google-adk/source`, і `release`, встановленим на `release.yaml`, та інструмент `build` з `workspace_root`, встановленим на `import-google-adk/source`, `release`, встановленим на `release.yaml`, і `write`, встановленим на true. Скажіть мені, які файли записала збірка; вони лежать у `import-google-adk/source/dist/`.Відкриття у VS Code
Зі встановленим розширенням Aggrega для Visual Studio Code відкрийте у VS Code теку import-google-adk/source, куди імпорт записав свої чернетки. Тека містить одну сутність Release, чернетку release.yaml, тож редактор вибирає її за вас і під час редагування перевіряє чернетки щодо цієї сутності Release, позначаючи знайдене у файлі та на панелі «Проблеми». Aggrega: Show topology graph у палітрі команд малює компоненти сутності Release і з’єднання між ними. Aggrega: Build, Aggrega: Preview build і Aggrega: Pull діють на ту саму сутність Release, і кожна з них також є кнопкою на панелі Commands подання Aggrega на панелі дій; Build записує свої файли в dist/ цієї теки. Використання Aggrega у Visual Studio Code описує решту.
Запуск
Docker Compose запускає ваш образ як відрендерений вище сервіс, разом із PORT. Образ має слухати цей порт на всіх інтерфейсах, а не на 127.0.0.1 — типовій адресі API-сервера ADK. Власний API-сервер ADK, adk api_server, віддає каталог конфігурації як є, тож образ не потребує вашого коду. Dockerfile у корені проєкту, поруч із 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 обслуговує каталоги агентів у вказаній теці, а команда передає йому PORT. --auto_create_session відкриває сесію, коли запит до /run уперше називає її, тож один запит доходить до агента. Зберіть образ, запишіть його назву замість ghcr.io/example/support-agent:1.0.0 у support_agent/import-answers.yaml і знову виконайте імпорт із --sync, який записує нову відповідь у чернетки й знову виконує pull; потім виконайте збирання:
docker build -t support-agent:local .aggrega import support_agent --syncaggrega build --release release.yamlПотім встановіть ключ у своїй оболонці й запустіть стек:
export GOOGLE_API_KEY='your Gemini API key'docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait-p задає назву проєкту, як пояснює крок запуску в розділі Як виконується імпорт. --wait повертає керування, щойно контейнер запуститься, оскільки збирання не задає сервісу перевірки стану, а сервер відповідає трохи пізніше, тож повторіть запит, який він відхилить.
Тестування
Надішліть агенту повідомлення на http://127.0.0.1:8000, адресу, яку публікує published_port. Запит вказує користувача й сесію, а /run відкриває сесію під час її першого повідомлення:
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."}]}}'Відповідь, від Gemini, повертається як список подій, які цей хід додав до сесії. Запуск використав заповнювач замість ключа, тож Gemini його відхилив: запит відповів HTTP 500, Internal Server Error, а журнал сервісу, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, називає причину:
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 відповідає ["support_agent"], тобто агентами, які містить сервер.
Зупиніть стек командою:
docker compose -p support-agent -f dist/compose/docker-compose.yaml downУ Kubernetes
Той самий агент імпортується для Kubernetes з --target helm. Кластер завантажує свої образи з реєстру, тому надішліть зібраний образ до реєстру, який читає ваш кластер, і запишіть його назву замість образу, вказаного як відповідь у support_agent/import-answers.yaml; запуск надіслав його до реєстру на власній машині кластера як localhost:5000/support-agent:1.0.0. Друга відповідь у цьому файлі називає Secret, з якого агент зчитує ключ API Gemini, — google-api-key. Чернетки для Docker Compose вже лежать у source, тож створіть ці чернетки в окремій теці та збирайте з неї:
aggrega import support_agent --target helm --output-dir helmcd helmaggrega build --release release.yamlЗбірка записує звичайні маніфести Kubernetes у dist/helm/ у корені робочого простору, source, що з helm є ../dist/helm/. Створіть Secret google-api-key у просторі імен, до якого застосовуєте, з ключем під ключем даних value, і застосуйте теку, як пояснює крок запуску в Як виконується імпорт. Service агента — support-agent-default: перенаправте на нього локальний порт і залиште команду запущеною:
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000З іншого термінала наведене вище повідомлення досягає агента за тією самою адресою без змін. Запуск отримав ту саму Internal Server Error, а kubectl logs -n <namespace> deploy/support-agent називає ту саму відмову для ключа-заповнювача.