Harness engineering: system wokół modelu decyduje o agencie AI

• Analytics Vidhya opublikowało 19.10.2026 przewodnik po harness engineering. Harness to system wokół modelu: daje mu informacje i narzędzia, pilnuje kroków zadania i sprawdza wynik.
• Claude Code i OpenAI Codex to model plus harness. Dwa produkty na tym samym modelu mogą działać bardzo różnie, bo różnią się harnessem.
• W demo harness odrzucił przedwczesne „gotowe", zablokował zapis do testów i wyjście poza piaskownicę, a limit kroków zatrzymał agenta zapętlonego na jednej akcji.
• Demo działa na skryptowym modelu, a nie na prawdziwym. Sam harness nie gwarantuje, że każdy wynik jest poprawny.

Agent AI do kodowania napisze funkcję w kilka sekund. Działająca funkcja to jednak dopiero połowa roboty. Agent musi rozumieć projekt, znaleźć właściwe pliki, bezpiecznie używać narzędzi i sprawdzić, czy jego zmiany działają. Analytics Vidhya pokazuje 19.10.2026, jak zbudować system, który to wszystko zapewnia, i demonstruje go na małym przykładzie w Pythonie. Przykład używa modelu odtwarzającego zapisane akcje, więc dowodzi mechanizmu, a nie jakości żadnego prawdziwego modelu.

Model widzi tylko tekst, więc ktoś musi zrobić resztę

Sam model nie zrobi tego wszystkiego. Widzi wyłącznie tekst, który mu podasz. Nie uruchomi testu i nie zapisze swojego postępu. Może też powiedzieć, że skończył, choć wcale nie skończył. System, który dostarcza brakujące elementy, nazywa się harness, a projektowanie go to harness engineering.

Według autorów harness łączy model z informacjami i narzędziami, zarządza krokami zadania i sprawdza wynik. W zależności od systemu może obejmować:

• instrukcje i reguły projektu,
• wyszukiwanie kontekstu i pamięć,
• narzędzia, takie jak terminal, przeglądarka czy baza danych,
• kontrolowane środowisko, w którym działają akcje,
• kroki workflow, zatwierdzenia i ponowienia,
• testy, ewaluacje i logi.

Spójrz na Claude Code i OpenAI Codex. Autorzy opisują je jako model plus harness: dostęp do plików, terminal, pliki z instrukcjami projektu, pytania o zgodę i uruchamianie testów. Stąd ich wniosek, że dwa produkty na tym samym modelu mogą zachowywać się bardzo różnie. To nie magia modelu, to system dookoła niego. Pisaliśmy już o DeepSeek Harness, a to kolejny przykład, że ta warstwa żyje własnym życiem.

Prompt, kontekst i harness to trzy różne rzeczy

Przewodnik rozdziela te pojęcia. Prompt odpowiada na pytanie „jak zapytać", kontekst na pytanie „co model musi wiedzieć", a harness na pytanie „co model musi zobaczyć, zrobić i sprawdzić". Prompt może polecić agentowi uruchomić testy, ale to harness musi dać mu sposób, żeby je uruchomić i zgłosić wynik.

Autorzy zaznaczają, że termin jest nowy i bywa używany różnie. Czasem oznacza tylko kod uruchamiający narzędzia, a czasem cały system wokół modelu. Przewodnik przyjmuje szersze znaczenie.

Pętla agenta: model proponuje, harness rozlicza

Harness nie woła modelu jeden raz. Działa w pętli: buduje kontekst, pozwala modelowi zaproponować akcję, wykonuje ją, sprawdza rezultat i zaczyna od nowa. Pętla kończy się, gdy testy przejdą albo gdy zadziała limit, na przykład liczby kroków. Wtedy agent zgłasza, gdzie się zatrzymał, albo prosi człowieka o pomoc.

Kontekst jest odbudowywany w każdym przebiegu, więc model zawsze widzi najnowsze wyniki. Model może twierdzić, że skończył, ale to harness decyduje, czy testy faktycznie przeszły. Pozwolić modelowi samemu ocenić własną robotę to jak pozwolić uczniowi wystawić sobie ocenę na świadectwie.

Sześć warstw harnessu

Autorzy twierdzą, że większość harnessów potrzebuje sześciu warstw. Bezpieczeństwo i koszty przecinają je wszystkie.

• Instrukcje: krótki plik, np. AGENTS.md albo CLAUDE.md, który działa jak mapa projektu i wskazuje, które sprawdzenia uruchomić. Ma być punktem wejścia, a nie pełnym podręcznikiem.
• Kontekst: więcej nie znaczy lepiej. Za dużo niepowiązanych plików może przysłonić szczegóły, które mają znaczenie. Pomagają wyszukiwanie, streszczanie długich logów, kompaktowanie historii, notatki w pliku i subagenci z czystym kontekstem.
• Narzędzia i wykonanie: agent dostaje tylko te narzędzia i uprawnienia, które są mu potrzebne. Na przykład edytuje pliki w izolowanym workspace, nie ma dostępu do produkcji, a przy akcjach z zewnętrznymi skutkami czeka na zgodę człowieka.
• Trwały stan: plan, dziennik decyzji i wyniki testów zapisane poza tymczasowym kontekstem modelu, żeby następna sesja miała skąd wznowić pracę.
• Orkiestracja: co po czym, kiedy ponowić, kiedy zatrzymać się i zapytać człowieka. Więcej agentów nie poprawia wyniku automatycznie. Każdy potrzebuje jasnej roli, wystarczającego kontekstu i sposobu sprawdzenia albo połączenia swojej pracy.
• Weryfikacja i obserwowalność: końcowa wiadomość agenta nie jest dowodem. Dowodem są testy, kontrole typów, wyniki buildu, a logi i ślady pokazują, gdzie agent się pomylił.

Demo: agent mówi „naprawione", a harness sprawdza

Zadanie w przewodniku jest proste: funkcja checkout nalicza rabat dwa razy, a agent ma to naprawić bez ruszania testów. Całość mieści się w jednym pliku harness_demo.py. Demo korzysta tylko z biblioteki standardowej Pythona 3.9 lub nowszego, więc nic nie trzeba instalować. Domyślny limit to 8 kroków, a wyjście narzędzi jest przycinane do 600 znaków. Harness blokuje ścieżki spoza workspace oraz zapis do tests/ i AGENTS.md.

Scenariusz 1: nieudolny, ale skuteczny przebieg

Skryptowy model robi po kolei kilka błędów:

• Krok 3: mówi „Fixed" przed jakąkolwiek zmianą. Harness sam uruchamia testy, one nie przechodzą, więc zakończenie zostaje odrzucone, a błąd wraca do modelu.
• Krok 4: próbuje nadpisać plik z testami. Bramka narzędzi odmawia, bo testy są tylko do odczytu.
• Krok 5: próbuje odczytać plik spoza workspace. Piaskownica odmawia.
• Kroki 6 i 7: model robi właściwą poprawkę, testy przechodzą i harness akceptuje zakończenie.

Po każdym kroku harness zapisuje przebieg do pliku .harness/state.json, więc przerwana praca ma punkt wznowienia.

Scenariusz 2: agent zapętlony na jednej akcji

Tu model w kółko czyta ten sam plik. Limit kroków zatrzymuje uruchomienie po 5 krokach i zapisuje status. Bez limitu zablokowany agent zużywałby tokeny dalej. Autorzy podsumowują, że w demo model popełnił trzy błędy z rzędu, a wynik i tak był poprawny, bo harness sprawdzał pracę, blokował niebezpieczne akcje i pilnował granic pętli.

Co to demo dowodzi, a czego nie

Wynik pochodzi ze skryptowego modelu, który odtwarza stałe akcje. Dzięki temu demo działa offline i daje powtarzalny rezultat. Adapter do prawdziwego modelu autorzy dołączyli, ale nie uruchamiali go na potrzeby przewodnika i radzą traktować go jako punkt wyjścia do własnych testów. Żeby spróbować z prawdziwym modelem, potrzebujesz pakietu Anthropic SDK i klucza API w zmiennej środowiskowej (klucz nie ląduje wtedy w kodzie), a potem uruchamiasz python harness_demo.py --claude. Kod harnessu się nie zmienia, ale prawdziwy model wybierze własne kroki, więc jego ślad będzie inny niż w skrypcie.

Bezpieczeństwo, koszty i ograniczenia harnessu

Agent jako niezaufany pracownik

Agent, który może uruchamiać polecenia i czytać pliki, może też robić błędy w ekspresowym tempie. Autorzy radzą traktować go jak niezaufanego pracownika:

• sandboxing: akcje w izolowanym środowisku, bez dostępu do produkcji i zbędnych sekretów,
• najmniejsze uprawnienia: np. baza tylko do odczytu, dopóki zapis nie jest potrzebny,
• bramki zatwierdzeń dla rzeczy trudnych do cofnięcia, jak kasowanie danych, wysyłanie wiadomości czy wdrożenia,
• ślad audytowy: log każdego wywołania narzędzia.

Osobny punkt to prompt injection. Tekst, który agent czyta, czyli strona WWW, komentarz w zgłoszeniu albo plik, może zawierać instrukcje próbujące nim sterować. Każdą treść z zewnątrz traktuj jako dane, trzymaj wrażliwe narzędzia z dala od kroków czytających niezaufany tekst i wymagaj zgody przed ryzykownymi akcjami, które po nich następują. Jeśli interesują Cię wdrożenia w firmach, o agentach AI w europejskich MŚP pisaliśmy osobno.

Pętla ma być tania i ograniczona

Po stronie kosztów autorzy wymieniają limity kroków i czasu, budżety tokenów, limity ponowień (po kilku próbach eskalacja zamiast powtarzania w nieskończoność) oraz dobór wielkości modelu do zadania: mniejszy i szybszy do prostych kroków, mocniejszy do trudnych decyzji. To ta sama logika, którą pokazuje historia agenta przeglądarkowego od Asany: o koszcie decyduje całe ustawienie, nie sam model.

Czego harness nie załatwi

Dobrze zaprojektowany harness sprawia, że praca agenta jest bardziej kontrolowana i łatwiejsza do oceny, ale nie gwarantuje, że każdy wynik jest poprawny. Testy mogą pomijać ważne przypadki, dokumentacja bywa nieaktualna, a narzędzia mogą zwracać niepełne informacje. Harnessy się też starzeją. Wiele ich elementów obchodzi słabości dzisiejszych modeli, więc przy zmianie modelu autorzy radzą usunąć jeden element, uruchomić testowe zadania ponownie i zostawić go tylko wtedy, gdy wyniki bez niego się pogorszą. Zabezpieczenia i testy chroniące przed realnym ryzykiem zostają zawsze. Zmiany warto mierzyć na małym zestawie reprezentatywnych zadań: przed i po zmianie porównujesz wskaźnik powodzenia, liczbę kroków, koszt i czas.

Nie musisz pisać kodu, żeby z tego skorzystać. Masz prawo nie wiedzieć, jak działa pętla agenta, ale możesz przyjąć jej logikę przy każdym zadaniu oddawanym AI. Weź jedno zadanie, które deleguje się do AI w Twojej pracy, i w pięć minut zapisz trzy zdania: po czym poznasz, że zadanie jest skończone (dowód, nie deklaracja), czego AI nie wolno ruszać i po ilu nieudanych próbach ma przestać i zapytać Ciebie. Dokładnie tym zajmuje się harness, tylko Ty robisz to ręcznie. Przy okazji zajrzyj, jak sam rynek ogranicza agentów kodujących: to ten sam odruch, którego uczy ten przewodnik.