Dodawanie agentów AI do mikrousług Spring Boot przy użyciu Spring AI

Wyobraź sobie trzy mikrosługi Spring Boot, które już obsługują ruch produkcyjny: sześć tygodni pracy nad dodaniem im funkcji agentów, z których dwa zostały wdrożone pomyślnie, a trzeci okazał się długą i kosztowną lekcją. Ten scenariusz, odzwierciedlający doświadczenia wielu zespołów pracujących z Javą, stanowi kontekst dla dalszej treści. Jest to praktyczny przegląd łączenia pipeline’ów agentowych z istniejącymi usługami, które mają ograniczenia czasowe, zależne zespoły oraz prawdziwych użytkowników, napisany dla inżynierów backendu używających Javy, którzy znają Spring Boot i chcą korzystać z funkcji AI bez rezygnacji z utrzymywanej architektury.

Następne strony omawiają, czym tak naprawdę jest agent AI w środowisku Spring Boot (i czym nie jest), dlaczego zespoły go przyjmują, jak implementować wywoływanie narzędzi za pomocą Spring AI, trzy rodzaje awarii, które zwykle pojawiają się dopiero po wdrożeniu, oraz jak traktować zużycie tokenów jako ważną miarę operacyjną.

Czym jest agent i czym nie jest

Zanim napisany zostanie jakikolwiek kod, model mentalny musi być poprawny. Większość inżynierów, którzy mają trudności z integracją agentów w Javie, nie napotyka przeszkód spowodowanych frameworkiem – to oni stosują do tego niewłaściwy model.

Agent to nie jest sprytny wywołanie API. To pętla rozumowania: model językowy otrzymuje zadanie, decyduje, jakie narzędzia wywołać, otrzymuje wyniki, analizuje wszystko, co teraz wie, i albo zwraca ostateczną odpowiedź, albo przechodzi do kolejnego kroku.

Pętlę tę składają cztery elementy:

• Model to silnik rozumowania, czy to GPT-4o, Claude, Gemini, czy alternatywa o otwartych wagach dostępna przez Ollamę.
• Narzędzia to funkcje, API lub wywołania usług, które model może używać.
• Pętla to wielokrotny cykl, który oddziela agenta od pojedynczego wywołania LLM.
• Kontekst to coraz większa liczba zapisów z historii rozmów, wyników narzędzi oraz instrukcji, które stanowią podstawę każdego kroku rozumowania.

W mikrosłudze Spring Boot oznacza to, że nie dodaje się otoczki w stylu RestTemplate wokół punktu końcowego AI. Zamiast tego wdraża się wieloetapowy, stanowy i nieokreślony proces pracy w usłudze zaprojektowanej do ograniczonej, synchronicznej i przewidywalnej eksploatacji. To niezgodność jest przyczyną problemów w większości integracji AI w Javie. Krótka metoda na zapamiętanie: to nie narzędzie jest agentem, lecz pętla – dopóki tego nie zrozumiesz, będziesz tworzyć punkty końcowe, a nie agenty.

Zalety wdrażania agentów w usługach Spring Boot

Instrukcje często pomijają tę część. Pokazują, jak zintegrować agenta, ale niewiele mówią o tym, dlaczego organizacja powinna to zrobić, jakie problemy to rozwiązuje lub jakie są koszty wdrożenia go zbyt wcześnie.

Poza sztywnymi regułami

Klasyczne mikrosługi automatyzują znane procedury, w których dane wejściowe przechodzą przez zbiór reguł B, aby uzyskać wynik C, co doskonale pasuje do deterministycznych procesów. Agenci rozszerzają tę koncepcję na niejednoznaczne, wieloetapowe zadania, w których właściwa kolejna akcja zależy od wyników pośrednich. Oto kilka przykładów pasujących do istniejących architektur Spring Boot:

• Przetwarzanie zamówień. Jeden agent sprawdza stan zapasów, ocenia zasady cenowe, stosuje zniżki specyficzne dla klienta i w ramach jednej prośby generuje rekomendację dotyczącą realizacji zamówienia, dzięki czemu interfejs użytkownika nie musi koordynować czterech sekwencyjnych wywołań.
• Rozumienie dokumentów. Agent czyta załadowany plik PDF, wyodrębnia ustrukturyzowane pola, weryfikuje je pod kątem zasad biznesowych i albo potwierdza wyniki, albo przekazuje sprawę do ludzkiego recenzenta, bez użycia sztywno zdefiniowanych reguł wyodrębniania danych.
• Obsługa klienta. W ramach istniejącej usługi wsparcia agent pobiera informacje o stanie konta, historii zamówień oraz dokumentach polityki i tworzy odpowiedź dokładną pod kątem kontekstu, co skraca czas obsługi bez wykluczania człowieka z procesu.
• Przegląd kodu i pomoc w CI. W pipeline’u inżynierii platformy agent analizuje nieudane testy, korzysta z dokumentacji wewnętrznej i proponuje celowe poprawki.

W każdym z tych przypadków wartością nie jest samo „AI”. Chodzi o zastąpienie kruchej, ręcznie pisanej logiki orkiestracji warstwą rozumowania, która dostosowuje się do tego, co znajduje, zamiast zawieść, gdy dane wejściowe odbiegają od planowanego ścieżki.

Dlaczego Spring Boot nadaje się do tego zadania

Python dominuje w tutorialach dotyczących sztucznej inteligencji, podczas gdy Java dominuje w systemach produkcyjnych przedsiębiorstw, a luka pomiędzy nimi stanowi prawdziwą szansę. Spring Boot oferuje przewagi strukturalne, których lekkie frameworki Python nie zapewniają od razu:

• Injekcja zależności umożliwia zarządzanie elementami narzędziowymi, ich testowanie oraz łączenie bez dodatkowej konfiguracji.
• Actuator i Micrometer przekształcają zużycie tokenów, opóźnienia pomiędzy etapami działania agenta oraz wskaźniki błędów narzędzi w standardowe metryki operacyjne.
• Proste struktury asynchroniczne, takie jak @Async i CompletableFuture, dobrze radzą sobie z pętlami agentów, których czas wykonywania się zmienia.
• Resilience4j otacza wywołania narzędzi mechanizmami awaryjnego wyłączania i ponawiania prób, zapobiegając kaskadowym awariom.
• Spring Security umożliwia integrację mechanizmów autoryzacji i uwierzytelniania dla punktów końcowych narzędzi dostępnych dla agentów z istniejącymi systemami kontroli dostępu.
• Rozwinięte narzędzia do operacji oznaczają, że istniejące rozwiązania takie jak Prometheus, Grafana czy Datadog mogą być rozszerzone o metryki agentów bez konieczności tworzenia nowej infrastruktury.

Ponadto Spring AI dostarcza klientów do modeli językowych, integrację z magazynami wektorowymi oraz możliwość wywoływania funkcji za pomocą anotacji @Tool w ramach tego samego ekosystemu, dzięki czemu tworzenie agenta klasy produkcyjnej nie wymaga rezygnacji z podejścia opartego na Springu.

Kiedy agent jest opłacalny

Agenty zyskują swoje miejsce wtedy, gdy:

• Proces wymaga decyzji opartych na informacjach odkrytych podczas wykonywania, a nie na informacjach znanych w momencie otrzymania żądania.
• Obecna implementacja sprawia, że interfejs użytkownika lub usługa orkiestratora musi koordynować kilka wywołań backendu, a agent mógłby przejąć tę koordynację na serwerze.
• Dane wejściowe to język naturalny o zmiennym strukturze, przy czym klasyfikacja, wydobywanie informacji, streszczanie lub kierowanie zależy od treści, a nie od schematu.
• Obecny system zawodzi w sposób „błędny, ale nie powodujący awarii”, a agent mógłby być zaprojektowany tak, aby ujawniać niepewność, zamiast cicho zwracać najbardziej prawdopodobną, błędną odpowiedź.

Są mało przydatne, gdy proces pracy jest w pełni deterministyczny, dane wejściowe są ustrukturyzowane, a logika oparta na regułach jest łatwa w utrzymaniu. Agenci dodają złożoność, a ich używanie jest opłacalne tylko wtedy, gdy alternatywa jest gorsza.

Argument biznesowy w prostych słowach

Dla kierowników działów inżynieryjnych oraz zaangażowanych w produkt osoby, argument opiera się na trzech filarach:

1. Szybsze wdrożenie nowych funkcji. Funkcje, które wcześniej wymagały tygodni pracy nad kodem do koordynacji w tle, mogą być często zaprojektowane w ciągu kilku dni, gdy agent zajmuje się wieloetapową koordynacją. Zespoły często odnotowują takie przyspieszenie po pierwszej udanej integracji, chociaż liczby mogą się różnić.
2. Mniej problematyczna konserwacja reguł. Każda reguła zapisana w sposób sztywny w usłudze stanowi dług, który rośnie wraz ze zmianami w logice biznesowej, a instrukcje napisane w języku naturalnym są zazwyczaj łatwiejsze do aktualizacji niż kod wyrażający tę samą logikę w sposób imperatywny.
3. Baza dla złożonych systemów AI. Jeden dobrze zintegrowany agent stanowi fundament dla prac wieloagentowych, pipeline’ów do generowania treści wzbogaconych o dane z bazy oraz funkcji produktowych opartych na technologii AI.

Dlaczego taka pilność i zmiana modelu realizacji?

Przez rok 2023 i aż do 2024 roku AI w Javie oznaczało niewiele więcej niż wysłanie zapytania do punktu końcowego LLM i otrzymanie powrotem dowolnego tekstu, który pojawił się – zwykły HTTP za pośrednictwem WebClient, czas timeout i brak dalszych rozważań.

Ten model już nie obowiązuje. Zestaw funkcji Spring AI (wywoływanie narzędzi i funkcji, integracja z magazynem wektorowym oraz API ChatClient stworzone z myślą o pracach agentowych) wskazuje, że sam model wykonywania się zmienił.

• W starym modelu jedna prośba prowadziła do jednego wywołania LLM i jednej odpowiedzi.
• W nowym modelu prośba rozgałęzia się na N wywołań narzędzi i M kroków rozumowania, zanim pojawi się jedna odpowiedź.

Wielu inżynierów Spring Boot nadal stosuje stary model i traktuje ChatClient jak RestTemplate. Ten błąd kategorialny powoduje problemy w produkcji kilka tygodni po uruchomieniu, a ich wystąpienie rzadko jest oczywiste.

Pętla to agent

Inżynierowie, którzy po raz pierwszy zajmują się integracją agentów, zwykle wyobrażają sobie usługę pełniącą rolę kontrolera: jeden bean typu @Service, jeden injectowany obiekt ChatClient – i to już wszystko. To jest punkt końcowy do autodopasowywania, a nie agent. Prawdziwy agent uruchamia pętlę składającą się z odbierania zadania, wyboru narzędzia, jego wykonywania, odbierania wyniku, przetwarzania nowego stanu, a następnie decydowania, czy kontynuować, czy odpowiedzieć. Modelem jest silnik rozumowania wewnątrz tej pętli; samą pętlą jest agent.

Dlaczego standardowy projekt błędnie ocenia koszty

Powszechnym założeniem jest, że kosztowną i skomplikowaną częścią jest wywołanie LLM, a resztę zajmuje się wrapper typu Spring @Service. W rzeczywistości „reszta” jest teraz rozproszona: szybkość działania narzędzi, stan kontekstu przenoszony z jednej rundy na drugą, sposób przekazywania błędów w łańcuchach wieloetapowych oraz konieczność ponawiania prób w przypadku nieukończonej pracy.

Rozważmy hipotetyczną usługę klasyfikacji zamówień. Zaczyna się od jednego punktu końcowego POST /orders/classify, który wykonywa jeden wywołanie LLM. Następnie jest przekształcana w agenta, który klasyfikuje zamówienie, wywołuje narzędzie do zarządzania zapasami, a w zależności od stanu zapasów – narzędzie do ustalania cen, po czym zwraca rekomendację dotyczącą realizacji zamówienia. Każde wywołanie takiego narzędzia to rzeczywiste wywołanie usługi z rzeczywistym opóźnieniem.

Załóżmy, że agent kończy przetwarzanie 80% zapytań w mniej niż dwie sekundy, natomiast w przypadku pozostałych 20% powolna usługa zarządzania zapasami wydłuża czas odpowiedzi do 8–14 sekund. To nie jest problem związany z sztuczną inteligencją – to problem systemów rozproszonych, który ujawnił się dzięki pętli agenta.

Kompromis, który jest pomijany

Pętla agenta nie jest bezstanowa. Każdy wynik narzędzia jest dodawany do rozmowy i wysyłany ponownie do modelu w następnej turze. Przy wysokiej przepustowości koszt pamięci każdego żądania rośnie wraz z liczbą tur, które agent wykonuje, a sama liczba żądań staje się mniej istotna. Usługa obsługująca 1000 żądań na minutę przy średnich 4 turach faktycznie przetwarza 4000 wywołań LLM, przy tym rozmiary kontekstu się kumulują.

Zanim napiszesz jakikolwiek kod agenta, wymień wszystkie wywołania narzędzi, oszacuj opóźnienie p95 dla każdego z nich i oblicz maksymalny rozmiar kontekstu przy największej liczbie tur. Przed zaprojektowaniem pętli określ budżet pamięci przeznaczony na kontekst. Większość awarii agentów w backendach Java okazuje się być awariami z powodu przekroczenia czasu oczekiwania, udawanymi jako błędy modelu.

Spring AI dostarcza narzędzia, a nie plan

Spring AI to poważna warstwa abstrakcji przeznaczona do użycia w produkcji. Oferuje ChatClient, ToolCallback, VectorStore oraz API do uruchamiania agentów, który wykorzystuje iniekcję zależności, zmianę modeli za pomocą pliku application.properties oraz obsługę reaktywną poprzez Flux. Jako punkt wyjścia do integracji modeli językowych w Spring Boot jest idealnym rozwiązaniem.

To, czego nie oferuje, to strategii dla pipeline’ów opartych na agentach, a ta luka oddziela prototypy od usług produkcyjnych. Framework zarządza pojedynczymi wywołaniami narzędzi i interakcjami z modelami. Nie obsługuje:

• Umów na granicy usług pomiędzy agentem a usługami poniżej niego.
• Persistentnego przechowywania stanu agenta pomiędzy żądaniami, czyli pamięci sesji.
• Logiki circuit-breaker dla awarii obejmujących kilka kroków.

Obserwowalność na poziomie procesu pracy, np. zrozumienie, dlaczego agent wybrał określoną sekwencję narzędzi.

Napisz macierz awarii narzędzi

Przed uruchomieniem w produkcji zdefiniuj dla każdej metody @Tool, co dzieje się w trzech sytuacjach:

• Narzędzie zwraca oczekiwany wynik. Agent przechodzi do następnego kroku rozumowania.
• Narzędzie zwraca błąd. Agent otrzymuje sygnał błędu i decyduje, czy spróbować ponownie, użyć rozwiązania awaryjnego, czy poinformować użytkownika.
• Narzędzie wygaśnia. Aktywowany zostaje mechanizm ochronny, zwracana jest wartość awaryjna, a agentowi informuje się, że dane są niedostępne.

Jeśli drugi i trzeci przypadek są puste dla jakiegokolwiek narzędzia, integracja nie została ukończona. Szlak prawidłowego działania to nie sam serwis. Spring AI zajmuje się sposobem realizacji; powody, momenty oraz scenariusze awarii pozostają Twoją odpowiedzialnością.

Okna kontekstowe zachowują się jak niewpisane umowy

W zwykłym serwisie Spring Boot naruszenie umowy powoduje wywołanie wyjątku. W agencie przekroczenie limitu okna kontekstowego nie powoduje wyjątku, żadnego alertu ani zapisu błędu. Model po cichu usuwa najstarszy treść z rozmowy, a to często jest komenda systemowa zawierająca zasady biznesowe. REST API odpowiada kodem 400, gdy naruszy się jego umowę; okno kontekstowe po prostu zaczyna zapominać, co sprawia, że błąd jest znacznie trudniejszy do znalezienia.

Przykładowy incydent

Załóżmy usługę przetwarzania dokumentów, której instrukcja systemowa składa się z około 800 tokenów. Podczas testów odpowiedzi narzędzi wynoszą średnio około 1 600 tokenów na zapytanie, co jest w pełni w granicach możliwości modelu. W środowisku produkcyjnym jeden konkretny przepływ pracy uruchamia wszystkie trzy wywołania narzędzi z dużymi obciążeniami, w tym odpowiedź dotyczącą zagnieżdżonej historii zamówień, sama w sobie liczącą około 1 800 tokenów. Całkowita ilość kontekstu przekracza 6 000 tokenów, w wyniku czego instrukcja systemowa jest cicho skracana, a agent zwraca wiarygodną odpowiedź, w której pomija kluczową zasadę biznesową.

Nic się nie wyświetla i nic nie sygnalizuje problemu. Błąd ujawnia się dopiero podczas cotygodniowej audytu trzy dni później.

Rozwiązanie: pomiary liczby tokenów od pierwszego dnia

Spójrzmy na zużycie kontekstu instrumentu przed wdrożeniem. W przypadku Micrometer oznacza to odczytanie liczby tokenów wejściowych i wyjściowych z obiektu usage w metadanych odpowiedzi oraz publikowanie ich jako wskaźników, na przykład pod nazwami takimi jak agent.context.input_tokens i agent.context.output_tokens. Dokładne nazwy dostępników różnią się w zależności od wersji Spring AI, więc sprawdź API dotyczące użytkowania w wersji, którą używasz. Następnie wyślij alert, gdy zużycie osiągnie około 80% limitu kontekstu modelu. To zazwyczaj odpowiada dwóm elementom typu bean oraz jednej właściwości konfiguracyjnej, i należy to umieścić na miejscu przed uruchomieniem w produkcji. Wdrożenie agenta bez metryk tokenów jest jak uruchamianie bazy danych bez monitorowania czasu wykonywania zapytań – kończy się to zwykle o 2 w nocy.

Budowanie krok po kroku

Wymagania wstępne: Spring Boot 3.2 lub nowsza wersja, Spring AI 1.0 lub nowsza wersja wraz ze starterem dla dostawcy modeli (w tym przykładzie starter OpenAI), solidna znajomość @Async i CompletableFuture, usługa wewnętrzna do udostępnienia jako narzędzie oraz Micrometer włączony do stacku do obserwowalności. Nazwy artefaktów starterów zmieniają się przy każdej nowej wersji Spring AI, dlatego należy sprawdzić aktualną nazwę w dokumentacji referencyjnej.

Krok 1: dodanie zależności

W pliku pom.xml dodaj starter Spring AI odpowiedni dla Twojego dostawcy, a także artefakt resilience4j-spring-boot3, jeśli chcesz wsparcia dla mechanizmu circuit-breaker przy wywoływaniu narzędzi. Dane uwierzytelniające modelu umieść w pliku application.properties. Klucz API należy odczytać z zmiennej środowiskowej, np. OPENAI_API_KEY, za pomocą właściwości spring.ai.openai.api-key, wybrać model do czatowania (w przykładzie użyto gpt-4o) oraz utrzymać niską temperaturę, około 0,2, aby korzystanie z narzędzi pozostawało przewidywalne.

Krok 2: zdefiniuj narzędzia przed konfiguracją agenta

Kolejność ma znaczenie, ponieważ projekt narzędzi wpływa na zachowanie agenta. Prompt systemowy powinien odnosić się do konkretnych możliwości narzędzi, a jego napisanie przed stworzeniem narzędzi skutkuje niejasnymi instrukcjami, które mylą model.

W przykładzie komponent OrderTools otrzymuje przez swój konstruktor InventoryService oraz PricingService i udostępnia dwa metody opatrzone adnotacjami. Metoda checkInventory(String sku) zwraca dostępną ilość towaru, a -1 w przypadku, gdy SKU jest nieznane. Metoda getPrice(String sku, String customerTier) zwraca cenę w centach USD. Każda z tych metod zawiera adnotację @Tool z opisem.

Częstym błędem jest używanie zbyt ogólnych opisów. Model czyta je, aby zdecydować, kiedy wywołać dany narzędzie, więc precyzyjne i kompletnie sformułowane opisy zapewniają mniej niepotrzebnych wywołań oraz dokładniejsze odpowiedzi. Należy jasno określić jednostki miary, wartości zwracane oraz sytuację, gdy dane nie zostały znalezione, tak jak to pokazano we wcześniejszych przykładach.

Krok 3: podaj ChatClientowi krótkie polecenie systemowe

Klasa AgentConfig definiuje obiekt ChatClient na podstawie zaimprowizowanego konstruktora oraz OrderTools. Standardowe polecenie systemowe jest krótkie i rozkazujące: działać jako asystent zajmujący się przetwarzaniem zamówień, zawsze sprawdzać stan zapasów przed potwierdzeniem dostępności, zawsze uzyskiwać informacje o cenach przed podaniem oferty, zwracać obiekt JSON zawierający wartość logiczną available, liczbę całkowitą price w centach USD oraz łańcuch tekstowy recommendation, a także nigdy nie wymyślać poziomów zapasów ani cen. Narzędzia są rejestrowane w defaultTools.

Tutaj kluczowa jest dyscyplina w używaniu tokenów. Każdy token w poleceniu systemowym zmniejsza ilość miejsca przeznaczonego na wyniki narzędzi, dlatego staraj się nie przekraczać 300 tokenów i edytuj bez litości.

Krok 4: uruchom agenta asynchronicznie i rejestruj tokeny

OrderAgentService przechowuje ChatClient oraz MeterRegistry. Jego metoda processOrder zwraca CompletableFuture<String> i uruchamia wywołanie agenta wewnątrz supplyAsync: wysyła dane wprowadzone przez użytkownika, wywołuje model, odbiera odpowiedź z czatu, odczytuje liczby tokenów wejściowych i wyjściowych oraz rejestruje je jako wskaźniki, a następnie zwraca tekst rezultatu.

Dlaczego asynchronicznie? Czas działania agenta jest proporcjonalny do liczby wywołań narzędzi, a nie do pozornej złożoności żądania. Wątek kontrolera synchronicznego zablokowany na 8 do 14 sekund w intensywnie używanym serwisie wyczerpie zasoby puli wątków. Od samego początku traktuj wykonywanie agenta jako zadanie w tle.

Krok 5: zainstaluj circuit breaker dla każdego narzędzia

Opisz każdą metodę narzędzia za pomocą @CircuitBreaker z biblioteki Resilience4j, podając nazwę wyłącznika (na przykład inventoryTool) oraz metodę awaryjną. Metoda awaryjna dla narzędzia do zarządzania zapasami loguje ostrzeżenie wraz z SKU i zwraca -1, co informuje agenta o niedostępności danych dotyczących zapasów. Progi są określone w pliku application.properties: okno czasowe 10 wywołań, próg wskaźnika niepowodzeń na poziomie 50% oraz 10 sekund oczekiwania w stanie otwartym.

Jeśli wyłączniki wydają się nigdy nie być aktywowane, pamiętaj, że Spring AOP działa tylko wtedy, gdy wywołania przechodzą przez proxy Spring. Właściwie wstrzyknij komponenty narzędzi i nie twórz ich instancji bezpośrednio.

Krok 6: udostępnij punkt końcowy z wzorcem odpowiedzi asynchronicznej

OrderAgentController mapowany na /agent przyjmuje żądanie POST do /orders, generuje identyfikator żądania, uruchamia agenta i przechowuje informację o przyszłym wyniku w mapie współbieżnej, a następnie odpowiada kodem 202 Accepted wraz z tym identyfikatorem. Żądanie GET do /orders/{requestId}/result wyszukuje tę informację. Zwraca kod 404, gdy identyfikator jest nieznany, kod 202 z komunikatem „Processing”, dopóki praca nad wynikiem nie jest zakończona, kod 200 z wynikiem po zakończeniu oraz kod 500 z komunikatem o błędzie, jeśli wykonanie się nie powiodło. W przypadku zastosowań wykraczających poza demonstrację należy zastąpić mapę pamięciową bazą danych, która przetrwa restarty i usuwa stare wpisy.

Rozgałęzienie decyzji odnosi się do samych narzędzi. W przypadku wewnętrznych wywołań usług o niskiej opóźnieniu należy utrzymać narzędzia synchroniczne, a obsługę asynchroniczną przenieść na warstwę usług. W przypadku zewnętrznych API o nieprzewidywalnym opóźnieniu należy uczynić narzędzie asynchronicznym, wykorzystując dedykowany pool wątków oraz sztywne ograniczenie czasowe, aby powolna zależność nie wpływała negatywnie na budżet czasowy agenta.

Narzędzia, które warto znać

• Spring AI to podstawowe frameworki agentów dla Spring Boot.
• LangChain4j to alternatywa typu Java, często uważana za lepszą pod względem koordynacji wielu agentów.
• Resilience4j zapewnia mechanizmy ochronne i powtórzenia prób dla wywołań narzędzi.
• Micrometer publikuje dane dotyczące użycia tokenów oraz metryki agenta.
• Ollama uruchamia modele o otwartym kodzie lokalnie w celach rozwoju i testowania.

Trzy błędy, które marnują czas i wiarygodność

Pułapka początkujących: testowanie wyłącznie za pomocą danych typu „happy path”. Turytoria wykorzystują czyste, sprzyjające testom dane, ale prawdziwi użytkownicy przesyłają dane, które powodują długie czasowe trwanie operacji, pozostają niejednoznaczne lub wywołują nietypowe zachowanie narzędzia, widoczne tylko w danych produkcyjnych. Stwórz narzędzie do odtwarzania zanonimizowanych przykładów zapytań z produkcji, a nie syntetycznych, w celu testowania ich z agentem w środowisku staging przed każdym wydaniem, przy czym koniecznie testuj również z danymi atakującymi, które przekraczają oczekiwany budżet kontekstowy.

Krytyczny punkt ślepy ekspertów: nadmierna konstrukcja przed wdrożeniem. Inżynierowie obeznani z literaturą na temat wielu agentów czasami wprowadzają systemy z orkiestratorami, podagentami, warstwami pamięci oraz pipeline’ami typu RAG, zanim choć jeden agent zdąży dotrzeć do rzeczywistego użytkownika. To odpowiednik zastosowania sztucznej inteligencji w formie compound-AI przy budowie sieci usług przed weryfikacją monolitu. Wdroż jednego agenta z jednym zestawem narzędzi w jednej usłudze, zmierz jej efektywność i dodawaj złożoność tylko tam, gdzie tego wymagają dane. Zespoły, które najszybciej docierają do fazy produkcji, unikają projektowania platformy, zanim mają gotowy produkt.

Systemowy błąd: nikt nie jest odpowiedzialny za zachowanie agenta. Zwykły błąd pozostawia wpis w dzienniku, wskaźnik i alert. Błędna, ale wiarygodna odpowiedź agenta nie pozostawia żadnego z nich: żadnego wyjątku, żadnego alertu, tylko odpowiedź, która przechodzi walidację schematu, ale zawodzi z punktu widzenia logiki biznesowej. Trzeba określić osobę odpowiedzialną za to, co mówi agent, a nie tylko to, czy odpowiedział, oraz co tydzień sprawdzać wybraną próbę odpowiedzi, zamiast patrzeć tylko na wskaźniki błędów. To decyzja organizacyjna, a nie techniczna.

Co pomagale wprowadzające pomijają

Zdaniem większości najtrudniejszą częścią integracji agenta Spring Boot nie jest sztuczna inteligencja. Zachowanie modelu, projektowanie zapytań oraz interfejs wywoływania narzędzi można opanować w około tygodnia. Trudnością jest spór między synchroniczną naturą Javy a asynchronicznym, wieloetapowym sposobem działania agentów.

Model żądanie-odpowiedź Spring Boot zakłada ograniczony czas wykonywania. Agent taki nie ma – wykonuje tyle wywołań narzędzi, ile wymaga zadanie, i przeprowadza tyle rund rozumowania, ile jest konieczne, nieświadomy 30-sekundowego limitu czasu oczekiwania bramy. Przepływy pracy oparte na agentach nie pasują do modelu żądanie-odpowiedź; pasują do modelu opartego na zdarzeniach, a im szybciej przestaniemy temu się sprzeciwiać, tym szybciej zostanie zrealizowana integracja.

Zespoły, które mają największe trudności, starają się utrzymać synchroniczną obsługę aż do momentu otrzymania odpowiedzi od agenta. Ci, którzy realizują projekty najszybciej, uruchamiają agenta jako zadanie w tle, startują je na żądanie, dostarczają wynik poprzez polling lub WebSocket i projektują umowę usługową w oparciu o to rozwiązanie. Ta zmiana perspektywy brakuje w materiałach wprowadzających do Spring AI, choć być może wcale nie powinna tam być.

Model myślowy, który należy zachować

Wszystko powyższe sprowadza się do jednego zdania: agent AI to system rozproszony z nieokreślonym silnikiem wykonywania w swoim wnętrzu.

Zasady systemów rozproszonych, które inżynier Java już zna (izolacja błędów, obserwowanie zachowania, ograniczanie czasu wykonywania, określanie warunków awarii), nadal mają zastosowanie, tym razem z jeszcze większą siłą, ponieważ awarie w takich systemach są mniej widoczne i dłużej się pojawiają. Pocieszające jest to, że Spring Boot doskonale nadaje się do tego typu zadań. Iniekcja zależności, możliwości obserwacji dzięki Actuatorowi, operatory asynchroniczne oraz rozwinięty ekosystem operacyjny to prawdziwe atuty, a Spring AI to solidne narzędzie. Różnica leży w modelu myślowym, a nie w narzędziach.

Praktyczne zasady:

• Traktuj agenta jako pętlę rozumowania i projektuj umowę usługową wokół tej pętli, a nie wokół wywołania modelu.
• Wykorzystuj agenty, gdy proces pracy zależy od informacji uzyskiwanych w trakcie jej wykonywania, lub gdy istniejąca architektura orkiestracji jest krucha i trudna w utrzymaniu. Unikaj ich, gdy proces pracy jest deterministyczny i wersja oparta na regułach funkcjonuje poprawnie.
• Spring AI dostarcza ramy robocze; ty określasz strategię radzenia sobie z awariami narzędzi, zarządzania zasobami kontekstowymi oraz zapewniania widoczności.
• Traktuj okna kontekstowe jak umowy i monitoruj zużycie tokenów przed uruchomieniem w produkcji, a nie po pierwszym incydencie.
• Od samego początku uruchamiaj wykonywanie agentów asynchronicznie, ponieważ projekt oparty na zdarzeniach lepiej funkcjonuje tam, gdzie model request-response stanowi przeszkodę.

Częste pytania

Która ramka robocza jest najlepsza do agentów w Spring Boot? Spring AI to najbardziej odpowiednia opcja dla aplikacji Spring Boot. LangChain4j to silna alternatywa oferująca szersze wsparcie dla koordynacji wielu agentów, przy czym obie są aktywnie utrzymywane.

Czy istniejące mikrosługi muszą zostać przepisane? Nie. Tutaj stosuje się podejście polegające na rozszerzeniu usługi za pomocą anotacji @Tool z Spring AI, beana ChatClient oraz wykonywania z użyciem @Async, bez ingerencji w istniejącą logikę usługi.

Jak należy radzić sobie z awariami agentów w środowisku produkcyjnym? Należy otoczyć każdą metodę @Tool mechanizmem circuit breaker z Resilience4j, publikować dane o zużyciu tokenów za pomocą Micrometer, zdefiniować matrycę awarii narzędzi przed uruchomieniem w produkcji oraz wyznaczyć osobę odpowiedzialną za sprawdzanie jakości odpowiedzi, a nie tylko wskaźników błędów.

W czym różnica między agentem a zwykłym wywołaniem LLM? Zwykłe wywołanie polega na jednej prośbie i jednej odpowiedzi. Agent to pętla, w której model może wywoływać narzędzia, czytać wyniki, analizować je i decydować o kontynuacji lub udzieleniu odpowiedzi w ciągu kilku rund rozmowy.

Czy Spring Boot jest gotowy na obciążenia agentów produkcyjnych? Tak, przy odpowiednich wyborach architektonicznych. Asynchroniczna eksploatacja, mechanizmy ochronne, metryki tokenowe oraz wyraźne zarządzanie oknem kontekstowym można zrealizować za pomocą istniejących, stabilnych bibliotek.

Gdzie mieści się RAG? RAG to jeden z wzorów narzędziowych wśród innych: agent pobiera istotne dokumenty z magazynu wektorowego, aby wzbogacić swój kontekst przed podejmowaniem decyzji. Jest przydatny, gdy agent potrzebuje dużej bazy wiedzy, nie jest wymagany przy każdej integracji i dodaje złożoność, którą najlepiej wprowadzać dopiero wtedy, gdy ograniczenia okna kontekstowego powodują rzeczywiste problemy.