Импорт агента 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 называет тот же отказ для ключа-заполнителя.