Jak działa Accounting AI Agent: jeden agent, 80+ narzędzi i realne dane z wFirma

W naszym artykule produktowym opisaliśmy już, co potrafi Accounting AI Agent: odpowiada na pytania o VAT, PIT i CIT, pracuje na realnych fakturach w wFirma i automatyzuje rutynę. To było spojrzenie od strony użytkownika. Teraz podejdźmy z drugiej strony — od strony realizacji — i zobaczmy, jak to wszystko działa w środku.

Księgowość w Polsce to nieustannie zmieniające się stawki, terminy i wymogi, a cena błędu jest tu liczona w realnych pieniądzach i karach. Zwykły chatbot jest w tym temacie niebezpieczny: pewnie poda nieistniejący termin, wymyśli numer rachunku albo «przypomni sobie» zeszłoroczną stawkę — i wszystko to brzmi przekonująco. Zbudowaliśmy system tak, aby miał jak najmniej powodów do zmyślania: agent nie zgaduje z pamięci, lecz sięga po żywe dane — Twoje faktury w wFirma, polskie rejestry państwowe, oficjalny kalendarz terminów podatkowych. W tym artykule przejdziemy całą drogę: od ogólnej mapy systemu po to, który model odpowiada za które zadanie. Po drodze — wszystkie kluczowe schematy, uporządkowane dla czytelnika, a nie dla inżyniera.

Przez cały tekst przewija się jedna myśl: siła tego produktu tkwi nie w rozmiarze modelu, lecz w dyscyplinie wokół niego — w narzędziach, kontrolach i powiązaniu z realnymi danymi. Od niej zaczynamy.

Jak zbudowany jest cały system

Zanim zanurzymy się w szczegóły, warto zobaczyć mapę. Accounting AI Agent to pełnoprawna aplikacja webowa (a nie «nakładka na ChatGPT»): ma panel w przeglądarce, bota Telegram, serwer z kontrolą dostępu i walidacją, warstwę integracji ze światem zewnętrznym oraz bazy danych.

flowchart TB
  subgraph Clients["Jak użytkownicy trafiają do agenta"]
    WEB["Aplikacja web<br/>(Next.js)"]
    TG["Bot Telegram"]
  end
  subgraph Core["Serwer i AI"]
    API["Serwer (API)<br/>logowanie · uprawnienia · walidacja"]
    AGENT["Agent AI<br/>(jeden, na LangGraph)"]
    OCR["Rozpoznawanie paragonów<br/>(GPT-4o vision)"]
  end
  subgraph Integrations["Integracje ze światem zewnętrznym"]
    WF["wFirma<br/>faktury · firma · płatności"]
    KSEF["KSeF<br/>rządowe e-faktury — FA(3)"]
    REG["Polskie rejestry<br/>Biała Lista MF · KRS"]
  end
  subgraph Data["Przechowywanie"]
    PG["PostgreSQL<br/>dane · pamięć AI"]
    RED["Redis<br/>sesje · limity"]
  end
  WEB --> API
  TG --> API
  TG --> OCR
  API --> AGENT
  AGENT --> WF
  AGENT --> KSEF
  AGENT --> REG
  API --> PG
  API --> RED
  WF --> PG

Po lewej — sposoby wejścia: panel w przeglądarce i bot Telegram. W centrum — serwer odpowiedzialny za logowanie, uprawnienia i walidację danych, oraz sam agent AI. Po prawej — świat zewnętrzny: wFirma (platforma księgowa), KSeF (państwowy system e-faktur) i polskie rejestry publiczne. Na dole — magazyny: PostgreSQL na dane i pamięć długoterminową agenta, Redis na sesje i ograniczanie obciążenia. Dalej omówimy każdy duży blok po kolei.

Jeden agent, a nie «rój»

Modne jest dziś budowanie «zespołów» z wielu agentów AI, które przekazują sobie zadania. My świadomie poszliśmy inną drogą: mamy jednego agenta. Otrzymuje wiadomość, sam decyduje, które narzędzia wywołać, w razie potrzeby wywołuje je po kolei lub kilka naraz, a następnie układa końcową odpowiedź. Żadnego «dyspozytora» rozdzielającego zapytania między podagentów — to prostsze, bardziej przewidywalne i tańsze w debugowaniu.

Działa według klasycznej pętli «rozumowanie → działanie»: model patrzy na wiadomość i historię, decyduje, czy potrzebne jest narzędzie, wywołuje je, otrzymuje wynik — i pętla powtarza się, aż gotowa będzie ostateczna odpowiedź.

stateDiagram-v2
  state "Agent AI (model)" as A
  state "Narzędzia" as T
  [*] --> A: wiadomość użytkownika
  A --> C: odpowiedź modelu
  state C <<choice>>
  C --> T: są wywołania narzędzi
  C --> [*]: gotowa odpowiedź (bez wywołań)
  T --> A: wyniki dołączone do rozmowy
  note right of A
    Model z podpiętymi
    narzędziami
  end note
  note right of T
    Narzędzia działają i zwracają
    dane z wFirma,
    KSeF i rejestrów
  end note

Aby agent nie «zapętlił się» w nieskończonych wywołaniach narzędzi, jest twardy bezpiecznik — nie więcej niż 25 kroków na jedno zapytanie. W praktyce to z zapasem wystarcza nawet przy złożonych scenariuszach w rodzaju «znajdź kontrahenta i wystaw mu fakturę», a przed zapętleniem chroni niezawodnie.

Droga jednej wiadomości

Co dokładnie dzieje się między «użytkownik nacisnął wyślij» a «przyszła odpowiedź»? Kolejność kroków ma znaczenie, więc pokażmy ją w całości.

flowchart TB
  A["Użytkownik wysyła wiadomość"] --> B["Pobierz klucz modelu<br/>użytkownika"]
  B --> C["Utwórz model<br/>(OpenAI lub Google Gemini)"]
  C --> D["Wykryj język<br/>z tekstu (ru / pl / en)"]
  D --> E["Wczytaj pamięć długoterminową<br/>o firmie użytkownika"]
  E --> F["Zbuduj prompt systemowy<br/>rola + język + reguły + podatki + pamięć"]
  F --> G["Podłącz narzędzia<br/>58, a z HR i KSeF — do 82"]
  G --> H["Uruchom agenta<br/>(pętla rozumowanie — narzędzia)"]
  H --> I["Zapisz rozmowę"]
  I --> J["Zaktualizuj pamięć<br/>(w tle)"]
  I --> K["Odczytaj odpowiedź<br/>(w tle, opcjonalnie)"]

Zwróć uwagę na dwa «tłowe» kroki na końcu. Gdy odpowiedź trafi już do użytkownika, system — nie zatrzymując go — aktualizuje pamięć długoterminową i w razie potrzeby przygotowuje odczyt. Innymi słowy, użytkownik nie czeka, aż wykona się cała mechanika służbowa — odpowiedź dostaje od razu.

58 narzędzi, a z HR i KSeF — do 82

Cała «siła» agenta tkwi w narzędziach. Narzędzie to konkretna umiejętność: «pobierz listę faktur», «utwórz kontrahenta», «policz wynagrodzenie», «wyślij fakturę do KSeF». Model nie wykonuje tych działań sam — decyduje jedynie, które narzędzie i z jakimi parametrami wywołać, a wykonuje je sprawdzony kod.

flowchart LR
  AGENT(["Agent AI wybiera potrzebne narzędzia"])
  subgraph BASE["Zawsze dostępne — 58 narzędzi"]
    direction TB
    T1["Firma i kontrahenci<br/>wyszukiwanie po NIP, rejestry"]
    T2["Faktury i sprzedaż<br/>utwórz · wyślij · PDF"]
    T3["Płatności i wydatki"]
    T4["Podatki: KPiR · JPK_VAT · PIT"]
    T5["Kalendarz terminów podatkowych"]
    T6["Biała Lista rachunków"]
    T7["Dokumenty · księgi · pojazdy · terminy"]
  end
  subgraph OPT["Włącza się, gdy skonfigurowane"]
    direction TB
    HR["HR i płace — 15"]
    KS["KSeF — 9"]
  end
  AGENT --> BASE
  AGENT -.-> OPT

Bazowe 58 narzędzi ma każdy użytkownik. Dwa kolejne zestawy — 15 dla kadr i płac oraz 9 dla KSeF — włączają się automatycznie, jeśli odpowiednie możliwości są skonfigurowane. Razem — do 82 narzędzi w rękach jednego agenta. Co ważne, część narzędzi w ogóle nie zależy od wFirma i jest dostępna dla wszystkich i zawsze: na przykład kalendarz terminów podatkowych i sprawdzenie kontrahenta na «Białej Liście».

Odpowiedzi na realnych danych, a nie z głowy

To kluczowa różnica wobec «mądrego, ale zmyślającego» chatbota. Gdy pytanie dotyczy konkretów — Twojej firmy, kontrahenta, kwoty — agent idzie po dane do wiarygodnych źródeł, zamiast je wymyślać.

flowchart LR
  Q["Pytanie lub działanie<br/>użytkownika"] --> AGENT["Agent AI"]
  AGENT --> WF["wFirma<br/>realne faktury, firma,<br/>płatności, wydatki"]
  AGENT --> REG["Rejestry publiczne<br/>Biała Lista MF · KRS"]
  REG --> AF["Autouzupełnianie po NIP<br/>nazwa · REGON · adres"]
  AGENT --> WL{"Płatność ≥ 15 000 zł?"}
  WL -->|tak| CHK["Sprawdź rachunek na Białej<br/>Liście MF (obowiązkowo)"]
  WL -->|nie| SKIP["Zwykły zapis"]
  WF --> ANS["Odpowiedź na realnych danych<br/>+ oficjalne linki"]
  CHK --> ANS
  AF --> ANS

Kilka szczegółów, które oszczędzają czas i nerwy:

Autouzupełnianie po NIP. Wystarczy podać jeden numer podatkowy kontrahenta — brakujące nazwę, REGON i adres system sam pobierze z rejestrów publicznych (Biała Lista Ministerstwa Finansów i KRS) i pokaże, które pola uzupełnił automatycznie.

Kontrola na «Białej Liście». Dla każdej płatności od 15 000 zł polskie prawo (art. 117ba Ordynacji podatkowej) wymaga upewnienia się, że rachunek kontrahenta jest na oficjalnej «Białej Liście» MF. Agent ma wprost polecone wykonywać tę kontrolę automatycznie, gdy realizujesz dużą płatność — abyś nie stracił prawa do zaliczenia wydatku do kosztów przez formalność.

KSeF: e-faktury po państwowemu

Wraz z przejściem Polski na obowiązkowy system e-faktur KSeF biznes zyskał nową rutynę. Agent bierze ją na siebie: potrafi wygenerować ustrukturyzowaną fakturę w wymaganym formacie (FA(3)), wysłać ją do KSeF, doczekać oficjalnego potwierdzenia i dopasować faktury przychodzące do Twoich zapisów.

flowchart LR
  A["Faktura z czatu<br/>lub z wFirma"] --> GEN["Wygeneruj<br/>FA(3) XML"]
  GEN --> SEND["Wyślij do KSeF"]
  SEND --> POLL["Sprawdzanie statusu<br/>w tle (co minutę)"]
  POLL --> UPO["UPO — oficjalne<br/>potwierdzenie"]
  subgraph Incoming["Przychodzące"]
    IN["E-faktury z KSeF"] --> MATCH["Dopasuj<br/>do zapisów wFirma"]
  end

Osobne usługi działające w tle śledzą statusy już wysłanych faktur i — jeśli skonfigurowano — same wysyłają do KSeF nowe faktury utworzone w wFirma. A przy tworzeniu faktury bezpośrednio na czacie wystarczy podać nazwę firmy — brakujące NIP i adres system wstawi z lokalnej bazy kontrahentów.

Paragon ze zdjęcia

Kolejny sposób na wyeliminowanie ręcznego wprowadzania to po prostu sfotografować paragon. Użytkownik wysyła zdjęcie w Telegramie, a system rozpoznaje je, zanim jeszcze do gry wejdzie agent AI.

flowchart LR
  P["Zdjęcie paragonu<br/>w Telegramie"] --> OCR["Rozpoznawanie<br/>(GPT-4o vision)"]
  OCR --> CARD["Ustrukturyzowana karta:<br/>sprzedawca · kwota · data · NIP"]
  CARD --> EXP["Utwórz wydatek w wFirma<br/>(kontrahent — po NIP automatycznie)"]
  N["Osobny krok w obsłudze zdjęcia,<br/>jeszcze przed agentem AI"] -.-> OCR

Rozpoznawaniem zajmuje się model GPT-4o z obsługą obrazów. Język odpowiedzi dobiera według języka Twojego konta Telegram, a wynik oddaje w postaci schludnej karty, z której wydatek jednym krokiem trafia do wFirma.

Pamięć długoterminowa o Twoim biznesie

Dobry asystent nie dopytuje o to samo dwa razy. Dlatego agent ma pamięć długoterminową: zapamiętuje fakty o Twojej firmie, częstych kontrahentów i Twoje preferencje — i uwzględnia je w kolejnych rozmowach. Przy tym pamięć jest urządzona starannie i przewidywalnie.

flowchart TB
  subgraph Extract["Ekstrakcja (w tle, po odpowiedzi)"]
    R["Odpowiedź gotowa"] --> RULES["Analiza wg reguł i wzorców<br/>bez LLM: «moja firma…», «zawsze…»"]
    RULES --> USE["Śledzenie częstych narzędzi<br/>i kontrahentów"]
  end
  subgraph Store["Przechowywanie (PostgreSQL)"]
    M[("Pamięć: fakty o firmie ·<br/>częste kontakty · preferencje ·<br/>wzorce pracy")]
  end
  subgraph Decay["Wygasanie (leniwie, raz dziennie)"]
    DEC["Brak użycia przez 30 dni →<br/>obniżamy pewność"] --> HIDE["Pewność zbyt niska →<br/>fakt ukrywany"]
  end
  subgraph Inject["Wstawienie do promptu"]
    TOP["Weź do 20 najważniejszych<br/>(budżet ~6000 znaków)"] --> SP["Dodaj do promptu systemowego<br/>następnej rozmowy"]
  end
  USE --> M
  RULES --> M
  M --> DEC
  M --> TOP

Jest tu nieoczywisty, ale zasadniczy szczegół: pamięć napełnia nie osobny model AI, lecz deterministyczne reguły. System szuka w rozmowie wyraźnych znaczników («moja firma jest na podatku liniowym 19%», «zawsze wystawiaj w PLN») i odnotowuje często używanych kontrahentów oraz operacje. To tanie, szybkie i nie dodaje kolejnego powodu do halucynacji.

Pamięć jest rozłożona na zrozumiałe kategorie — fakty o biznesie, częste kontakty, preferencje i wzorce pracy — i nie rośnie bez kontroli: to, co dawno się nie przydało, stopniowo «wygasa» i jest ukrywane, a do promptu wstawianych jest tylko kilkanaście najważniejszych rekordów, w ramach ścisłego budżetu znaków. Dzięki temu kontekst pozostaje trafny, a koszty modelu — pod kontrolą.

Prompt systemowy i język

Prompt systemowy to instrukcja, którą agent otrzymuje przed każdą rozmową. Nie jest statyczny: system składa go z warstw dopasowanych do konkretnego zapytania — bazowa rola eksperta księgowego, reguły języka, wskazówki dotyczące narzędzi, reguły formatowania odpowiedzi, standardy zawodowe i zastrzeżenia, wymogi dokładności, obsługa błędów oraz, w razie potrzeby, aktualne polskie dane podatkowe i pamięć osobista.

Język system wykrywa automatycznie z samej wiadomości: cyrylica — odpowiadamy po rosyjsku; polskie znaki diakrytyczne — po polsku; w pozostałych przypadkach — po angielsku. Dalej wszystkie narzędzia zwracają wynik już w odpowiednim języku — z formatowaniem liczb, dat i kwot przyjętym w danym kraju.

Twoje klucze, Twój wybór modelu

Ważna cecha architektury: klucze do modeli językowych należą do użytkownika. Każdy podłącza własny klucz (przechowywany w bazie w postaci zaszyfrowanej), a system działa na jego bazie. Obsługiwani są dwaj dostawcy — OpenAI i Google Gemini. Nowsze modele OpenAI (rodziny gpt-5, o1, o3) system obsługuje według ich szczególnych reguł — na przykład nie narzuca im parametru «temperatury».

Przy okazji, obsługi Anthropic już tu nie ma: wiosną 2026 roku ją usunęliśmy — pozostawała jedynie jako spuścizna starego kodu wieloagentowego i kolejny powód, by trzymać jeszcze jeden płatny klucz. Mniej zależności to czystsza architektura.

Sam projekt jest otwarty na GitHubie, a cały stos można postawić u siebie: własny serwer, własne klucze, pełna kontrola nad danymi. A dla tych, którzy chcą gotowego zarządzanego hostingu, dostępna jest subskrypcja na eKsiegowyAi.pl. O bezpieczeństwie też nie zapomniano: logowanie na tokenach, haszowanie haseł, ograniczanie częstości zapytań, walidacja wszystkich danych wejściowych i ochrona przed wstrzyknięciami do bazy, a każda operacja zmieniająca dane jest zapisywana w dzienniku audytu.

Podsumowanie

Gdy zebrać to wszystko razem, wyłania się prosta myśl: niezawodny asystent księgowy powstaje nie z «większego modelu», lecz ze starannej inżynierii wokół niego. Jeden zrozumiały agent zamiast splątanego roju. Dziesiątki sprawdzonych narzędzi zamiast domysłów. Żywe dane z wFirma i rejestrów państwowych zamiast «wiedzy z głowy». Obowiązkowe kontrole tam, gdzie wymaga tego prawo. Przewidywalna pamięć na regułach. I klucze, które zostają u użytkownika.

To właśnie ta dyscyplina zamienia gadatliwy model w narzędzie, któremu można powierzyć rutynę — i przy tym spać spokojnie, wiedząc, że nie wymyśli Ci numeru rachunku. Accounting AI Agent możesz wypróbować na eKsiegowyAi.pl albo złożyć samodzielnie ze źródeł na GitHubie. A jeśli potrzebujesz podobnego agenta wbudowanego w Twoje systemy i dane — napisz do nas: [email protected].

Który model za co odpowiada

Na koniec — zestawienie: który model realizuje które zadanie. Osobno podkreślmy: napełnianie pamięci długoterminowej działa bez modelu językowego, na deterministycznych regułach, dlatego nie ma go w tabeli.