Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Importowanie agenta Google ADK

Ten przewodnik krok po kroku importuje Agent Config aplikacji zbudowanej na Agent Development Kit (ADK) od Google — jednego agenta odpowiadającego na pytania klientów o ich zamówienia — i buduje aplikację dla Docker Compose. Import tworzy szkic każdego pliku, który odczytuje kompilacja: agenta i jego model Gemini, klucz, który agent przedstawia modelowi jako odwołanie do zmiennej, oraz realizacje każdego z nich. Pyta jeden raz o jedyną wartość, której nie zawiera żadna konfiguracja: obraz, w którym działa aplikacja. Każdy plik i każdy blok wyjścia poniżej pochodzi z rzeczywistego uruchomienia; konfiguracja i każdy etap przewodnika znajdują się w przykładzie import-google-adk, w którym skrypt sprawdzający ponownie uruchamia import, porównuje to, co zapisuje, to, co wypisuje, oraz bloki cytowane na tej stronie z przechowywanymi tam plikami, a także waliduje i buduje to, co zapisał import.

Generowanie przykładu

Ten import można uruchomić poleceniami z tej strony albo zlecić to asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu; kolejne, poniżej, przechodzi do folderu source w nowym folderze, który zawiera to, co importuje ta strona, i w którym uruchamia się import:

Terminal window
cd import-google-adk

Folder source wygenerowanego przykładu otwarty w Visual Studio Code, pokazujący konfigurację agenta: support_agent na gemini-2.5-flash z narzędziem google_search.

Projekt

ADK może deklarować agentów aplikacji w plikach Agent Config zamiast w kodzie: adk create --type=config zapisuje root_agent.yaml, konfigurację agenta głównego, oraz obok niego plik środowiskowy. Ten plik, napisany na potrzeby tego przewodnika, deklaruje jednego agenta na gemini-2.5-flash od Gemini, z narzędziem Google Search dostarczanym przez 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

Import nigdy nie odczytuje pliku środowiskowego, który zwykle zawiera klucz wysyłany przez aplikację do Gemini, więc przykład go nie zawiera. W katalogu głównym projektu plik .aggrega-config.yaml czyni folder przestrzenią roboczą:

# 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

Import odwołuje się do encji Components z katalogu dla agenta ADK i modelu Gemini, a --target tworzy szkic encji Manifest na podstawie jego encji Recipes. Przestrzeń robocza nie wskazuje żadnego folderu katalogu, więc import odczytuje katalog biblioteki standardowej z rejestru, z którego pobiera swój importer: podpisaną migawkę opublikowanego katalogu, którą pierwszy import pobiera, weryfikuje i przechowuje w pamięci podręcznej treści przestrzeni roboczej i którą rekord zapisywany przez import obok jego szkiców wskazuje za pomocą jej skrótu. Przestrzeń robocza, która wskazuje własne foldery katalogu — w AGGREGA_CATALOG_DIRS lub pod workspace.catalog_dirs — importuje zamiast tego względem nich.

O co pyta import

Agent Config wskazuje model agenta, nigdy obraz, w którym działa aplikacja: ten obraz buduje się z własnego projektu. Katalog nie zawiera domyślnego obrazu dla aplikacji zbudowanej na ADK, więc import o niego pyta. W terminalu pyta i zapisuje odpowiedź w szkicach oraz w pliku odpowiedzi import-answers.yaml wewnątrz importowanego katalogu support_agent/, dzięki czemu następny import odczytuje ją stamtąd i o nic nie pyta. Bez terminala — w ciągłej integracji lub przez potok — o nic nie pyta: zapisuje plik z pustym kluczem i zatrzymuje się, wskazując plik. Przykład zawiera już ten plik z odpowiedzią dotyczącą obrazu, ghcr.io/example/support-agent:1.0.0, która oznacza obraz budowany we własnym zakresie:

# 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"

Druga odpowiedź dotyczy kompilacji dla Kubernetes z --target helm: tam agent odczytuje klucz API Gemini z obiektu Secret w Kubernetes, a odpowiedzią jest nazwa tego obiektu Secret, google-api-key, nigdy sam klucz. Kompilacja dla Docker Compose odczytuje natomiast klucz z powłoki, więc ten import nie używa tej odpowiedzi. Plik odpowiedzi importu opisuje plik, pytania i zasady dotyczące odpowiedzi dla sekretu.

aggrega import wymienia każdą flagę przyjmowaną przez polecenie, w tym --answers, która wskazuje plik odpowiedzi przechowywany gdzie indziej.

Należy przejść do source:

Terminal window
cd source

Uruchomienie importu

Należy wskazać katalog agenta. Import odczytuje jego root_agent.yaml:

Terminal window
aggrega import support_agent --target compose

Na standardowym wyjściu wymienia to, co zapisał:

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

Na standardowym wyjściu błędów, gdzie <workspace> oznacza folder, w którym go uruchomiono:

[… 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)

Import uruchomiony z edytora: szkice encji Aggregate, Release i Manifest pojawiają się obok konfiguracji agenta, wyjście Aggrega wymienia, jak zmapowano agenta i jego model, oraz zapisane pliki, a powiadomienie informuje, że import utworzył szkice 3 plików, rozpoznanych jako google-adk.

  • Wiersz info wskazuje odpowiedź, której nie używają szkice dla Docker Compose, przechowywaną w pliku odpowiedzi na potrzeby kompilacji dla Kubernetes.
  • Wiersze mapped mówią, że agent jest instancją agenta ADK z biblioteki standardowej, core/ai-agent/google-adk, a model, który wskazuje, jest instancją core/ai-model/gemini. Ich poziom to NONE: import ADK odwołuje się do tych encji Components na podstawie tego, co wskazuje konfiguracja, zamiast porównywać każdą z nich z katalogiem.
  • Wiersz made no choice mówi, że dla narzędzia Google Search nie tworzy się żadnego szkicu: jest to narzędzie dostarczane przez ADK i działa wewnątrz aplikacji.
  • Wiersz Pull complete oznacza, że import pobiera to, od czego zależy szkic encji Release, tak jak robi to aggrega pull, do release.lock, dzięki czemu szkice od razu przechodzą walidację i budowanie. Z --offline import niczego nie pobiera i podaje polecenie aggrega pull, które należy uruchomić.

Co zapisuje import

Encje Aggregate, Release i Manifest otrzymują nazwę imported/support-agent od pola name agenta głównego, support_agent, sprowadzonego do support-agent, w przestrzeni nazw określonej przez ustawienie target_namespace importera, imported, o ile nie ustawi się innej (Ustawienia).

aggregate.yaml — agent podłączony do modelu, z kluczem, który przedstawia, zadeklarowanym na połączeniu, oraz model, poprzedzone komentarzami, które mówią, co zostało odczytane, a co nie:

# 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 udostępnia aplikację od jej agenta głównego, więc szkic zawiera jedną instancję na drzewo agentów, nazwaną od jego agenta głównego. instruction agenta nie jest przenoszona: aplikacja odczytuje ją z własnej konfiguracji, którą zawiera obraz.

ADK obsługuje gemini-2.5-flash przez swoją klasę Gemini, która wysyła żądania do API Gemini, dlatego szkic podłącza model do gniazda model agenta, które przyjmuje wyłącznie API Gemini. Gemini jest usługą hostowaną, dlatego encja Component agenta odrzuca połączenie z nią, które nie niesie żadnych poświadczeń; połączenie deklaruje je pod kluczem GOOGLE_API_KEY. Model, który ADK obsługuje w jakikolwiek inny sposób — nazwa taka jak gpt-4o, którą ADK obsługuje przez własną klasę, lub ciąg modelu LiteLLM, taki jak openai/gpt-4o — nie zostaje do niczego podłączony: komentarz nad instancją go wskazuje, a połączenie pozostawia się użytkownikowi, jak opisuje Czym staje się drzewo agentów.

release.yaml — środowisko, obraz, opublikowany port i źródło klucza:

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: {}

Środowisko development to wartość domyślna, którą zapisuje import, ponieważ żadna konfiguracja go nie wskazuje; należy ją zmienić tam, gdzie encja Release jest wdrażana gdzie indziej. Obraz to odpowiedź, którą import odczytał z support_agent/import-answers.yaml. published_port to 8000, port, na którym nasłuchuje aplikacja, więc odpowiada ona pod http://127.0.0.1:8000 na maszynie lokalnej; jak mówi komentarz, każdy proces na tej maszynie może do niej tam dotrzeć i nic poza nim, a usunięcie tego wiersza pozostawia aplikację wyłącznie w sieci stosu. Konfiguracja nie wskazuje żadnej zmiennej dla klucza, dlatego połączenie odczytuje go z ${GOOGLE_API_KEY}, zmiennej, którą odczytują biblioteki klienckie API Gemini, jako odwołanie do zmiennej, a nigdy jako wartość.

manifest.yaml — encja Recipe dla Compose każdego typu oraz realizacja, która zapisuje odwołanie do zmiennej klucza w pliku Compose dosłownie:

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 rejestruje, według digestu, encje katalogu, na które została rozwiązana encja Release, a .aggrega-import.json to zapis tego, co utworzył import, odczytywany przez późniejsze aggrega import --sync.

Walidacja i kompilacja

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

Szkic encji Release otwarty w edytorze po walidacji; wyjście Aggrega i powiadomienie zgłaszają, że nie znaleziono problemów.

Build szkicu encji Release: w Eksploratorze pojawia się folder dist, wyjście Aggrega wymienia zapisany plik Docker Compose, a powiadomienie informuje, że zapisano 1 plik.

Walidacja wypisuje:

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)

oraz build, gdzie <workspace> oznacza folder, w którym go uruchomiono:

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

Wiersz notice ma charakter informacyjny: encja Feature sekretu przyjmuje swoje origin z values encji Aggregate lub z infra encji Release, a komunikat informuje, że jeden liść jest zadeklarowany w obu miejscach. Nie zmienia żadnego werdyktu.

Usługa agenta w 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

Aplikacja otrzymuje port, na którym nasłuchuje jej serwer, jako PORT, a klucz jako GOOGLE_API_KEY, który klient Gemini z ADK wysyła do API Gemini. Model nie dostaje własnej usługi: klient wysyła swoje żądania na własny adres API Gemini i nie odczytuje innego ze swojego środowiska. Klucz jest odwołaniem do zmiennej, wypełnianym z powłoki przy uruchamianiu stosu. Encja Recipe Compose dla agenta ADK publikuje port na maszynie lokalnej tylko wtedy, gdy encja Release ustawia published_port w infra agenta, i wówczas wyłącznie na adresie pętli zwrotnej 127.0.0.1; bez tego usługa jest osiągalna tylko w sieci stosu.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `import-google-adk`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `import-google-adk` i bez `dir`: zapisuje ono przykład w nowym folderze `import-google-adk`, którego folder `source` zawiera to, co importuje ta strona. Następnie wywołaj narzędzie `import` z `workspace_root` ustawionym na `import-google-adk/source`, `source` ustawionym na `support_agent` i `target` ustawionym na `compose`: odczytuje ono potrzebne odpowiedzi z `import-answers.yaml` w folderze `support_agent`, zapisuje swoje szkice w `import-google-adk/source` i pobiera to, czego one potrzebują. Następnie wywołaj narzędzie `validate` z `workspace_root` ustawionym na `import-google-adk/source` i `release` ustawionym na `release.yaml` oraz narzędzie `build` z `workspace_root` ustawionym na `import-google-adk/source`, `release` ustawionym na `release.yaml` i `write` ustawionym na true. Podaj mi, które pliki zapisał build; znajdują się w `import-google-adk/source/dist/`.

Otwieranie w VS Code

Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code folder import-google-adk/source, w którym import zapisał swoje szkice. Folder zawiera jedną encję Release, szkic release.yaml, więc edytor wybiera ją automatycznie i podczas edycji sprawdza szkice względem tej encji Release, oznaczając znalezione problemy w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w dist/ tego folderu. Używanie Aggrega w Visual Studio Code opisuje resztę.

Uruchomienie

Docker Compose uruchamia obraz jako wyrenderowaną powyżej usługę, łącznie z PORT. Obraz musi nasłuchiwać na tym porcie na wszystkich interfejsach, a nie na 127.0.0.1, domyślnym adresie serwera API ADK. Własny serwer API ADK, adk api_server, udostępnia katalog konfiguracji w niezmienionej postaci, więc obraz nie wymaga żadnego własnego kodu. Dockerfile w katalogu głównym projektu, obok 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 udostępnia katalogi agentów ze wskazanego folderu, a polecenie przekazuje mu PORT. --auto_create_session otwiera sesję, gdy żądanie do /run po raz pierwszy ją wskaże, więc jedno żądanie dociera do agenta. Należy zbudować obraz, wpisać jego nazwę w miejsce ghcr.io/example/support-agent:1.0.0 w support_agent/import-answers.yaml i ponownie zaimportować z --sync, które zapisuje nową odpowiedź w szkicach i ponownie wykonuje pull; następnie wykonać build:

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

Następnie należy ustawić klucz w powłoce i uruchomić 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 nadaje nazwę projektowi, co wyjaśnia krok uruchamiania w Jak przebiega import. --wait kończy działanie, gdy tylko kontener zostanie uruchomiony, ponieważ build nie nadaje usłudze żadnej kontroli stanu, a serwer odpowiada chwilę później, dlatego odrzucone żądanie należy powtórzyć.

Testowanie

Wiadomość do agenta należy wysłać pod adres http://127.0.0.1:8000, który publikuje published_port. Żądanie wskazuje użytkownika i sesję, a /run otwiera sesję przy jej pierwszej wiadomości:

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

Odpowiedź, pochodząca od Gemini, wraca jako lista zdarzeń, które dana tura dodała do sesji. Przebieg użył symbolu zastępczego jako klucza, więc Gemini go odrzucił: żądanie zwróciło HTTP 500, Internal Server Error, a log usługi, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, podaje przyczynę:

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 zwraca ["support_agent"], czyli agentów, których przechowuje serwer.

Stack zatrzymuje się poleceniem:

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

Na Kubernetes

Ten sam agent importuje się dla Kubernetes z --target helm. Klaster pobiera swoje obrazy z rejestru, więc zbudowany obraz należy wypchnąć do rejestru, który klaster odczytuje, i wpisać jego nazwę w miejsce obrazu podanego jako odpowiedź w support_agent/import-answers.yaml; przebieg wypchnął go do rejestru na maszynie samego klastra, jako localhost:5000/support-agent:1.0.0. Druga odpowiedź w tym pliku wskazuje obiekt Secret, z którego agent odczytuje klucz API Gemini, google-api-key. Wersje robocze dla Docker Compose znajdują się już w source, więc te należy utworzyć w osobnym folderze i z niego zbudować:

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

Build zapisuje zwykłe manifesty Kubernetes w dist/helm/ w katalogu głównym obszaru roboczego, source, który z perspektywy helm to ../dist/helm/. Należy utworzyć obiekt Secret google-api-key w przestrzeni nazw, do której się stosuje, z kluczem pod kluczem danych value, i zastosować folder, jak wyjaśnia krok uruchamiania w Jak przebiega import. Obiekt Service agenta to support-agent-default: należy przekierować do niego lokalny port i pozostawić polecenie uruchomione:

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

Z innego terminala powyższa wiadomość dociera do agenta pod tym samym adresem, bez zmian. Przebieg otrzymał ten sam Internal Server Error, a kubectl logs -n <namespace> deploy/support-agent podaje to samo odrzucenie klucza zastępczego.