Większość firm, z którymi rozmawiamy, chce agenta AI. Gdy pytamy, co dokładnie agent ma robić, słyszymy odpowiedzi w stylu „da radę ze wszystkim", „będzie komunikować się z dostawcami, śledzić faktury i planować zmiany". I tu właśnie leży sedno problemu. Agent, który robi wszystko, zazwyczaj w sposób zawodny nie robi niczego.
Ten artykuł to praktyczna metodologia — nie teoria, lecz ramy decyzyjne, które zweryfikowaliśmy przy realnych wdrożeniach. Przeprowadzimy Państwa od wyboru pierwszego use-case'u przez definicję narzędzi, guardrails i ewaluację aż po to, jak agenta stopniowo rozszerzać. Powiemy też, czego na początku lepiej unikać.
Krok 1: Wybierz wąski, dobrze ograniczony use-case
Najczęstszy powód niepowodzenia pierwszego agenta nie jest techniczny. To zbyt szeroki zakres.
Dobry pierwszy use-case spełnia następujące kryteria:
- Jasne wejście i wyjście — agent otrzymuje coś konkretnego i zwraca coś konkretnego (nie „przetworzy email")
- Weryfikowalność wyniku — Państwo lub system mogą sprawdzić, czy agent zrobił właściwą rzecz
- Ograniczone narzędzia — maksymalnie 3–5 narzędzi, a nie „dostęp do wszystkich systemów"
- Tolerowalna błędność — jeśli agent popełni błąd, da się go wykryć przed wystąpieniem skutków
Przykłady, które w praktyce sprawdzają się jako pierwsze projekty: agent, który każdego ranka pobiera nowe reklamacje z helpdesku, kategoryzuje je i zapisuje podsumowanie do Excela lub arkusza; agent, który sprawdza nowe zamówienia w systemie i wywołuje przepisane kroki API, gdy zamówienie spełnia zdefiniowane warunki; agent, który na żądanie wyciąga odpowiednią dokumentację z wewnętrznej biblioteki przy użyciu RAG nad dokumentacją przemysłową i formułuje odpowiedź.
Z kolei jako pierwszy projekt odradzamy: agenta z dostępem do kilku działów naraz, agenta wysyłającego e-maile lub wystawiającego faktury bez nadzoru, ani agenta, przy którym nie jest jasne, jak będzie mierzony sukces.
Krok 2: Zdefiniuj narzędzia — nie „co agent może", lecz „co agent wolno"
Narzędzia to serce agenta. Agent bez narzędzi to tylko chatbot; agent z nadmiernie swobodnymi narzędziami to zagrożenie bezpieczeństwa.
Przy definiowaniu narzędzi myśl w dwóch krokach:
Czego agent fizycznie potrzebuje? - Odczyt (baza danych, API, pliki, wektorowa DB) - Zapis (aktualizacja rekordu, wysłanie wiadomości, zapis do systemu) - Obliczenia lub transformacja (konwersja formatu, podsumowanie, klasyfikacja)
Na co agent otrzyma pozwolenie? To jest krytyczny krok, który się pomija. Każde narzędzie musi mieć jawny zakres: agent może czytać rekordy z tabeli X, ale nie usuwać. Może wywoływać endpoint API Y kluczem read-only. Może zapisywać do sekcji Z, ale nie modyfikować historycznych rekordów.
Dobra zasada dla pierwszego agenta: operacje zapisu wyłącznie przez bramkę HITL — czyli z zatwierdzeniem przez człowieka przed wykonaniem. Human-in-the-loop przy agentach to nie jest skomplikowana architektura; w LangGraph to jedno wywołanie interrupt(). Dodaje latencję odpowiadającą czasowi reakcji człowieka, ale zapobiega nieodwracalnym błędom.
Schemat każdego narzędzia musi być weryfikowalny maszynowo. Jeśli agent zwróci zniekształcony JSON jako argument narzędzia, trzeba to wykryć i powtórzyć — nie ignorować po cichu. To nie jest edge case — w produkcji jest to częste źródło problemów.
Krok 3: Wybierz prostą architekturę
Dla pierwszego agenta rekomendujemy pętlę ReAct — Reason, Act, Observe w prostym grafie. Powód jest prosty: to architektura najłatwiejsza do debugowania.
Jeśli czytali Państwo artykuł Architektury agentów AI, wiedzą Państwo, że istnieją bardziej zaawansowane wzorce (Plan-and-Execute, Reflexion, multi-agent). Są one zasadne — ale nie dla pierwszego projektu. Każdy dodatkowy krok to kolejne potencjalne źródło błędu i kolejna warstwa, w której nie wiadomo, co się dzieje.
Konkretny rekomendowany stack:
- Framework:
LangGraph— graf-based, jawny stan, wbudowany checkpointing; sprawdzony produkcyjnie w wdrożeniach enterprise - Model: zacznij od taniego i szybkiego modelu (poziom Haiku, poziom Flash lub lokalny model przez
Ollama); modele frontier (Opus, GPT) włącz dopiero gdy podstawowa logika działa - Pamięć: krótkoterminowy kontekst w stanie grafu; dla dłuższego horyzontu wektorowa DB — ale tylko jeśli pierwszy use-case tego rzeczywiście wymaga
Poważny błąd na początku: wybrać najwydajniejszy i najdroższy model, bo „chcemy najlepszych wyników", a potem dziwić się, że koszty są nie do utrzymania. Model jest łatwy do wymiany. Architektura i narzędzia — znacznie trudniejsze.
Jeden praktyczny detal: ustaw maksymalną liczbę kroków pętli. Agent bez limitu może przy nieoczekiwanym wejściu zapętlić się i przez noc zużyć tysiące tokenów. Wartość 10–15 kroków na jedno zadanie to rozsądny punkt startowy dla większości use-case'ów.
Krok 4: Guardrails — nie jako filtr, lecz jako architektura
Guardrails dla agentów AI to temat, który jest niedoceniany przy pierwszym projekcie, a potem boleśnie nadrabiany później.
Guardrails to nie tylko filtr wyjściowy („sprawdź, czy odpowiedź nie zawiera czegoś złego"). Guardrails to architektura wielowarstwowa:
- 1.Walidacja wejścia — co trafia do agenta? Czy to format, którego agent oczekuje? Czy wejście zawiera potencjalnie niebezpieczne instrukcje?
- 2.Klasyfikacja intencji — jeśli agent otrzymuje wolny tekst od użytkowników, należy sklasyfikować intencję przed przekazaniem jej do pętli agentowej
- 3.Zakres uprawnień narzędzi — jak opisano powyżej: każde narzędzie ma uprawnienia
- 4.Bramka HITL dla operacji zapisu — krytyczne akcje wymagają potwierdzenia człowieka
- 5.Filtr wyjściowy — semantyczna weryfikacja odpowiedzi przed wysłaniem
Dla pierwszego agenta w środowisku wewnętrznym (niewystawionego na zewnętrznych użytkowników) wystarczy zacząć od punktów 3 i 4. Walidacja wejścia i klasyfikacja intencji są niezbędne, jeśli agent otrzymuje dane od zewnętrznych lub nieznanych źródeł.
Prompt injection — atak polegający na tym, że niebezpieczna treść w wejściu przekonuje agenta do działania innego niż zamierzone — jest według OWASP LLM Top 10 najczęstszym zagrożeniem bezpieczeństwa aplikacji AI. Jeśli agent ładuje jakiekolwiek zewnętrzne treści (e-maile, strony internetowe, pliki od klientów), trzeba aktywnie brać pod uwagę to ryzyko.
Krok 5: Observability — bez niej agent nie trafia do produkcji
To zasada, od której nie odstępujemy: agent bez observability nie jest agentem produkcyjnym. To proof-of-concept.
Co konkretnie trzeba wiedzieć o każdym przebiegu agenta:
- Jakie było wejście i wyjście
- Ile kroków pętli zostało wykonanych
- Które narzędzia były wywoływane, z jakimi argumentami, co zwróciły
- Gdzie wystąpił błąd (jeśli wystąpił) i dlaczego agent wybrał konkretną akcję
Narzędzia, które to zapewniają: Langfuse (agnostyczny wobec frameworka, self-hostable), LangSmith (głęboka integracja z LangGraph), Arize Phoenix (oparty na OpenTelemetry, zaawansowane metryki ewaluacyjne). Observability agentów AI to dziś dojrzała dziedzina — nie ma powodu budować tego od zera.
Konkretny zysk w praktyce: przy jednym wdrożeniu dla klienta z logistyki dzięki trasom odkryliśmy, że agent poprawnie kategoryzował 94 % przypadków, ale przy jednej kategorii konsekwentnie wywoływał narzędzie z błędnym argumentem. Bez observability dowiedzielibyśmy się o tym dopiero po dziesiątkach błędnych zapisów w systemie.
Krok 6: Eval — skąd wiadomo, że agent działa poprawnie?
Ewaluacja to krok, który przy pierwszym projekcie jest najczęściej pomijany. Skutek: nie wiadomo, czy zmiana w prompcie, modelu lub narzędziach coś poprawiła, czy pogorszyła.
Dla pierwszego agenta wystarczy prosty eval harness:
- Przygotuj 20–50 przypadków testowych z zdefiniowanym wejściem i oczekiwanym wyjściem lub akcją
- Uruchamiaj agenta na tych przypadkach po każdej większej zmianie
- Śledź co najmniej dwie metryki: task completion rate (czy agent ukończył zadanie?) i tool call accuracy (czy agent wywoływał właściwe narzędzia z właściwymi argumentami?)
Nie trzeba od razu wdrażać złożonego frameworka ewaluacyjnego. Skrypt uruchamiający agenta na zestawie testowym i wypisujący wynik jest lepszy niż brak ewaluacji. W miarę jak system rośnie, ewaluacja aplikacji RAG i LLM staje się bardziej zaawansowana — ale podstawa pozostaje ta sama: mieć zestaw referencyjny i mierzyć względem niego.
Czego unikać przy pierwszym agencie
Na podstawie doświadczeń z wdrożeń — oto najczęstsze błędy, które wydłużają projekt lub go zatrzymują:
Zbyt wiele narzędzi od początku. Każde narzędzie to kolejne źródło awarii. Zacznij od trzech, rozszerzaj na podstawie rzeczywistej potrzeby.
Brak HITL dla operacji zapisu. Pierwszy zapis, który agent wykona niepoprawnie bez możliwości przechwycenia, zazwyczaj kończy projekt. Dodaj zatwierdzanie — można je usunąć później, gdy masz zaufanie do niezawodności.
System multi-agent jako pierwszy krok. System multi-agent w praktyce ma sens, gdy jeden agent nie wystarcza. Ale gdy jeszcze nie wiemy, co jeden agent robi źle, dodawanie kolejnych agentów zwiększy zamęt, nie zmniejszy.
Model jako główna zmienna. Słyszeliśmy to wielokrotnie: „Wypróbujemy GPT-5, na pewno rozwiąże problemy." W praktyce większość problemów wynika ze złej definicji narzędzi, brakującej walidacji lub niejasnego zakresu — nie z jakości modelu. Rozwiązuj architekturę, nie model.
Brak maksymalnych limitów. Agent bez limitu liczby kroków, bez timeoutu i bez alertu kosztowego może przez noc wygenerować tysiące wywołań. Ustaw limity od pierwszego dnia.
Stopniowe rozszerzanie: od prototypu do produkcji
Pierwszy działający agent to prototyp. Droga do produkcji wymaga kilku jawnych kroków:
- 1.Eval na zestawie testowym — co najmniej 20–50 przypadków, task completion rate > 85 % jako warunek minimalny
- 2.Shadow mode — agent działa równolegle z istniejącym procesem, ale nie ingeruje; porównujesz wyjścia
- 3.HITL dla wszystkich operacji zapisu — w pierwszej fazie produkcyjnej człowiek zatwierdza każdą akcję
- 4.Observability live — ślady muszą być dostępne od pierwszego dnia w produkcji
- 5.Stopniowe ograniczanie HITL — po 2–4 tygodniach z dobrymi metrykami można usunąć HITL dla akcji niskiego ryzyka
Rozszerzanie zakresu (nowe narzędzia, nowe use-case'y) to zawsze iteracja tego samego cyklu: zdefiniuj, przetestuj w shadow mode, wdrażaj stopniowo, śledź metryki.
Najczęstsze pytania
Jaki model wybrać dla pierwszego agenta?
Zacznij od taniego i szybkiego modelu — poziom Haiku lub Flash, ewentualnie lokalny model open-weight jak Ollama z Qwen lub Llama. Modele frontier (Opus, GPT) włącz dopiero gdy podstawowa logika działa i wiesz, gdzie dokładnie model nie wystarcza. Wymiana modelu jest łatwa; naprawa architektury — nie.
Ile narzędzi może mieć pierwszy agent?
Rekomendujemy maksymalnie 3–5 narzędzi w pierwszej wersji. Każde narzędzie to kolejne źródło awarii i kolejna rzecz do przetestowania. Lepiej mieć trzy dobrze przetestowane narzędzia niż dziesięć z niejasno określonymi granicami.
Czy muszę używać LangGraph lub innego frameworka?
To nie jest obowiązek. Własny kod daje pełną kontrolę i czasem mniej abstrakcji, niż jest potrzebne. Powód, dla którego rekomendujemy LangGraph przy pierwszych wdrożeniach produkcyjnych, to wbudowany checkpointing, HITL interrupt() i dobre ślady — te elementy trzeba by inaczej budować od zera.
Kiedy warto przejść na architekturę multi-agent?
Gdy jeden agent konsekwentnie nie nadąża — typowo z powodu zbyt szerokiego zakresu zadania lub potrzeby przetwarzania równoległego. Jeśli agent wykonuje sekwencyjnie 15 kroków, z których część mogłaby przebiegać równolegle, czas na podejście multi-agent. Ale to drugi lub trzeci projekt, nie pierwszy.
Jak oszacować koszty agenta w produkcji?
Kluczową zmienną jest nie tylko cena modelu, lecz także liczba kroków pętli na zadanie i retry rate. Jeśli agent wykonuje średnio 5 kroków, a retry rate wynosi 12 %, rzeczywista liczba wywołań jest o 12 % wyższa — a w wieloetapowych pipeline'ach ten narzut mnoży się dalej. Bardziej szczegółowe ramy do szacowania znajdą Państwo w artykule Koszty agenta AI w produkcji.
*MP Industrial Solutions pomaga firmom zdefiniować, zaprojektować i wdrożyć pierwszego agenta AI — od wyboru use-case'u przez architekturę techniczną aż po wdrożenie produkcyjne z observability i guardrails. Jeśli rozważają Państwo pierwszy krok, chętnie ocenimy konkretny przypadek podczas wstępnej konsultacji.*