Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Импорт агента Google ADK

Это пошаговое руководство импортирует Agent Config приложения, построенного на Agent Development Kit (ADK) от Google, — одного агента, отвечающего на вопросы клиентов об их заказах, — и собирает приложение для Docker Compose. Импорт создаёт черновик каждого файла, который читает сборка: агента и его модель Gemini, ключ, который агент предъявляет модели в виде ссылки на переменную, и реализации каждого из них. Он один раз запрашивает единственное значение, которого нет ни в одной конфигурации, — образ, в котором работает приложение. Каждый файл и каждый блок вывода ниже взяты из реального запуска; конфигурация и каждый этап руководства находятся в примере import-google-adk, где проверочный скрипт заново запускает импорт, сравнивает то, что он записывает, то, что он выводит, и блоки, которые цитирует эта страница, с хранящимися там файлами, а также проверяет и собирает то, что записал импорт.

Создание примера

Этот импорт можно выполнить командами с этой страницы или поручить его вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку; следующая, ниже, переходит в её папку source, которая содержит то, что импортирует эта страница, и в которой выполняется импорт:

Terminal window
cd import-google-adk

Папка source сгенерированного примера, открытая в Visual Studio Code, с конфигурацией агента: support_agent на gemini-2.5-flash с инструментом google_search.

Проект

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.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

Импорт никогда не читает файл окружения, который обычно содержит ключ, отправляемый приложением в 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:

Terminal window
cd source

Запуск импорта

Укажите папку агента. Импорт читает её root_agent.yaml:

Terminal window
aggrega import support_agent --target compose

В стандартный вывод он выводит список записанного:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .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 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)

Импорт, запущенный из редактора: черновики сущностей Aggregate, Release и Manifest появляются рядом с конфигурацией агента, вывод Aggrega перечисляет, как были сопоставлены агент и его модель, и записанные файлы, а уведомление сообщает, что импорт создал черновики 3 файлов, распознанных как google-adk.

  • Строка 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/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 обслуживает приложение от его корневого агента, поэтому черновик содержит один экземпляр на каждое дерево агентов, названный по его корневому агенту. 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/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: {}

Среда 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/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 фиксирует по дайджесту сущности каталога, в которые разрешилась сущность Release, а .aggrega-import.json — это сведения о том, что записал импорт; их читает последующий aggrega import --sync.

Проверка и сборка

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

Черновик сущности Release, открытый в редакторе после валидации; вывод Aggrega и уведомление сообщают, что проблем не найдено.

Сборка черновика сущности Release: в проводнике появляется папка dist, вывод Aggrega перечисляет записанный файл Docker Compose, а уведомление сообщает, что записан 1 файл.

Проверка выводит:

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-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 обслуживает каталоги агентов в указанной папке, а команда передаёт ему PORT. --auto_create_session открывает сессию, когда запрос к /run впервые называет её, поэтому один запрос доходит до агента. Соберите образ, запишите его имя вместо ghcr.io/example/support-agent:1.0.0 в support_agent/import-answers.yaml и снова выполните импорт с --sync, который записывает новый ответ в черновики и снова выполняет pull; затем выполните сборку:

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

Затем задайте ключ в своей оболочке и запустите стек:

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 задаёт имя проекта, как объясняет шаг запуска в разделе Как выполняется импорт. --wait возвращает управление, как только контейнер запущен, поскольку сборка не задаёт сервису проверку работоспособности, а сервер отвечает чуть позже, поэтому повторите запрос, который он отклонит.

Тестирование

Отправьте агенту сообщение по адресу http://127.0.0.1:8000, который публикует published_port. Запрос указывает пользователя и сессию, а /run открывает сессию при её первом сообщении:

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."}]}}'

Ответ — от 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"], то есть агентами, которые содержит сервер.

Остановите стек командой:

Terminal window
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, поэтому создайте эти черновики в отдельной папке и собирайте из неё:

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

Сборка записывает обычные манифесты Kubernetes в dist/helm/ в корне рабочего пространства, source, что из helm является ../dist/helm/. Создайте Secret google-api-key в пространстве имён, к которому применяете, с ключом под ключом данных value, и примените папку, как объясняет шаг запуска в Как выполняется импорт. Service агента — support-agent-default: перенаправьте на него локальный порт и оставьте команду запущенной:

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

Из другого терминала приведённое выше сообщение достигает агента по тому же адресу без изменений. Запуск получил ту же Internal Server Error, а kubectl logs -n <namespace> deploy/support-agent называет тот же отказ для ключа-заполнителя.