Tworzenie asystenta API typu agencyjnego: od hackathonu do wersji beta
Asystent LangGraph, który wyjaśnia API, pisze kod oraz uruchamia zapytania tylko do odczytu: dwa tryby, samonaprawiający się pętla OData, pamięć artefaktów, ocena przez LLM-judge, dostęp typu self-serve.
Źródła: From hackathon spark to production reality: building an agentic API assistant
Zespół odpowiedzialny za API do zarządzania flotą w firmie zajmującej się płatnościami przekształcił prototyp stworzony podczas hackathonu w asystenta w wersji beta, który funkcjonuje w ramach ich portalu dla programistów. Ideą było uniknięcie konieczności czytania przez integratorów stron referencyjnych i ich przekładania na kod, pozwalając zamiast tego agentowi konwersacyjnemu samodzielnie załatwić integrację. Przedstawiamy, w jaki sposób takiego asystenta tworzy się od podstaw, co celowo odrzuca, oraz jak mierzy się jego jakość.
Asystent wyjaśnia informacje na temat punktów końcowych, pisze kod w dowolnym języku używanym przez programistę, planuje wieloetapowe procesy pracy oraz przeprowadza zapytania do danych tylko do odczytu w żywych systemach. Zastępuje on statyczne dokumentacje specyficzne dla danego języka oraz indeksy wyszukiwania, które wskazują jedynie na konkretne strony.
Dlaczego statyczne dokumentacje przestały wystarczać
Oprogramowanie do zarządzania flotą i mobilnością obsługuje duży przepływ danych: aktywność kierowców, stacje paliw, transakcje kartowe oraz dane telemetryczne pojazdów. Każdy, kto chce je wdrożyć, musi opanować zaawansowane punkty końcowe REST, składnię filtrowania, słownictwo specjalistyczne oraz długie łańcuchy powiązanych wywołań. Wszystkie te trudności utrudniały partnerom rozwój wraz z platformą.
Rozwijający polegali na gotowych narzędziach dokumentacyjnych do czytania definicji punktów końcowych oraz na narzędziach testowych do ręcznego wykonywania wywołań. Zespół przechowywał również „przepisy” – ustalone sekwencje wywołań pokazujące, jak wykonać złożone zadanie, takie jak utworzenie konta, włączenie kierowcy do systemu czy dołączenie karty. To działało, ale pojawiały się trzy słabe strony:
- Związane z konkretnym językiem. Prezentowanie każdego procesu w formacie cURL, Python, .NET, Java i Go wymagało ciągłego wysiłku ręcznego ze strony autorów i inżynierów.
- Kruche na krawędziach. Niemożliwe jest udokumentowanie każdej możliwej kombinacji każdego procesu pracy, więc instrukcje często nie uwzględniają dokładnego przypadku konkretnego użytkownika.
- Stałe koszty utrzymania. Gdy tylko zmienił się schemat API, strony stawały się przestarzałe, co wydłużało proces wdrożenia i zapełniał kolejki wsparcia.
Od pomysłu z hackathonu do dwóch trybów
Koncepcja ta powstała podczas wewnętrznego hackathonu w grudniu 2025 roku z jednym pytaniem: dlaczego prosić programistów o przekształcanie dokumentacji w kod, skoro model może bezpośrednio zrozumieć ich intencje? Wynik działający w ten sposób przypomina dostępnego w każdej chwili konsultanta ds. integracji, a nie pole wyszukiwania.
Dla bezpieczeństwa operacyjnego projekt dzieli asystenta na dwa oddzielne ścieżki przetwarzania.
Tryb doradcy obsługuje wyjaśnienia dotyczące pojedynczych kroków, dogłębną dokumentację oraz generowanie kodu dla dowolnego frameworku, w tym żądania typu POST, PUT i DELETE. Tworzy kod, ale nigdy go nie uruchamia, dzięki czemu osoba odpowiedzialna może nadal monitorować zmiany w danych.
Tryb planowania i wykonywania przetwarza złożone, wieloetapowe żądania odczytu i realizuje je na żywej platformie za pomocą narzędzi Model Context Protocol (MCP) dostępnych wyłącznie do odczytu.
To, co faktycznie widzą partnerzy
Jeśli poprosisz tryb doradcy o fragment kodu w Pythonie, który stworzy sterownik, otrzymasz wywołanie funkcji requests z odpowiednim punktem końcowym, nagłówkami, schematem ciała oraz komentarzem dotyczącym wymaganych zakresów uprawnień. Nic nie wpływa na API produkcyjne.
Tryb planowania i wykonywania prosi o pięciu kierowców o imieniu John, a planer redukuje zapytanie z wieloma filtrami do jednego zadania: pobranie kierowców filtrowanych według imienia. Wykonawca wybiera odpowiedni narzędzie MCP, buduje argumenty OData ($filter=first_name eq 'John', $top=5), uruchamia czynność odczytu tylko do odczytu i przechowuje pełną odpowiedź w magazynie artefaktów. Model widzi jedynie zwięzły podsumowanie, takie jak identyfikator artefaktu, liczbę pięć oraz krótkie przedstawienie. Następnie syntezator tworzy uporządkowaną listę pięciu pasujących kierowców.
Architektura: cykl współpracujących agentów
Asystent jest zbudowany na bazie LangGraph jako cykliczna maszyna stanowa. Planer, wykonawcy, walidatorzy oraz syntezator na zmianę planują, działają i sprawdzają każdy krok, przekazując wspólny stan i pamięć aż do zakończenia zadania. Wyróżniają się cztery wybory projektowe.
1. Proxy tylko do odczytu dla bezpieczeństwa
Bezpieczeństwo od samego początku kształtowało projekt. Asystent nie może wykonywać zmiennych wywołań w swoim własnym środowisku działania. Gdy użytkownik prosi o „stworzenie nowej karty dla kierowcy X”, router wysyła żądanie do węzła doradcy, który zwraca ustrukturyzowany fragment, który programista może skopiować, przejrzeć i uruchomić lokalnie. Wszystko, co jest wykonywane naprawdę, ogranicza się do żądań GET. W kodzie serwera MCP istnieją narzędzia umożliwiające zapisywanie, ale są one filtrowane, zanim model w ogóle je zobaczy.
2. Orkiestracja w stylu nadzorcy
Rozumowanie i wykonywanie znajdują się na różnych warstwach, koordynowanych przez jednego nadzorcę, który decyduje, który specjalista ma następnie działać w ramach jednego globalnego pętla:
- Klasa mode router klasyfikuje intencję i wysyła każdą wiadomość do doradcy lub do modułu planowania i wykonywania.
- Planista dzieli złożoną prośbę na listę zadań powiązanych z określonymi parametrami.
- Wykonawca wybiera narzędzie MCP dla każdego zadania, kompletuje argumenty (w tym filtry OData) i iteruje z warstwą narzędzi aż zadanie zostanie ukończone lub wyczerpią się próby ponownych działań.
- Syntetyzator łączy wyniki wszystkich zadań, zarówno rzeczywiste dane, jak i fragmenty kodu awaryjnego, w jedną odpowiedź.
3. Pętla naprawiająca własne dane OData
Modele mają tendencję do tworzenia opcji zapytań lub zaburzania składni, gdy mierzą się z zaimplementowanym językiem filtrów takim jak OData. Zespół wybrał OData, ponieważ umożliwia on elastyczne zapytania częściowe dotyczące złożonych obiektów mobilnościowych bez konieczności ręcznego pisania każdej kombinacji, ale ta elastyczność sprzyja błędom, dlatego dodano wielowarstwową pętlę naprawczą.
Jeśli parser przedstartowy zidentyfikuje problem składniowy lub połączenie w czasie rzeczywistym zwróci błąd API, system rejestruje to zdarzenie, zwiększa licznik prób ponownych dla danej zadania i wprowadza dokładną wiadomość o błędzie z powrotem do kontekstu modelu. Wykonawca odczytuje informację o swoim niepowodzeniu i tworzy poprawioną próbę połączenia. Gdy skończą się próby ponowne, zadanie przechodzi w tryb doradcy, aby użytkownik mimo wszystko otrzymał coś przydatnego.
4. Pamięć podzielona na artefakty
Wprowadzanie dużego ładunku JSON, na przykład tysięcy rekordów zasobów, do rozmowy szybko wyczerpuje budżet tokenów, pogarsza dokładność rozumowania i zwiększa koszty. Dlatego surowe odpowiedzi są przechowywane w izolowanym magazynie artefaktów backendu, a model otrzymuje jedynie krótkie metadane podsumowujące wskazujące na identyfikatory artefaktów. Pytania dodatkowe pozwalają na analizę konkretnych elementów poprzez wyszukiwanie tych identyfikatorów w warstwie aplikacyjnej, co utrzymuje kontekst modelu w małym i skoncentrowanym formacie.
Mierzenie jakości
Zmiana promptu lub modelu bez regresji wymaga zautomatyzowanego punktu odniesienia. Proces w zespole wykorzystuje LLM jako sędziego, który odpowiada na jedno pytanie w związku z każdą zmianą: czy jest ona lepsza, czy gorsza niż wcześniej?
Zbiór danych to ręcznie przygotowana seria przypadków testowych w czterech kategoriach: generowanie kodu, wiedza faktograficzna, rozumowanie i bezpieczeństwo. Każdy przypadek zawiera wyraźną skalę ocen, a nie tylko pytanie, dzięki czemu sędzia ocenia treść odpowiedzi zamiast porównywać ją z sztywno określonym wzorem. Sędzią jest zawsze inny model niż ten, który jest testowany, a ocena odbywa się według trójpunktowej skali: 10 za poprawną odpowiedź, 5 za częściową i 0 za błędną. Każdy test dodaje wiersz do pliku historii oznaczonego komitem z git, modelem testowanym, modelem sędziego, haszem OpenAPI, haszem zbiórki danych oraz wersją promptu, dzięki czemu każda ocena może być prześledzona do konkretnego kodu, specyfikacji i promptu, które za nią stały.
Zgodnie z zespołem, asystent osiąga średnio około 9,4 na 10 punktów w tym kryterium podczas różnych sesji, a ta wartość służy jako punkt odniesienia do obrony przed wprowadzeniem zmian. Dokładność nie jest jednak jedynym kryterium – każda sesja rejestruje również opóźnienia, aby zapewnić szybką odpowiedź, oraz zużycie tokenów, które bezpośrednio odpowiada kosztom modelu. Zmiany, które pogarszają którąkolwiek z tych wartości, są wykrywane przed publikacją.
Ochrona budżetu i mocy obliczeniowej
Asystent dostępny cały czas, który korzysta z API produkcyjnego, wymaga ograniczeń chroniących zarówno budżet modelu, jak i usługi wejściowe. Wprowadzono trzy warstwy ochrony:
- Limity na użytkownika. Konta demonstracyjne pozwalają na 10 wiadomości dziennie, co umożliwia ciekawym partnerom przetestowanie rozwiązania bez nieograniczonego zużycia modelu i skłania je do zakupu konta partnerskiego, gdy chcą realizować prawdziwe zadania.
- Wywołania, które są zdefiniowane i możliwe do przypisania. Ruch pochodzący od partnerów odbywa się przy użyciu ich własnych uprawnień, więc każde wywołanie jest uwzględniane w ich limicie i pojawia się w ich własnym rejestrze audytowym. Asystent nigdy nie udaje konta usługi współdzielonej, co umożliwia przypisywanie korzystania oraz wykrywanie nadużyć.
- Ponawiania prób, które rozumieją niepowodzenia. Gdy żądanie zawodzi, w tym w przypadku tymczasowej odpowiedzi ograniczającej przepustowość, pętla naprawcza przekazuje błąd z powrotem do modelu, zwiększa licznik ponawianych prób i planuje je ponownie do ustalonego maksimum. Po wyczerpaniu możliwości ponawiania prób system przechodzi w tryb doradcy.
Ułatwianie dostępu
Budowa asystenta to była tylko połowa pracy. Równie ważny był bezpieczny i łatwy dostęp.
API platformy tradycyjnie wykorzystywały standardowe dane uwierzytelniające klienta, co oznaczało konieczność ręcznego konfigurowania każdego nowego klienta. Dla asystenta przeznaczonego dla zewnętrznych partnerów rozwiązanie „złożenie wniosku i czekanie na zatwierdzenie przez dział inżynieryjny” nie było do przyjęcia. Prośba o wklejenie tokenów przez programistów do czatu również nie była lepsza, ponieważ utrudniała odróżnienie połączeń utworzonych przez asystenta od tych ręcznie wykonanych oraz komplikowała ustalanie źródeł wykorzystania zasobów i monitorowanie bezpieczeństwa. Zespół potrzebował jednej strategii, która mogłaby służyć dwóm typom użytkowników: partnerom pragnącym bezproblemowego środowiska testowego oraz tym, którzy chcieli korzystać z danych rzeczywistych, bez konieczności ręcznego składania zgłoszeń.
Rozwiązaniem okazał się dwuwarstwowy model samobsługowy, dostępny poza standardowym logowaniem programistów.
- Tryb demo jest domyślnym ustawieniem. Nowi użytkownicy mogą od razu rozmawiać z asystentem przy użyciu syntetycznych danych, bez konieczności konfiguracji, oczekiwania czy składania zgłoszeń.
- Tryb partnera zostaje włączony, gdy deweloper chce integracji w czasie rzeczywistym. Dane uwierzytelniające pochodzą z jednorazowego, samodzielnie przeprowadzanego procesu autoryzacji powiązanego z własnym kontem i uprawnieniami dewelopera. Po połączeniu każda prośba jest przypisywana do tej tożsamości i jest w pełni rozliczalna, dzięki czemu jasno wiadomo, kto wysyła żądanie i którym pathem.
To usunęło główny wąskie gardło w procesie wdrażania. Przejście od „Jestem ciekawy” do „Integruję” nie wymaga już oczekiwania w kolejce inżynierskiej.
Kierunek dalszych działań
Projekt rozpoczął się jako eksperyment wewnętrzny, a obecnie jest wersją beta, która skraca czas integracji dla zespołów deweloperów korporacyjnych. Działa w portalu deweloperskim i już przyjął pierwszą grupę partnerów.
Orkiestrator czyta standardowe schematy OpenAPI, więc architektura jest zaprojektowana tak, aby mogła się rozwijać w poziomie. Obecne wysiłki koncentrują się na walidacji w ramach obszaru mobilności, ale rdzeń routingu jest celowo uniwersalny. Plan rozwoju obejmuje przeniesienie tej samej warstwy konwersacyjnej do innych działów, takich jak platformy płatności i świadczeń korporacyjnych, dodanie bardziej zaawansowanej walidacji typu OData, aby większa liczba błędnych zapytań została zatrzymana przed opuszczeniem asystenta, oraz zbadanie możliwości potwierdzenia przez człowieka operacji zapisu, aby asystent mógł w przyszłości bezpiecznie pomagać w modyfikacji procesów pracy.
Literatura pokrewna
- Od prototypu do produkcji: AI agencyjne z LangChain, LangGraph i Azure — wyszukiwanie hybrydowe, pamięci cache do embeddingów, routowanie w LangGraph, mechanizmy circuit breaker, testy regresji na podstawie zbiorków danych „złotych” oraz śledzenie działania agenta do dokumentów podatkowych, wraz z przedstawionymi wynikami.
- Grafy wiedzy dla AI agencyjnego: cztery wzorce wykraczające poza Vector RAG — wyszukiwanie wektorowe znajduje podobny tekst, a nie powiązane fakty. Cztery wzorce grafowe dla agentów: ustrukturyzowane instrukcje, planowanie, weryfikacja wykonania oraz samokorekcja.