Od Vibe Coding do AI Workflow: Co steruje agentem?

Czym właściwie jest agent AI?

Nie ma jednej definicji agenta, która działałaby tak samo w każdym narzędziu. Na potrzeby tego wpisu dobrym punktem startowym jest definicja z OpenAI: W tej definicji najważniejsze jest słowo "configured". Agent nadal opiera się na LLM-ie, ale nie jest tylko samym modelem. Jest modelem uruchomionym z konkretną konfiguracją i w konkretnym runtime. Ta konfiguracja może obejmować wybrany model, instrukcje, tryb pracy, dostępne narzędzia, ograniczenia, oczekiwany output i zasady przechodzenia między krokami. Runtime odpowiada za resztę: składa wejście dla modelu, dołącza instrukcje i kontekst, obsługuje tool calls, przekazuje wyniki narzędzi z powrotem do modelu i utrzymuje historię sesji. Dlatego agent nie jest po prostu "lepszym promptem". Prompt jest tylko jednym z wejść. O tym, jak agent działa, decyduje połączenie modelu, konfiguracji, runtime'u, dostępnego kontekstu, narzędzi i ograniczeń.

Agent jako koncepcja, nie implementacja

Nie traktuję tutaj agenta jako konkretnego pliku, trybu w IDE ani funkcji jednego narzędzia. Ten sam mechanizm może być inaczej opakowany w Copilocie, Claude Code czy aplikacji zbudowanej bezpośrednio na SDK. Nazwy plików, trybów i ustawień będą się różnić, ale nadal chodzi o ten sam problem: jak sterować pracą modelu, kontekstem, narzędziami, ograniczeniami i outputem.

Co wpływa na pracę agenta AI?

Skoro agent nie jest tylko modelem ani pojedynczym promptem, rozróżniam kilka grup elementów, które wpływają na jego pracę. Nie traktuję tego jako oficjalnej taksonomii z dokumentacji jednego narzędzia. To praktyczny model, który pomaga sprawdzić, czy agent ma właściwą konfigurację, właściwy kontekst i jasne granice pracy.

Konfiguracja agenta

To elementy, które definiują sposób pracy agenta niezależnie od konkretnego zadania.

• Model - wybór modelu wpływa na koszt, szybkość, jakość rozumowania i sensowny zakres odpowiedzialności. Innego modelu można użyć do eksploracji, innego do implementacji, a innego do review architektury.
• Rola i odpowiedzialność - agent powinien mieć zdefiniowane, czy ma eksplorować, przygotować specyfikację, implementować, zrobić review, czy tylko odpowiedzieć na pytanie.
• Instrukcje stałe (system instructions / system prompt) - reguły obowiązujące zawsze albo w danym typie pracy: wymagania architektoniczne, styl testów, konwencje projektu, sposób komunikacji i zasady formatowania outputu.
• Zasady szukania kontekstu (context discovery / retrieval guidance) - wytyczne określające, gdzie agent ma szukać brakujących informacji, z jakich źródeł ma korzystać i kiedy powinien przerwać exploration.
• Narzędzia i uprawnienia (tools / tool definitions) - dostęp do plików, edycji, terminala, testów, MCP, API albo innych źródeł. Sam LLM nie wykonuje tych akcji. Robi to runtime, który udostępnia narzędzia i egzekwuje część ograniczeń.
• Oczekiwany output - informacja, co agent ma zostawić po sobie: kod, specyfikację, summary, wynik weryfikacji albo materiał dla kolejnego kroku.

Input konkretnego zadania

To rzeczy, które agent dostaje na starcie danej pracy.

• Prompt użytkownika - bieżące polecenie, czyli co ma zostać zrobione teraz.
• Kontekst zadania - ticket, acceptance criteria, opis błędu, otwarte pliki, aktualny diff, specyfikacja albo wcześniejszy artefakt.
• Instrukcje lokalne - reguły dotyczące tylko tego zadania, na przykład zakres zmiany, ograniczenia albo miejsca, których nie należy ruszać.
• Handoff z poprzedniego kroku - materiał wejściowy powstały wcześniej, na przykład specyfikacja, exploration summary, review notes albo wynik wcześniejszej sesji.

Kontekst pozyskany w trakcie pracy

To elementy, których agent nie musi znać na starcie, ale które może znaleźć albo otrzymać podczas działania. W terminologii systemów agentowych można myśleć o tym jako o retrieved context i obserwacjach z narzędzi, a nie jako o ręcznie przygotowanym prompcie.

• Pliki i dokumenty (retrieved context) - fragmenty kodu, dokumentacja, konfiguracje, testy albo inne materiały odczytane w trakcie pracy.
• Wyniki narzędzi (tool results / observations) - output wyszukiwania, komend, testów, builda, lintera albo zewnętrznych API.
• Błędy i ograniczenia odkryte po drodze - brakujące zależności, niespójności w kodzie, nieaktualna dokumentacja albo przypadki, których nie było w początkowym opisie zadania.

Output i artefakty

To, co agent tworzy albo zostawia po sobie.

• Zmiany w projekcie - kod, testy, konfiguracja, dokumentacja albo inne zmodyfikowane pliki.
• Podsumowania i notatki (working notes / intermediate artifacts) - implementation summary, decision notes, exploration summary, review findings albo wynik analizy.
• Handoff artifact - output przygotowany po to, żeby stał się inputem kolejnego kroku, agenta albo sesji.

Guardrails i weryfikacja

To elementy, które ograniczają pracę agenta albo sprawdzają jej wynik.

• Guardrails - zasady mówiące, czego agent nie powinien robić albo co wymaga zatwierdzenia: zakazane pliki, destrukcyjne komendy, zmiany publicznego API, dostęp do danych wrażliwych, operacje poza zakresem zadania.
• Weryfikacja techniczna - testy, build, lint, typecheck, walidacja schematu albo inne automatyczne sprawdzenia.
• Weryfikacja merytoryczna - acceptance criteria, review architektury, zgodność z wymaganiami, zgodność z decyzjami projektowymi.

Nie chodzi o to, żeby każdy z tych elementów od razu zamieniać w osobny plik, agenta albo proces. W małym zadaniu część z nich może istnieć tylko w jednej rozmowie. W większym workflow warto je rozdzielać, bo inaczej łatwo pomieszać reguły projektu z danymi zadania, znaleziony kontekst z decyzją projektową, a output końcowy z materiałem dla kolejnego kroku.

Jak faktycznie działa agent AI?

Skoro wiemy już, jakie elementy wpływają na pracę agenta, warto zobaczyć, jak układają się one w czasie. Agent nie działa jako jedna długa, ciągła myśl modelu. W praktyce jest to pętla między runtime'em, modelem i narzędziami. Runtime to warstwa sterująca: CLI, IDE, aplikacja webowa, framework agentowy albo własny skrypt. To ona odpowiada za techniczną stronę pracy agenta: przygotowanie wejścia dla modelu, obsługę narzędzi, przekazywanie wyników i egzekwowanie części ograniczeń. W uproszczeniu wygląda to tak:

1. Runtime składa wejście dla modelu. Bierze konfigurację agenta, input zadania, dostępny kontekst, historię sesji i opis narzędzi, z których agent może skorzystać.
2. Model analizuje ten stan i generuje kolejny krok. Może odpowiedzieć tekstem, zaproponować zmianę albo zwrócić żądanie użycia narzędzia.
3. Jeśli potrzebne jest narzędzie, model nie wykonuje operacji samodzielnie. Zwraca do runtime'u ustrukturyzowane żądanie wywołania narzędzia (tool call), na przykład odczytania pliku, wyszukania fragmentu kodu albo uruchomienia testów.
4. Runtime wykonuje akcję poza modelem. To on czyta plik, odpala komendę, wywołuje API albo korzysta z MCP. To również runtime pilnuje uprawnień i może zatrzymać operację, jeśli wykracza poza dozwolony zakres.
5. Wynik narzędzia wraca do kolejnego kroku. Runtime dokłada go do kontekstu i wysyła następne wejście do modelu. Od tego momentu model może pracować już na nowej informacji: znalezionym pliku, błędzie testu, wyniku wyszukiwania albo logu z komendy. Pętla zaczyna się od nowa.

Ta pętla trwa do momentu, gdy agent przygotuje oczekiwany output albo zostanie zatrzymany przez runtime, limit kroków, błąd narzędzia lub guardrail. W narzędziach interaktywnych zatrzymanie może oznaczać pytanie do użytkownika albo prośbę o zatwierdzenie. W trybie nieinteraktywnym może skończyć się błędem, fallbackiem albo przerwaniem zadania. Context window ma skończony rozmiar. Runtime nie może dokładać kolejnych plików, logów i wyników narzędzi bez ograniczeń. Dlatego w pracy agenta ważny jest nie tylko dostęp do narzędzi, ale też selekcja tego, co wraca do kolejnych wywołań modelu. Najważniejsze jest to, że LLM nie posiada własnego dostępu do plików, terminala ani pamięci projektu. Dostaje tekstowy kontekst przygotowany przez runtime. Jeśli agent "pamięta", co wydarzyło się wcześniej, to dlatego, że runtime przekazał mu historię rozmowy, podsumowanie albo wynik poprzednich kroków. Tę historię można traktować jako pamięć krótkotrwałą sesji (conversation history / short-term memory). Jawne artefakty, takie jak specyfikacje, summary albo handoff file, są czymś innym: to stan workflow (state management), który można przenieść do kolejnej sesji albo kolejnego agenta. Jeśli agent "używa narzędzia", to dlatego, że runtime udostępnił mu taki mechanizm i wykonał operację po swojej stronie. To właśnie ta pętla odróżnia pracę agenta od pojedynczej odpowiedzi w czacie. Agent nie tylko odpowiada na prompt. Może iteracyjnie zbierać kontekst, wykonywać akcje przez narzędzia, analizować ich wyniki i dopiero na tej podstawie przygotować output.

Context flow, nie tylko input

Po opisaniu pętli runtime widać, że kontekst agenta nie jest stały. Z każdym krokiem może rosnąć o kolejne pliki, wyniki narzędzi, logi, błędy, zapisane decyzje i artefakty z poprzednich kroków.

To brzmi niewinnie, ale ma bardzo praktyczną konsekwencję: błędny albo przypadkowy kontekst może zaśmiecić całą sesję i wpływać na kolejne decyzje agenta. Jeśli na etapie exploration agent uzna przypadkową implementację za obowiązujący pattern, przeczyta przestarzałą dokumentację albo pominie ważny fragment domeny, błąd może zostać utrwalony już w pierwszym artefakcie. Specyfikacja będzie wtedy oparta na złym kontekście. Implementer poprawnie zaimplementuje tę specyfikację. Reviewer może sprawdzić diff względem planu i nie zauważyć problemu, bo kod będzie zgodny z błędnym założeniem. Bez weryfikacji artefaktów między krokami taki błąd może propagować się przez cały flow. Dlatego w pracy z agentami nie chodzi tylko o to, żeby "dać więcej kontekstu". Chodzi o to, żeby kontrolować jakość tego, co do niego ostatecznie trafia: inputu, wyników exploration, częściowych podsumowań i artefaktów przekazywanych dalej. Każdy z tych elementów może pomóc agentowi podjąć lepszą decyzję, ale może też utrwalić błąd i przenieść go do kolejnego kroku. W praktyce oznacza to dwie rzeczy:

• Input powinien być dobrany do roli agenta. Spec writer potrzebuje innych informacji niż implementer, a reviewer innych niż explorer. Wrzucanie wszystkim wszystkiego może wyglądać bezpiecznie, ale często zwiększa szum i zużywa okno kontekstowe bez realnej korzyści.
• Exploration musi mieć granice. Agent powinien mieć określone, gdzie szukać, czego szukać i kiedy przestać. Bez tego może czytać dużo plików, znaleźć przypadkowe podobieństwa i zbudować wniosek na materiale, który nie ma znaczenia dla zadania.

W agent workflow jakość kontekstu jest ważniejsza niż jego ilość. Każdy kolejny krok buduje na tym, co zostało dostarczone, znalezione albo przekazane wcześniej, więc słaby kontekst potrafi zepsuć wynik nawet wtedy, gdy sama pętla pracy wygląda poprawnie. To praktyczna wersja problemu znanego z pracy z LLM-ami: degradacji kontekstu i gubienia istotnych informacji w dużym oknie kontekstowym.

Output, artefakty i handoff

Skoro agent działa w pętli, jego output nie powinien być traktowany wyłącznie jako końcowa odpowiedź. W pracy nad większym zadaniem output często pełni dwie role: jest wynikiem danego kroku i jednocześnie materiałem wejściowym dla kolejnego. Najbardziej oczywistym outputem jest kod, ale w pracy z agentami równie ważne są artefakty pośrednie. Nie chodzi jednak o dokumentację dla samej dokumentacji. Artefakt powinien pomagać w dalszej pracy, a nie tylko wyglądać jak ślad po wykonanym zadaniu. W praktyce artefakt powinien robić przynajmniej jedną z trzech rzeczy:

• Ułatwiać review przez człowieka - dobry artefakt pokazuje rzeczy, które da się szybko sprawdzić: podjęte decyzje, założenia, przykładowe requesty API, diagram blokowy algorytmu, listę zmienionych obszarów albo przypadki brzegowe, które agent uwzględnił.
• Być precyzyjnym inputem dla kolejnego kroku - dobry artefakt powinien ograniczać konieczność odtwarzania ukrytej historii rozmowy. Kolejny agent, kolejna sesja albo człowiek powinien dostać jasny materiał wejściowy, a nie domyślać się, co właściwie było ustalone wcześniej.
• Wspierać kontrolę standardowego procesu SDLC - artefakt może zawierać wynik testów, status weryfikacji, listę niespełnionych acceptance criteria albo jednoznaczną rekomendację typu approve/reject. Dzięki temu łatwiej zatrzymać zmianę na review, w CI albo przed merge'em, zamiast przepychać błędny output dalej.

Handoff pojawia się wtedy, gdy output jednego kroku staje się inputem kolejnego. Specyfikacja może być handoffem dla implementera. Diff i wynik testów mogą być handoffem dla reviewera. Exploration summary może być handoffem dla kolejnej sesji. W małym zadaniu taki handoff może być nieformalny i istnieć tylko w historii rozmowy. To często wystarczy. Problem zaczyna się przy dłuższych albo bardziej ryzykownych zmianach. Wtedy jawny artefakt jest bezpieczniejszy, bo można go przeczytać, poprawić, zatwierdzić i wykorzystać w nowej sesji bez polegania na ukrytej pamięci rozmowy. Artefakt ma sens tylko wtedy, gdy pomaga coś sprawdzić, przekazać dalej albo zatrzymać w procesie. Jeśli nikt go nie czyta i żaden kolejny krok realnie z niego nie korzysta, to nie jest element kontroli workflow, tylko dodatkowy tekst w kontekście.

Zacznij prosto

Łatwo wpaść w pułapkę projektowania zbyt dużego workflow od pierwszego dnia. Skoro mamy agentów, tools, handoffy, guardrails i artefakty, to kuszące jest zbudowanie od razu całego procesu: agent od analizy, agent od specyfikacji, agent od implementacji, agent od testów i agent od review. Tylko że to często nie rozwiązuje problemu. Czasem jedynie przenosi chaos z jednego prompta do kilku nazwanych agentów. Na początku zwykle wystarczy jeden agent albo jeden prosty tryb pracy. Taki agent może przygotować zmianę, uruchomić testy i zrobić podstawowe self-review. W małym zadaniu to często jest wystarczające. Ważniejsze od liczby agentów jest to, czy agent ma jasno określone:

• jaką rolę pełni,
• jakich reguł ma pilnować,
• gdzie ma szukać brakującego kontekstu,
• czego nie powinien robić,
• co ma zostawić po sobie,
• jak wynik ma zostać sprawdzony.

Dopiero gdy prosty setup zaczyna boleć, warto go rozdzielać. Jeśli analiza wymaga przeglądania dużego codebase'u, warto wydzielić exploration albo spec writing, żeby implementer nie zaczynał od chaotycznego czytania repozytorium. Jeśli review jest zbyt powierzchowne, można przygotować osobnego agenta albo osobny tryb review. Jeśli każda sesja czyta te same pliki od nowa, warto zostawiać jawne exploration summary albo handoff file. To jest pragmatyczna granica: nie budować workflow dla samego workflow, tylko dokładać strukturę wtedy, gdy rozwiązuje realny problem.

Podsumowanie

Agent nie gwarantuje jakości tylko dlatego, że działa w trybie agentowym. Pod spodem nadal jest LLM, więc wynik zależy od jakości kontekstu, instrukcji, narzędzi i weryfikacji. Cały sens konfiguracji, runtime'u, artefaktów i handoffów polega na tym, żeby praca z AI była bardziej kontrolowalna. Chcemy wiedzieć, co agent dostał na wejściu, co znalazł, co zostawił po sobie i gdzie można zatrzymać błąd, zanim przejdzie dalej. Nie trzeba zaczynać od złożonego systemu agentów. Wystarczy prosty setup, ale świadomy: jasna rola, sensowny input, ograniczona exploration, czytelny output i podstawowa weryfikacja. Dopiero gdy taki setup zaczyna boleć, warto dokładać kolejne role, handoffy i artefakty.