Inżynieria promptów, kontekstu, narzędzi i pętli: cztery warstwy agenta AI
Inżynieria promptów i inżynieria kontekstu obejmują dwa z czterech warstw. Kontrolowane są przez inżynierię harnessów i pętli, przykład triażu na GitHubie oraz kolejność budowania.
Źródła: Prompt, context, harness, loop: the four layers of engineering an AI agent
W połowie 2025 roku dyrektor generalny Shopify, Tobi Lütke, napisał, że prawdziwą umiejętnością w pracy z modelami językowymi nie jest wcale projektowanie promptów, lecz dostarczenie wystarczającej ilości kontekstu, aby zadanie mogło zostać rozwiązane w sposób prawdopodobny. Andrej Karpathy zgodził się z tym, nazywając to sztuką polegającą na umieszczaniu dokładnie odpowiednich informacji w oknie kontekstowym, niezależnie od tego, co model będzie robił dalej. Wkrótce potem „inżynieria kontekstu” zastąpiła „projektowanie promptów” we większości poważnych dyskusji na temat wykorzystania modeli językowych.
Rok później zespoły tworzące autonomiczne agenty do programowania, boty do triażu problemów oraz pipeline’y samonaprawcze wciąż napotykają ten sam problem. Okazało się, że inżynieria kontekstu to tylko jeden z czterech poziomów tego problemu. Od najwęższego do najszerszego poziomy te to prompt, kontekst, harness i loop, przy czym każdy z nich otacza poziom znajdujący się wewnątrz niego. Dwa zewnętrzne poziomy – inżynieria harness i inżynieria loop – przyciągają najmniej uwagi, co jest dziwne, ponieważ to właśnie w nich teraz leży większość korzyści.
Pomyśl o tym jako o czterech pytaniach. Jak sformułowano prośbę? To jest prompt. Co model już wie na początku pracy? To jest kontekst. Co może faktycznie zrobić po uruchomieniu? To jest harness. A kiedy i jak często ktoś do niego zwraca się? To jest loop. Obecnie większość rzeczywistych korzyści leży w loop, poziomie, który rok temu ledwo miał nazwę.
Poniżej znajduje się praktyczna struktura służąca do odróżniania poszczególnych warstw oraz kolejność ich tworzenia. Zakłada ona, że już wykonałeś wywołania narzędzi lub funkcji przez API LLM. Jeśli jeszcze tego nie zrobiłeś, zacznij od tego.
W praktyce pojawia się pewien wzorzec, który wyjaśnia, dlaczego ta struktura jest przydatna. Gdy wynik działania agenta jest niezadowalający, naprawa prawie nigdy nie leży w samym promptzie – zazwyczaj wymaga interwencji na wyższej warstwie.
Warstwa 1: prompt, czyli to, co mówisz
Inżynieria promptów to najwęższa warstwa, która zajmuje się jedną rzeczą: sposobem sformułowania instrukcji skierowanej do modelu.
Przykłady: sposób sformułowania promptu systemowego, układ przykładów typu few-shot, prośba o krok po kroku rozumowanie lub dokładną analizę, oraz to, czy odpowiedź powinna być zwracana w formacie JSON, czy jako zwykły tekst. To sztuka pisania takiej wiadomości, która sprawi, że model w następnej rundzie wykona to, czego chcesz.
Praca jest rzeczywista. Dokładność przy wykonywaniu tej samej zadania może się znacznie różnić w zależności od tego, czy instrukcja jest ogólna, czy precyzyjna. Weźmy jako przykład agenta do triażu w projekcie GitHub. Słaby prompt wygląda w ten sposób:
Look at this GitHub issue and label it.
A jeden dokładny:
You are a triage agent for project X. For each issue, output JSON with:
component (one of the values in the taxonomy provided in context)
severity (critical | high | medium | low)
team (the owning team from the on-call table provided in context)
Base severity only on user-facing impact stated in the issue, not on your
own guess about difficulty. If the component is ambiguous, set
"component": "unknown" rather than guessing.
Model, narzędzia i wszystko inne są identyczne, a mimo to drugie polecenie daje ustrukturyzowany, uzasadniony wynik. Zwróć jednak uwagę na to, co uważa się za oczywiste. Proces ten odbywa się w ramach jednego kroku jednego wezwania. Zakłada się, że taksonomia oraz tabela dostępnych narzędzi są już załadowane, że narzędzia istnieją, a coś innego decyduje o tym, kiedy model zostanie wywołany.
Większość tutoriali kończy się w tym momencie. Większość systemów agentów produkcyjnych dopiero zaczyna pracę w tym obszarze.
Warstwa 2: kontekst, czyli to, co wie model
Inżynieria kontekstu obejmuje wszystko, co trafia do okna przed tym, jak model analizuje polecenie. Znajduje się ona przed procesem przetwarzania poleceń. Nawet doskonałe polecenie daje błędny wynik, jeśli kontekst jest błędny.
To obejmuje określenie, które dokumenty, pliki kodu lub rekordy bazy danych są pobierane i wprowadzane, jakie schematy narzędzi są ładowane, a które są zachowywane w celu oszczędzania tokenów, ile historii rozmów zostaje zachowane w porównaniu z tym, co jest podsumowywane lub usuwane, oraz co mówią instrukcje systemu na temat roli i ograniczeń modelu.
Drew Breunig opisał w 2025 roku sposoby, w których zawodzi kontekst. Zatrucie kontekstem występuje, gdy do okna informacji dostaje się halucynacja, która jest ciągle odwoływana. Rozpraszanie uwagi przez kontekst ma miejsce, gdy zbyt długie okno informacji zmusza model do polegania na nim i zaniedbywania tego, czego nauczył się podczas treningu. Zamieszanie kontekstowe powstaje, gdy nieistotne materiały obniżają jakość wyników. Konflikt kontekstów występuje, gdy nowo dodane narzędzia lub fakty są sprzeczne z istniejącymi instrukcjami.
Kontekst również kosztuje pieniądze, a jego kodowanie wpływa na wysokość rachunku. TOON, to kompaktowe kodowanie modelu danych JSON, według doniesień wykorzystuje o około 42,6% mniej tokenów niż JSON w ramach własnego zestawu testowego na połowę 2026 roku, przy dokładności wyszukiwania na poziomie około 72,2% w porównaniu z 71,4%. Oszczędności zależą od struktury danych. W przypadku prostych danych tabelarycznych spadek ten osiąga prawie 59%, natomiast przy zmiennych, zagnieżdżonych danych spada do około 33%. Zwykły format CSV może przewyższyć oba te rozwiązania, gdy dane są całkowicie prosty. Są to dane dostarczone przez sam projekt, więc warto je sprawdzić na własnych danych. Wniosek jest taki, że ta sama informacja, przedstawiona w trzech różnych formatach, różni się ceną oraz stopniem niezawodności przy odczytywaniu. Inżynieria kontekstu oznacza wybór nie tylko tego, co należy włączyć, ale także sposobu jego kodowania.
Krótki przykład pokazuje, jak to może pójść nie tak. Wyobraźmy sobie agenta do generowania artykułów, który ciągle wytwarza ogólne wyniki. Dwa dni spędzono na przepisywaniu instrukcji, dodawaniu przykładów i ograniczeń oraz doprecyzowywaniu definicji roli, ale nic się nie zmienia. Problemem nigdy nie były same instrukcje. Trzydzieści schematów narzędzi jest wcześniej załadowywanych do kontekstu i przytłaczają istotne wskazówki. Przejście na ładowanie opóźnione, przy którym definicja pojawia się tylko wtedy, gdy agent o nią prosi, poprawia jakość bez zmiany ani jednego słowa w instrukcjach. Dwa dni stracono na niewłaściwym poziomie.
Jeśli inżynieria instrukcji dotyczy dobierania słów, to inżynieria kontekstu dotyczy określania tego, co model może zobaczyć, zanim cokolwiek powiemy.
Warstwa 3: środowisko wykonawcze, czyli to, co model może robić
Środowisko wykonawcze to otaczające model środowisko, w którym może działać: wszystko, do czego może dotrzeć, oraz wszystko, co oddziałuje na niego.
Słynne wytyczne Anthropic dotyczące tworzenia skutecznych agentów wprowadziły koncepcję interfejsu agent-komputer, celowo zaprojektowanego jako odpowiednik interfejsu człowiek-komputer. Ich argument polega na tym, że należy włożyć tyle samo wysiłku w projektowanie sposobu, w jaki agent pracuje z narzędziami, ile branża włożyła w opracowanie sposobu, w jaki ludzie korzystają z oprogramowania.
Oto uproszczona definicja narzędzia z przykładu triażu:
{
"name": "apply_label",
"description": "Apply a label to a GitHub issue. Only use after reading the issue body and checking the component taxonomy.",
"parameters": {
"type": "object",
"properties": {
"issue_number": { "type": "integer" },
"labels": { "type": "array", "items": { "type": "string" } }
},
"required": ["issue_number", "labels"]
}
}
Pole description pełni funkcję kontekstową. Określa, kiedy model ma użyć danego narzędzia, a nie tylko jakie argumenty ma przekazać. Jednak schemat stanowi tylko połowę całego rozwiązania.
Druga połowa znajduje się w orkiestratorze, który otacza narzędzie elementami, których model nigdy nie widzi. Brama zatwierdzeń decyduje, czy funkcja apply_label ma zostać uruchomiona automatycznie, czy trafi do kolejki do osoby. Ograniczenie szybkości, na przykład 60 zapisów etykiet na godzinę, zapobiega niekontrolowanym pętlom powodującym spamowanie repozytorium. Granice środowiska testowego określają, z czym narzędzie może mieć kontakt. Takie otulacze kształtują zachowanie modelu bez żadnych zmian w instrukcjach systemowych.
Rozwiązanie to obejmuje również:
- System plików. Określa, jakie pliki model może otwierać, edytować, tworzyć lub usuwać.
- Pamięć. Określa, w jaki sposób informacje są przechowywane i odzyskiwane pomiędzy kolejnymi interakcjami, np. dzienniki korekt, wcześniejsze decyzje i konwencje projektowe.
Jeśli dać przeciętnemu promptowi dobre narzędzia, zazwyczaj będzie on lepszy od genialnego promptu bez narzędzi. Agent, który nie może otworzyć potrzebnego mu pliku, nie zyska nic na lepszym sformułowaniu. Najpierw wykorzystaj odpowiednie narzędzia.
Warstwa 4: pętla, czyli to, co czyni agentem
Inżynieria pętli to mechanizm, który sprawia, że agent staje się autonomiczny. Działa, obserwuje wynik, decyduje, co robić dalej, i kontynuuje działanie, aż zostanie osiągnięty cel lub zostanie spełniona warunek zatrzymania, przy czym na każdym kroku nie ma interwencji człowieka. Ta warstwa przekształca chatbota używającego narzędzi w coś, co potrafi samodzielnie rozwiązywać problemy.
Oto ta sama idea w pseudokodzie. Służy jedynie do ilustracji i nie może być uruchomiony: pomocniki takie jak model.decide i execute zostały pominięte.
def agent_loop(goal, max_iterations=10):
context = gather_initial_context(goal)
consecutive_errors = 0
for i in range(max_iterations):
action = model.decide(context, goal)
if action.type == "done":
return action.result
result = execute(action)
if result.error:
consecutive_errors += 1
if consecutive_errors >= 3:
# stuck: same approach keeps failing, decompose differently
context.add("Previous approach failed 3 times. Try a different strategy.")
consecutive_errors = 0
else:
consecutive_errors = 0
context.add(result)
return escalate_to_human(context)
Kilka wierszy zawiera decyzje, które są kluczowe: kiedy przestać, kiedy zmienić strategię, kiedy poddać się. OpenAI włączyło ten mechanizm do produktu, dodając w kwietniu 2026 roku polecenie /goal do Codex CLI. Ustalasz cel, a system kontynuuje działanie, dopóki nie uzna, że cel został osiągnięty lub wyczerpie budżet tokenów.
Naiwny pętla próbuje ponownie, dopóki coś nie zadziała. Dobrze zaprojektowana pętla zauważa, że utknęła, dekomponuje problem w inny sposób, zwraca się o pomoc do człowieka lub porzuca nieskuteczną metodę. Projektant Matt Webb zauważył w marcu 2026 roku, że agentowi, który ma przed sobą problem i pętlę while, ostatecznie uda się go rozwiązać. To określenie „ostatecznie” jest kluczowe dla inżynierii: limity prób, opóźnienia po powtarzających się niepowodzeniach oraz strategie dekompozycji w przypadku, gdy pojedyncza próba się nie udaje.
Dlatego właśnie ta warstwa stanowi największą zmianę w strukturze władzy. W przypadku inżynierii promptów osoba ta pisze każdą instrukcję. W inżynierii kontekstu osoba ta decyduje, co model widzi przy każdym wezwaniu. W inżynierii narzędzi osoba ta buduje narzędzia raz, a model może je wykorzystywać nieograniczenie. Inżynieria pętli różni się charakterem – osoba ta projektuje system, który wysyła polecenia do modelu, ocenia wynik i wywołuje go ponownie, bez udziału żadnej osoby w pomieszczeniu. Kontrola przechodzi od osoby wysyłającej polecenia do agenta na osobę, która zaprojektowała system generujący te polecenia.
Jon Udell zaproponował w połowie 2026 roku ujęcie, które warto zapamiętać: nie lubi wyrażenia „człowiek w pętli”, ponieważ przekazuje ono władzę maszynom, podczas gdy w rzeczywistości to nadal nasza pętla, a my teraz rekrutujemy agenty, aby dołączyli do zespołu.
Wszystkie cztery warstwy w jednym agencie: triaż zadań na GitHubie
Załóżmy, że agent zajmuje się nowymi problemami w GitHubie w ramach średniej wielkości projektu open-source: oznacza komponent, ocenia jego powagę i przekazuje każdy problem odpowiedniemu zespołowi.
- Wskazówka. Wskazówka systemu poleca mu znaleźć dotknięty komponent, ocenić jego powagę od krytycznej do niskiej, przydzielić odpowiedni zespół i odpowiedzieć w formacie strukturyzowanego JSON.
- Kontekst. Dla każdej decyzji system dostarcza tytuł i treść, pięć najnowszych komentarzy, taksonomię komponentów (plik YAML aktualizowany co kwartał), wcześniejsze podobne problemy wraz z ich etykietami (pobierane za pomocą wyszukiwania wektorowego jako przykłady) oraz osobę, która jest na dyżurze.
Każde 100 wydań system porównuje swoją dokładność z interwencjami ludzkimi i dostosowuje swoje progi. W podobnym systemie próg pewności miał według doniesień zaczynać się od 0,85, a nie od założonych 0,7, ponieważ błędne etykiety generowały więcej pracy dla ludzi niż te pominięte. Tego typu kalibracja to inżynieria pętli: można ją odkryć tylko poprzez uruchamianie systemu i obserwowanie jego błędów z biegiem czasu.
Jeśli usunąć jakąkolwiek warstwę, system będzie działał inaczej. Bez instrukcji format wyjściowy jest domysłem. Bez kontekstu wymyślane są nazwy komponentów. Bez narzędzi pomocniczych może ustalić, co robić, ale nie potrafi nadać etykiety ani przeszukać. Bez pętli pozostaje asystent, który działa tylko wtedy, gdy ktoś wpisze „przeprowadź triaż tego problemu” w oknie czatu, jeden po drugim.
Pochodzenie słownictwa
Pojęcie „prompt engineering” pochodzi z 2022 roku. Riley Goodside zaproponował już w 2023 roku podzielenie go na „context engineering” oraz „prompt programming”, ale termin ten stał się powszechnie używany dopiero po tym, jak Lütke i Karpathy użyli określenia „context engineering” w czerwcu 2025 roku, a Simon Willison wyjaśnił, dlaczego jest ono bardziej odpowiednie.
Określenia „Harness” oraz „scaffolding” weszły do powszechnego użycia dzięki pracom Anthropic nad skutecznymi agentami, które sformalizowały interfejs agent-komputer oraz potraktowały projektowanie narzędzi jako element inżynierii pierwszej klasy.
Inżynieria pętli jest najmłodszą z tych czterech koncepcji i nikt jej nie wymyślił. Powstała w wyniku połączenia kilku różnych podejść: celowo ukierunkowanej pętli w Codex firmy OpenAI, rozróżnienia w Anthropic między procesami pracy (stałymi ścieżkami) a agentami (pętlami kierowanymi przez model), rozwoju LangChain od routera przez maszyny stanowe aż po autonomiczne agenty, oraz rosnącego zwyczaju polegającego na tym, że to człowiek projektuje pętlę i nie ingeruje w jej poszczególne etapy.
To czterowarstwowe podział jest syntezą tych łączących się praktyk, a nie standardem branżowym. Mimo to nazewnictwo warstw przyspiesza diagnozę. Zadanie pytania, czy problem dotyczy promptu, kontekstu, narzędzi wspomagających czy samej pętli, natychmiast zawęża zakres poszukiwań.
Gdzie inwestować najpierw
Warstwy zostały wymienione od najwęższej do najszerszej, ale należy je budować najpierw w najszerszym zakresie, a dokładniej najpierw narzędziami wspomagającymi. Dla pierwszego autonomicznego agenta do programowania kolejność jest następująca.
- Łańcuch operacji. Musi umożliwiać czytanie i zapisywanie plików, dostęp do wiersza poleceń, możliwość wykonywania testów oraz poleceń git. Agent niezwiązany z programowaniem otrzymuje zamiast tego wywołania API, zapytania do bazy danych lub funkcje komunikacyjne; zasada pozostaje ta sama.
- Pętla. Nawet prosta pętla jest pomocna: uruchomić proces, sprawdzić, czy testy przeszły, w przypadku niepowodzenia zwrócić błąd, a po trzech próbach lub po odniesieniu sukcesu zakończyć działanie. Już to samo zapewnia większość korzyści wynikających z autonomii.
- Kontekst. Obserwując działanie agenta w ramach pętli, można zauważyć, czego mu brakuje – czy to kodu, wcześniejszych błędów, czy konwencji projektowych. Domysły z góry przeważnie tylko marnują czas.
- Pytania sterujące. Gdy Łańcuch operacji i pętla już działają, pytania potrzebne do kierowania nimi są zazwyczaj krótkie i proste. Trudne aspekty inżynieryjne zostały już wtedy rozwiązane gdzie indziej.
Istnieje jedno wyjątki. Jeśli agent musi wygenerować wynik w precyzyjnie sformatowanej formie, np. strukturyzowany JSON dla API lub zgodny z określonymi konwencjami markdown, praca nad promptem jest ważna już na wczesnym etapie, ponieważ skorygowanie błędów formatowania w trakcie działania pętli jest trudne. To przypadek specjalny, a nie standard.
Początkujący zazwyczaj odwracają ten porządek – tygodnie są poświęcane na tworzenie skomplikowanych promptów systemowych, podczas gdy agent nadal nie ma żadnych narzędzi, nie funkcjonuje w żadnej pętli, a w jego kontekście znajdują się niewłaściwe pliki.
Przejście od promptów do projektowania kontekstu oznacza przyznanie, że materiał dostarczany modelowi ma większe znaczenie niż sformułowanie żądania. Przejście do projektowania mechanizmów wykorzystania modelu i pętli oznacza jeszcze większe przyznanie władzy: osoba, która buduje system otaczający model, ma większą kontrolę niż osoba, która z nim rozmawia.
Literatura pokrewna
- Inżynieria kontekstu agenta: Przewodnik krok po kroku dla inżynierów ML: Jak zaprojektować to, co agent LLM widzi na każdym kroku: pobieranie danych, ustrukturyzowany kontekst, pamięć, kompresja i ocena, z przykładem agenta do debugowania modeli ML.
- Od zero-shot do samokonsystencji: Praktyczna lista technik formułowania promptów: Jak wybrać między technikami zero-shot, few-shot, dekompozycji, pętlami krytycznymi a promptami służącymi do rozumowania, z przykładem bota pomocniczego, oraz kiedy lepiej zlecić zadanie zwykłemu kodowi.