Google ADK, budowanie agentów w pięciu językach

Google ADK, framework agentowy dla zespołów spoza Pythona

Większość bibliotek agentowych powstaje w Pythonie i tam zostaje. Zespół pracujący w Javie albo w TypeScripcie ma wtedy do wyboru osobną usługę w innym języku albo pisanie wszystkiego od zera.

Google ADK jest wydawany równolegle w pięciu językach: Pythonie, TypeScripcie, Go, Javie i Kotlinie, z tym samym modelem pojęciowym w każdym. Cztery pierwsze mają wydania stabilne, kotlinowe jest najmłodsze i wciąż przed wersją 1.0. Framework jest otwarty, a jego naturalnym miejscem wdrożenia jest infrastruktura Google, choć nie jest do niej przywiązany.

Model pojęciowy

Agent to model z instrukcją i zestawem narzędzi. Nic zaskakującego i tak jest w każdej bibliotece tej kategorii.

pip install google-adk

from google.adk.agents import Agent

def sprawdz_status(numer: str) -> dict:
    """Zwraca status zamowienia o podanym numerze.

    Wywolaj, gdy klient pyta o swoje zamowienie.
    """
    return {"status": baza.status(numer)}

agent = Agent(
    name="wsparcie",
    model="gemini-2.5-flash",
    instruction="Odpowiadasz na pytania o zamowienia. Bez wstepow.",
    tools=[sprawdz_status],
)

Narzędzie to zwykła funkcja, a jej schemat powstaje z adnotacji typów i dokumentacji. Zdanie mówiące, kiedy funkcję wywołać, poprawia trafność mocniej niż zmiana instrukcji systemowej, i to obowiązuje we wszystkich bibliotekach agentowych.

Ciekawiej robi się przy składaniu agentów. Agent może mieć agentów podrzędnych, którym przekazuje zadanie, a framework udostępnia też gotowe wzorce przepływu: wykonanie sekwencyjne, równoległe i w pętli do spełnienia warunku.

Agenci zagnieżdżeni i przepływy

To główna różnica wobec bibliotek, w których wszystko sprowadza się do jednego agenta z listą narzędzi.

from google.adk.agents import SequentialAgent, ParallelAgent

zbieranie = ParallelAgent(
    name="zbieranie",
    sub_agents=[agent_dokumentacji, agent_zgloszen, agent_kodu],
)

przeplyw = SequentialAgent(
    name="analiza",
    sub_agents=[zbieranie, agent_syntezy],
)

Wykonanie równoległe ma tu konkretny sens. Trzy niezależne wyszukiwania wykonane naraz trwają tyle, co najdłuższe z nich, a nie tyle, co suma. Przy zadaniach obejmujących kilka źródeł różnica jest odczuwalna.

Wykonanie sekwencyjne opisuje etapy, gdzie wynik jednego wchodzi do drugiego. Wykonanie w pętli powtarza krok, aż warunek zostanie spełniony, co przydaje się przy poprawianiu wyniku do skutku.

Warto natomiast uważać na przesadę. Pięciu agentów przekazujących sobie zadanie to system, którego nikt nie prześledzi, a diagnozowanie złej odpowiedzi wymaga przejścia przez pięć śladów. Trzy role wystarczają w większości zastosowań.

Protokół wymiany między agentami

Framework obsługuje natywnie protokół pozwalający agentom z różnych platform rozmawiać ze sobą. To odpowiedź na problem, który pojawia się w większych organizacjach.

Sytuacja wygląda tak: jeden zespół zbudował agenta w tym frameworku, drugi w LangGraphie, trzeci w narzędziu dostawcy chmurowego. Bez wspólnego protokołu połączenie ich oznacza pisanie opakowań dla każdej pary.

Protokół definiuje, jak agent ogłasza swoje możliwości i jak przyjmuje zadania od innych. Agent zdalny wygląda wtedy dla Twojego agenta jak zwykłe narzędzie, niezależnie od tego, w czym został napisany.

Warto rozróżnić to od protokołu udostępniania narzędzi, opisanego w tekście o MCP. Ten drugi łączy agenta z narzędziami, ten pierwszy agentów między sobą. Oba bywają używane w jednym systemie i nie wykluczają się.

Przy wdrożeniu w jednym zespole ten mechanizm jest nadmiarowy. Sens pojawia się, gdy części systemu powstają niezależnie i nikt nie kontroluje wszystkich naraz, a więc typowo w organizacji, gdzie każdy dział buduje własne narzędzia i chce je udostępnić pozostałym.

Stan sesji i pamięć

Agent odpowiadający na pojedyncze pytania nie potrzebuje niczego poza wejściem. Agent prowadzący rozmowę potrzebuje pamiętać, co powiedziano wcześniej, a agent wykonujący zadanie wieloetapowe potrzebuje przechowywać wyniki pośrednie.

Framework rozdziela te rzeczy na trzy poziomy i warto je rozróżniać. Stan sesji trzyma przebieg bieżącej rozmowy. Stan użytkownika przechowuje rzeczy trwałe, na przykład preferencje. Stan aplikacji dotyczy wszystkich sesji i mieści konfigurację wspólną.

from google.adk.sessions import InMemorySessionService

sesje = InMemorySessionService()
sesja = await sesje.create_session(app_name="wsparcie", user_id="klient-118")

Wariant w pamięci nadaje się do testów i znika razem z procesem. Do produkcji potrzebna jest usługa trwała, dostępna w środowisku zarządzanym albo zbudowana samodzielnie na bazie danych.

Warto od razu przemyśleć, co trafia do stanu, a co do bazy aplikacji. Stan sesji jest wygodny i kuszący, więc łatwo wrzucić do niego rzeczy, które powinny żyć w normalnym modelu danych. Zasada jest prosta: stan przechowuje to, co dotyczy przebiegu rozmowy, a baza to, co jest faktem o kliencie niezależnym od tego, czy rozmowa trwa.

Wywołania zwrotne i kontrola przebiegu

Framework pozwala wpiąć własny kod przed wywołaniem modelu, przed wywołaniem narzędzia i po każdym z nich. To odpowiednik warstw pośrednich znanych z serwerów i służy do tych samych rzeczy.

Trzy zastosowania powtarzają się najczęściej. Pierwsze to limity kosztu, gdzie wywołanie zwrotne przerywa pracę po przekroczeniu progu. Drugie to zatwierdzanie działań nieodwracalnych, gdzie kod zatrzymuje wywołanie narzędzia i pyta o zgodę. Trzecie to filtrowanie wejścia, czyli odrzucenie zapytań spoza zakresu, zanim uruchomi się droższy model.

Ten ostatni wzorzec jest wart uwagi z powodów ekonomicznych. Tanie sprawdzenie modelem lekkim odrzuca zapytania niezwiązane z tematem, zanim wejdzie agent z dostępem do narzędzi. Oszczędzasz tokeny i ograniczasz powierzchnię, na której coś może pójść źle.

Warto pamiętać, że wywołanie zwrotne oparte o model nie jest zabezpieczeniem w sensie bezpieczeństwa systemu. Chroni przed typowym błędnym zachowaniem, a nie przed celowym atakiem, więc uprawnienia nadal egzekwuj w kodzie narzędzia.

Ślady i ocena

Framework zbiera zapis przebiegu: wywołania modelu, wywołania narzędzi, przekazania między agentami. To działa lokalnie w narzędziu do podglądu i w środowisku chmurowym po wdrożeniu.

Diagnozowanie agenta bez śladu sprowadza się do zgadywania, dlaczego zrobił coś dziwnego. Ze śladem widzisz dokładnie, które narzędzie wywołał, z jakimi argumentami i co dostał w odpowiedzi. To ta sama zasada co przy LangSmith i innych narzędziach obserwacyjnych.

Poza śladami dostępny jest mechanizm oceny na zestawie przypadków. Definiujesz pytania z oczekiwanym wynikiem i uruchamiasz je po każdej zmianie instrukcji, żeby wychwycić regresję.

Trzydzieści przypadków wystarczy, żeby zobaczyć różnicę między wariantami. Zbieraj je z prawdziwego ruchu, a zwłaszcza z sytuacji, w których agent zawiódł, bo to one wracają najczęściej. Zestaw złożony z przypadków łatwych przechodzi zawsze i nie mówi nic o tym, czy zmiana pomogła.

Wdrożenie

Agent napisany w tym frameworku to zwykły program, więc uruchomisz go tam, gdzie uruchamiasz resztę: w kontenerze, w funkcji bezserwerowej, na własnym serwerze.

Ścieżką rekomendowaną przez producenta jest środowisko zarządzane w jego chmurze, przeznaczone do uruchamiania agentów. Zdejmuje ono z Ciebie skalowanie, utrzymanie sesji i zbieranie śladów, kosztem przywiązania do jednej platformy.

Warto tę decyzję rozdzielić od wyboru frameworka. Sam framework jest otwarty i nie wymaga tej chmury, więc można pisać w nim agenta i wdrożyć go u innego dostawcy. Wygoda środowiska zarządzanego jest realna, natomiast nie jest wymuszona.

Trzecia droga to wdrożenie w kontenerze u dowolnego dostawcy. Traci się wtedy gotowe zarządzanie sesją, ale zyskuje niezależność i możliwość trzymania danych tam, gdzie wymagają tego zasady. Sesje trzeba wtedy oprzeć o własną bazę, co przy istniejącym zapleczu jest zwykle kwestią jednej tabeli, a nie osobnego projektu.

Narzędzia gotowe i własne

Poza własnymi funkcjami framework udostępnia narzędzia wbudowane oraz sposoby podłączenia narzędzi istniejących gdzie indziej.

Wbudowane obejmują wyszukiwanie w sieci i wykonywanie kodu w piaskownicy. Oba działają po stronie dostawcy, więc nie musisz ich uruchamiać sam, kosztem tego, że część przetwarzania dzieje się poza Twoją infrastrukturą.

Drugą drogą jest podłączenie serwerów udostępniających narzędzia przez wspólny protokół. Gotowe integracje, na przykład z repozytorium kodu albo z narzędziem do śledzenia zadań, wpinasz wtedy bez pisania własnych opakowań.

Trzecią jest użycie narzędzi z innych bibliotek agentowych. Framework potrafi opakować narzędzie napisane pod inną bibliotekę, co przydaje się przy migracji albo gdy potrzebna integracja istnieje tylko tam.

Praktyczna kolejność jest odwrotna do intuicyjnej. Najpierw sprawdź, czy narzędzie już istnieje w którymś z tych trzech miejsc. Pisanie własnego opakowania na interfejs programistyczny, który ktoś już opakował, to praca wykonana dwa razy, a utrzymanie spada na Ciebie.

Warto natomiast pamiętać o liczbie. Każde podłączone narzędzie zajmuje miejsce w kontekście i obniża trafność wyboru, więc podłączanie wszystkiego, co dostępne, pogarsza wynik zamiast go poprawiać.

ADK kontra alternatywy

Dla zespołu pracującego w Javie albo w Go pierwszy wiersz bywa jedynym rozsądnym wyborem, bo alternatywy oznaczałyby osobną usługę w Pythonie. To realny argument, którego nie widać w porównaniach skupionych na możliwościach.

Dla zespołu w Pythonie wybór jest szerszy i warto porównać kilka bibliotek na własnym zadaniu. Różnice dotyczą wygody i ekosystemu, bo wszystkie opierają się na tym samym mechanizmie wywoływania narzędzi udostępnianym przez dostawców modeli.

Warto przy tej okazji nazwać rzecz, która ginie w porównaniach bibliotek. O jakości agenta decydują opisy narzędzi, granice postawione w instrukcji i zestaw przypadków, na którym mierzysz zmiany. Te trzy rzeczy przenoszą się między bibliotekami niemal bez zmian, więc praca w nie włożona nie przepada przy ewentualnej migracji.

Wybór frameworka wpływa natomiast na coś innego: na to, jak łatwo wpiąć agenta w istniejący system i jak wygląda wdrożenie. Przy zespole pracującym w Javie i wdrażającym u tego dostawcy różnica jest odczuwalna od pierwszego dnia, a przy zespole pythonowym z własną infrastrukturą znacznie mniejsza.

Typowe błędy

Pierwszy to opisy narzędzi pisane dla programisty. Model czyta ten sam tekst i potrzebuje zdania o tym, kiedy funkcję wywołać, a nie opisu implementacji.

Drugi to zbyt wielu agentów podrzędnych. Pięć poziomów zagnieżdżenia daje system, w którym diagnoza złej odpowiedzi wymaga przejścia przez wszystkie ślady po kolei.

Trzeci to brak limitu kroków. Agent wywołujący narzędzia w pętli zużyje tyle tokenów, ile mu pozwolisz, a przy modelu z górnej półki cenowej to bywa kosztowne.

Czwarty to przekazywanie identyfikatora użytkownika w argumentach narzędzia. Model może podać cudzy, więc tożsamość powinna pochodzić z kontekstu uruchomienia.

Piąty to wdrożenie bez zestawu przypadków. Zmiana instrukcji poprawiająca jedną rozmowę zwykle psuje inną, a bez zestawu nikt tego nie zauważy.

Szósty to sięganie po protokół wymiany między agentami przy jednym zespole. To mechanizm rozwiązujący problem współpracy między niezależnymi zespołami, a przy jednej bazie kodu dokłada złożoność bez korzyści.

FAQ

W jakich językach dostępny jest ADK?

W Pythonie, TypeScripcie, Go, Javie i Kotlinie, z tym samym modelem pojęciowym w każdym i osobnym zestawem stron w dokumentacji dla każdego z nich. To główny wyróżnik wobec bibliotek dostępnych wyłącznie w Pythonie, bo pozwala zespołowi pracować w języku, w którym już pisze resztę systemu. Warto tylko sprawdzić numer wydania wybranej odmiany, bo kotlinowa dołączyła najpóźniej i jest jeszcze przed wersją 1.0.

Czy ADK wymaga chmury Google?

Nie, framework jest otwarty i agenta uruchomisz w kontenerze albo w funkcji bezserwerowej u dowolnego dostawcy. Środowisko zarządzane tego producenta upraszcza skalowanie i zbieranie śladów, ale jest wyborem, a nie warunkiem.

Czym różni się protokół A2A od MCP?

Protokół opisany w tekście o MCP łączy agenta z narzędziami i źródłami danych. Protokół wymiany między agentami łączy agentów ze sobą, także tych napisanych w innych frameworkach. Oba bywają używane w jednym systemie.

Czy działa z modelami innymi niż Gemini?

Tak, warstwa modelu obsługuje różnych dostawców, choć integracja z modelami tego producenta jest najgłębsza. Przy porównywaniu warto przepuścić własne przypadki przez kilka modeli, bo różnice zależą od zadania bardziej niż od zestawień.

Kiedy wybrać coś innego?

Gdy pracujesz w Pythonie i zależy Ci na typowanym wyjściu albo na testach bez wywoływania modelu, bo do tego są biblioteki lepiej dopasowane. Gdy potrzebujesz pełnej kontroli nad przepływem z zatrzymaniami na decyzję człowieka, właściwym kierunkiem jest rozwiązanie oparte o graf stanów.

Dokumentacja stoi na stronie projektu, a opis obsługi protokołu wymiany w osobnym rozdziale.