Jak zbudowałem agenta AI dla księgowości — architektura od Telegrama po ERP

Co rozbieramy na części

W studium przypadku LUBART Keg Market opisałem, co robi agent księgowy: księgowa, dyrektor i właściciel pytają na Telegramie, agent odpowiada w sekundy z żywych danych enova365, a o 8:00 sam przysyła poranny raport.

Ten artykuł to druga połowa: jak to jest zbudowane. Komponent po komponencie, z decyzją stojącą za każdym z nich — i z dwoma czy trzema pułapkami, które dopadną cię, jeśli zabierzesz się za własną wersję.

Architektura w skrócie:

• runtime agenta w pojedynczym podzie Kubernetesa,
• narzędzia jako skille w Pythonie, które LLM może wywoływać,
• konektor REST tylko-do-odczytu do enova365 z dwutokenową autoryzacją,
• CronJoby, które z konwersacyjnego agenta robią proaktywny system raportowy,
• warstwa telegramowa ograniczona do białej listy czatów.

Bez bazy wektorowej, bez fine-tuningu, bez osobnego stacku BI. Nudne klocki — celowo.

---

Runtime: jeden pod, jeden config, skille na wolumenie

Agent działa jako pojedynczy kontener w Kubernetesie. Jego zachowanie mieszka w jednym YAML-u — prompt systemowy, workflowy, włączone skille — a same skille to moduły Pythona na trwałym wolumenie.

Skill to zwykły moduł eksportujący schemat narzędzia (nazwa, opis, parametry) i asynchroniczną funkcję execute(args). To cały kontrakt pluginu. LLM widzi schemat, decyduje, kiedy wywołać narzędzie, runtime wykonuje Pythona. Nowa umiejętność agenta to wrzucenie jednego pliku na wolumen. Bez rebuildu, bez redeployu.

Brzmi jak drobne udogodnienie. Nie jest. Agent urósł od „odpowiada na pytania" do „wysyła wykresy i arkusze" bez dotykania rdzenia — nowy plik skilla, jedna linia w configu, koniec.

---

Konektor ERP: tylko odczyt — z konstrukcji, nie z obietnicy

Jedyna droga agenta do enova365 to warstwa REST, a jej token ma wyłącznie prawa odczytu. To nie jest polityka zapisana w prompcie — z promptem można dyskutować. To kształt samego poświadczenia.

Zwróć uwagę na dwa szczegóły autoryzacji. Oba gryzą.

Taniec dwóch tokenów. Długożyciowy JWT aplikacyjny służy wyłącznie do logowania; logowanie zwraca token sesyjny żyjący minuty. Każda udana odpowiedź roluje token sesyjny — świeży przychodzi w nagłówku odpowiedzi i klient musi go przechwycić do następnego wywołania. Przegap to, a integracja działa dokładnie jedno wywołanie naraz, loguje się w kółko i wygląda w logach jak próba brute-force.

Prawa są per kontroler, nie per token. Token aplikacyjny niesie listę nazw usług, których wolno mu dotykać. Jeśli kontrolera nie ma na liście, nie dostaniesz błędu logowania. Logowanie się uda. A potem ten jeden kontroler zwraca 401, podczas gdy cała reszta działa. Za pierwszym razem wygląda to identycznie jak bug w Twoim kodzie. Nie jest. Zanim zaczniesz cokolwiek debugować, sprawdź listę usług tokenu.

Konektor ma też własną białą listę endpointów — agent może wywołać tylko te zapytania, których realnie potrzebuje: kontrahenci, faktury sprzedaży i zakupu ze stanem rozliczenia, płatności, stany magazynowe. Reszta z punktu widzenia LLM-a nie istnieje.

---

Proaktywność: CronJoby rozmawiające z agentem

Agent czatowy odpowiada, gdy ktoś pyta. Tyle że najcenniejsze bywa to, o co nikt nie pomyślał zapytać — wczorajsza sprzedaż, faktury, które w nocy stały się przeterminowane, płatności wpadające w tym tygodniu.

Mechanizm jest wręcz wstydliwie prosty. CronJoby Kubernetesa (dni robocze 8:00, poniedziałki 8:30 z przeglądem tygodnia) POST-ują prompt raportu na własny endpoint chat-completions agenta, z dedykowanymi identyfikatorami sesji, żeby uruchomienia z harmonogramu nie zanieczyszczały prawdziwych rozmów. Agent przetwarza prompt dokładnie tak, jakby wpisał go użytkownik — woła te same narzędzia ERP, formatuje tak samo — i wysyła wynik skillem telegramowym.

Jeden agent, jeden zestaw narzędzi, dwa tryby pracy. Alternatywa to osobny pipeline raportowy, który duplikuje każde zapytanie do ERP — czyli dwa systemy po cichu podające różne liczby.

---

Wykresy i pliki: ostatnia mila też jest skillem

„Pokaż trend sprzedaży" nie powinno kończyć się „zaloguj się do portalu BI". Agent generuje wykresy matplotlib jako PNG i arkusze openpyxl jako XLSX we własnym workspace, a skill wysyłkowy dostarcza je na Telegram jako zdjęcia i dokumenty — z tą samą białą listą co wiadomości i z prawem czytania plików wyłącznie z katalogu roboczego agenta.

To ostatnie ograniczenie łatwo pominąć. Nie pomijaj go. Narzędzie wysyłające pliki bez restrykcji ścieżki to gotowy prymityw eksfiltracji — czeka tylko, aż ktoś go znajdzie.

---

Bezpieczeństwo w pięciu punktach

• Token ERP tylko-do-odczytu — agent niczego nie utworzy, nie zmieni, nie zaksięguje. Nie „nie powinien". Nie może.
• Biała lista Telegrama — rozmawiać z agentem i dostawać raporty mogą tylko jawnie wskazane czaty; wiadomości od obcych są odrzucane.
• Biała lista endpointów w konektorze — LLM nie improwizuje nowych zapytań.
• Krótkożyciowe, rolowane tokeny sesyjne — wyciekły token wygasa w minuty.
• Hosting w UE, minimalne uprawnienia — zgodność z RODO z konstrukcji, nie z disclaimera.

Nic z tego nie jest egzotyczne. I o to właśnie chodzi — dlatego firma w ogóle wpuściła agenta AI w okolice swoich ksiąg. Zaufanie jest właściwością architektury na długo przed tym, zanim stanie się argumentem sprzedażowym. O tej stronie pisałem szerzej w historii wdrożenia.

---

Co zrobiłbym inaczej

Zacząć od raportów, nie od Q&A. Ludzie potrzebowali kilku dni, żeby w ogóle wyrobić sobie nawyk pytania. Poranny raport dawał wartość pierwszego dnia — i przy okazji uczył ich, o co agenta można zapytać.

Zabudżetować dzień na autoryzację. Rolowanie tokenów jest udokumentowane, tylko że każda biblioteka kliencka zakłada, że token nie zmienia się przy każdym żądaniu. Logikę przechwytywania pisz od razu, nie po poranku spędzonym na tajemniczych 401.

Trzymać małą powierzchnię narzędzi. Kusi, żeby wystawić każdy endpoint ERP „na wszelki wypadek". Nie dawaj się skusić — każde dodatkowe narzędzie rozmywa trafność wyboru przez LLM. Agent zrobił się bardziej niezawodny, kiedy usunąłem zapytania, których nikt nie używał.

Jeśli pracujesz na enova365 i chcesz głębszych detali od strony ERP — przewodnik programisty po WebAPI opisuje licencje, kontrolery i typowe awarie, a integracja AI z enova365 pokazuje pełny obraz. A jeśli wolisz wynik zamiast budowy: to jest ta usługa — bezpłatny 30-minutowy audyt powie, który obieg dokumentów zwróci się pierwszy.