Inżynieria grafów dla agentów kodujących w AI: kontekst, kontrakty i naprawianie

„Inżynieria grafów” przyciąga ostatnio dużą uwagę, a większość wyjaśnień koncentruje się na grafach, węzłach i DAG-ach. Te elementy są ważne, ale nie odpowiadają na pytanie, które naprawdę należy zadać: dlaczego agenci do programowania oparte na sztucznej inteligencji nagle w ogóle potrzebują inżynierii grafów?

Rozwijający, który spędził miesiące z narzędziami takimi jak Claude Code, a później Codex, zauważył pewien wzorzec. Większość zadań programistycznych nie zawodzi się z powodu niemożności modelu napisania kodu. Poddają się one porażce, ponieważ długotrwałe procesy pracy stopniowo tracą swoją strukturę. Kontekst wychodzi z synchronizacji, zapominane są wymagania, wyniki stają się trudne do weryfikacji, a gdy coś idzie nie tak, łatwym rozwiązaniem jest często ponowne uruchomienie całego zadań.

To spostrzeżenie doprowadziło do powstania niewielkiej ramy badawczej o nazwie ContractGraph. Poniższy opis przedstawia jej założenia, to, co się sprawdziło, a co nie. Nie została stworzona, aby konkurować z istniejącymi ramami, ani nie jest powiązana z konkretnym modelem. Cel był węższy: czy można zaprojektować proces pracy tak, aby każdy krok miał jasny cel, dobrze zdefiniowany kontrakt oraz deterministyczny sposób określania, czy dany krok rzeczywiście został zakończony?

Rezultatem było graf sterowany kontraktem, który realizował proces badawczy poprzez izolowane zadania, wyraźną weryfikację oraz celowe naprawy, zamiast jednego ogromnego polecenia. Pierwsza implementacja była skierowana do agentów badawczych, ale leżące u jej podstaw idee równie dobrze pasują do agentów programistycznych, pipeline’ów dokumentów, systemów oceny oraz wszelkich procesów, w których kilka kroków sterowanych przez sztuczną inteligencję musi dostarczyć wyników, które można zweryfikować. Należy pamiętać, że to jest eksperyment jednego praktyka, więc wnioski wynikają z doświadczenia, a nie z pomiarowych benchmarków.

Co oznacza inżynieria grafów

Inżynieria grafów to praktyka dzielenia złożonego procesu opartego na sztucznej inteligencji na małe jednostki wykonawcze i łączenia ich za pomocą wyraźnych reguł. System zaprojektowany z wykorzystaniem inżynierii grafów zazwyczaj łączy kilka jednostek wykonawczych, wyraźne ścieżki przekierowania, wspólny stan, mechanizmy weryfikacji oraz trwałą koordynację.

Jedna odpowiedzialność na węzeł. Krawędzie wybierają następny krok. Stan udostępniany w całym procesie przenosi informacje, a etap weryfikacji decyduje o tym, czy kontynuować, spróbować ponownie, naprawić błąd czy zatrzymać się.

Dwie kwestie leżące u podstaw projektu

Mając nadzieję, że większość czasu poświęci węzłom, krawędziom i przepływowi wykonywania zadań, programista odkrył, że to nie są najtrudniejsze elementy. Ciągle powracały dwie pytania.

Pierwsze: jakie informacje agent AI powinien mieć prawo traktować jako prawdziwe? Drugie: po zakończeniu zadania – jak sprawdzić, czy wynik rzeczywiście odpowiada temu, o co proszono?

Im więcej testowano długotrwałych procesów pracy, tym wyraźniej stawało się, że te kwestie mają większe znaczenie niż sam graf. Agent, który rozpoczyna pracę od błędnych informacji lub kończy bez niezawodnego sposobu na sprawdzenie swojej pracy, po prostu przenosi błędy z jednego węzła na drugi. Te dwie kwestie stały się kontekstem i umową. Kontekst określa, w co agent może wierzyć, a umowa określa, co musi wygenerować. Wszystko inne w tym frameworku opiera się na tych dwóch koncepcjach.

Kontekst i umowy jako elementy budulcowe

Graph nie był najtrudniejszą częścią. Prawdziwym wyzwaniem było zapewnienie, że każdy węzeł rozpoczyna pracę od właściwych informacji i generuje coś sprawdzalnego, zanim proces pracy przejdzie dalej.

Kontekst. Agenci nie powinni widzieć wszystkiego. Węzeł otrzymuje tylko te dane, którym może zaufać – na przykład wymagania użytkowników, ograniczenia projektu, zweryfikowane dokumenty lub zaakceptowane wyniki z wcześniejszych węzłów.

Umowa. Każdy węzeł wymaga jasnej definicji tego, co musi dostarczyć. Gdy wynik nie spełnia wymogów umowy, proces nie może po prostu iść dalej. Należy sprawdzić wynik, naprawić błędną czynność lub zatrzymać proces.

Mówiąc prościej, kontekst określa, w co agent może wierzyć, a umowy określają, co musi dostarczyć. Gdy oba te elementy są jasno określone, graf staje się znacznie łatwiejszy do zrozumienia. Każdy węzeł ma jedną funkcję, wąskie źródło prawdy, wynik, który można zmierzyć, oraz deterministyczną kontrolę przed rozpoczęciem kolejnego kroku.

Od pomysłu do wykonywalnego grafu

Gdy kontekst i umowy są oddzielone, następnym pytaniem jest to, jak stają się one działającym procesem pracy. Celem nie było hardkodowanie oddzielnego grafu do badań, programowania czy generowania dokumentów. Zamiast tego proces pracy powinien być kompilowany dynamicznie na podstawie samego problemu, a nie z z góry zdefiniowanych ścieżek. Najpierw należy wykonać dwa kroki.

Pierwszy krok polega na utworzeniu kontekstu. Nie każdy plik czy dokument zasługuje na takie samo zaufanie, dlatego proces pracy tworzy kanoniczny kontekst – zweryfikowane źródło prawdy, na którym mogą się opierać wszystkie węzły. Jego surowce różnią się w zależności od zadania, takie jak dokumenty projektowe, wymagania użytkowników, kod, dokumenty projektowe lub inne dane uznawane za wiarygodne.

Drugi element tworzy umowę. Zamiast opisywać zadanie wyłącznie w prozie, generuje ustrukturyzowaną umowę, która określa, co musi zostać wygenerowane na każdym etapie, w jaki sposób węzły od siebie zależą oraz co musi zostać zweryfikowane przed kontynuacją wykonywania.

Gdy oba elementy są już gotowe, kompilowany jest przepływ pracy. Ten etap inicjalizacji nic nie wykonuje – jego zadaniem jest planowanie. W jego wyniku powstaje graf wykonywania, spakiet kontekstu dostosowany do każdego węzła, wielokrotnie używalne manifesty oraz wspólne umiejętności, a także kolejność wykonywania ustalona na podstawie umów, bez żadnej sztywnej sekwencji.

Następnie wykonywanie jest prostsze. Węzeł otrzymuje jedynie swój dostosowany kontekst, wykonuje przydzielone mu zadanie, przechodzi przez deterministyczną weryfikację, zapisuje przyjęty wynik i przekazuje kontrolę dalej. Jeśli weryfikacja się nie powiedzie, naprawiany jest tylko dotknięty problem przed wznowieniem wykonywania, więc nic nie musi być rozpoczynane od nowa.

Struktura grafu pochodzi zatem z kontekstu oraz umów podanych na początku, a nie z ustalonej implementacji. Ten sam proces kompilacji może tworzyć przepływy pracy do badań, programowania, dokumentacji lub czegokolwiek zupełnie innego, bez zmiany środowiska wykonywania.

Testowanie na większych i mniejszych modelach

Projektowanie frameworka to zaledwie połowa pracy. Trudniejsze pytanie brzmi, czy architektura wytrzyma, gdy przepływ pracy stanie się na tyle duży, by ujawnić jej słabości.

Pierwsze eksperymenty wykorzystywały znacznie większy przepływ pracy działający w Claude Code, z dynamicznie generowanymi węzłami wykonywania, zagnieżdżonymi etapami planowania oraz długimi zadaniami badawczymi. Jakość była doskonała, ale ukończenie tego przepływu pracy wymagało dużej ilości obliczeń modelu.

To rodzi kolejne pytanie: czy ta sama architektura grafu może nadal zapewniać niezawodne procesy pracy na znacznie mniejszym, tańszym modelu? W drugim eksperymencie wykorzystano proces generowania planu studiów, realizowany za pomocą OpenCode z Big Pickle zamiast modelu typu frontier. Mechanizmy pozostały takie same: proces był kompilowany dynamicznie, generowane były specjalistyczne węzły, każdy etap był weryfikowany w sposób deterministyczny, błędy były naprawiane w razie potrzeby, a ostateczny wynik pochodził z tego samego procesu.

Celem nie było porównywanie modeli ani wyłonienie zwycięzcy. Chodziło o sprawdzenie, w jakim stopniu niezawodność wynikała z architektury wykonania, a nie z surowych możliwości modelu. Zaskakującym odkryciem było to, że największe problemy wcale nie były błędami modelu – były to błędy w procesie pracy, i właśnie w tym miejscu inżynieria grafów stała się interesująca.

Gdzie doszło do awarii

Eksperyment nie wykazał, że inżynieria grafów zapobiega awariom. Pokazał natomiast, że inżynieria grafów sprawia, iż awarie stają się widoczne.

W trakcie pracy pojawiły się różne problemy: niekompletne metadane, brakujące dowody, nierozwiązane odniesienia, powtarzający się treść, nieważne stany cyklu życia, błędne informacje śledzenia, a nawet proste problemy z kodowaniem. Graf nie był przyczyną żadnego z nich. To są awarie, których można się spodziewać w długotrwałych procesach AI.

Zmieniło się to tak, że każda awaria miała dokładną lokalizację. Zamiast traktować cały proces jako jedną nieudaną eksploatację, można było znaleźć konkretny węzeł, który złamał swoje zobowiązania, naprawić tylko ten węzeł, ponownie przeprowadzić deterministyczną weryfikację i kontynuować od tego miejsca. Reszta procesu pozostała nienaruszona, ponieważ każdy udany etap został już zweryfikowany i zapisany.

To zmieniło sposób, w jaki programista postrzegał tę technikę. Nie była to metoda na uczynienie modeli mądrzejszymi, lecz sposób na uczynienie błędów lokalnymi, widocznymi i możliwymi do naprawienia. Graf nie eliminował błędów, ale nadawał każdemu z nich adres.

Dlaczego walidacja musi być deterministyczna

Model może z pełną pewnością stwierdzić, że zadanie zostało ukończone, ale to nie czyni tego faktem. Modele językowe doskonale rozumują, podsumowują i podejmują decyzje, ale są niewiarygodnymi sędziami w kwestii tego, czy proces pracy spełnił własne wymagania.

Dlatego każdy węzeł w ContractGraph kończy się deterministyczną weryfikacją. Nikt nie prosi drugiego modelu o opinię na temat wyniku. Proces pracy sprawdza obiektywne warunki: czy schemat zawiera wszystkie potrzebne pola? Czy spełniono wszystkie zależności? Czy obecne są wymagane pliki, a odnośniki są poprawne? Czy węzeł przekazał wszystko to, co obiecywał jego kontrakt? To nie są subiektywne oceny – każda z nich jest po prostu prawdziwa lub fałszywa.

To rozdzielenie okazało się jedną z najcenniejszych koncepcji w tym frameworku. Model skupia się na rozumowaniu, natomiast deterministyczna weryfikacja zajmuje się potwierdzeniem poprawności. Model może twierdzić, że jego praca jest zakończona, ale tylko deterministyczny walidator może udowodnić, że brakuje jakiegoś wymaganego pola.

Dlaczego dodatkowe wysiłki mogą się opłacić

Już przed tym eksperymentem deweloper traktował agenty do pisania kodu oparte na sztucznej inteligencji jak mały zespół, a nie pojedynczego asystenta. Nie było nic niezwykłego w tym, że Claude Code, Codex i OpenCode pracowały jednocześnie nad różnymi częściami jednego repozytorium.

To stworzyło nieoczekiwany problem. Agenci mogli mieć potrzebę zmiany tych samych plików lub polegać na tej samej implementacji, a bez koordynacji jeden mógł nadpisać pracę drugiego lub unieważnić wcześniej poczynione założenia.

Rozwiązanie było proste: każde zadanie miało swojego właściciela. Jeśli jeden agent był odpowiedzialny za część bazy kodu, pozostali nie mogli edytować tych plików, dopóki właściciel na to nie pozwolił. Dodanie kroku weryfikacji po każdym ważnym kroku sprawiło, że wiele konfliktów w ogóle nie dotarło do repozytorium.

Kompromis był oczywisty. Ten styl rozwoju wymaga znacznie więcej zasobów niż prośba o stworzenie funkcji przez jeden model w ramach jednej rozmowy, ponieważ każdy krok walidacji, ponownej próby, naprawy i koordynacji dodaje pracę. Mimo to rezultat był inny. Zamiast ciągłego naprawiania regresji spowodowanych wcześniejszymi poprawkami, proces pracy stał się znacznie bardziej przewidywalny, a funkcje w ten sposób tworzone wymagały niewielu poprawek, ponieważ każdy etap był weryfikowany przed rozpoczęciem następnego.

Inżynieria grafów nie jest czymś, co powinno być używane przy każdym zapytaniu, a przy małych zmianach stanowi czystą stratę czasu. W przypadku większych funkcji, długich implementacji lub pracy z wieloma agentami dodatkowy koszt przynosi coś cenniejszego niż tania inferycja – przynosi pewność siebie.

Jakie są rzeczywiste koszty

Nikt nie powinien interpretować tego jako stwierdzenia, że inżynieria grafów to rozwiązanie na wszystko. Przygotowanie kontekstu, generowanie kontraktów, kompilowanie grafu, walidacja, naprawa oraz agregacja każdej z tych czynności wiążą się z dodatkowymi kosztami w postaci wywołań modelu i tokenów. W porównaniu z pojedynczym poleceniem, cały ten proces jest bez wątpienia droższy.

Najwcześniejsze eksperymenty z modelami typu frontier przyniosły doskonałe wyniki, ale wymagały dużych zasobów obliczeniowych, co stało się głównym powodem testowania mniejszych, tańszych modeli. Wniosek był taki, że inżynieria grafów nie zmniejsza zapotrzebowania na obliczenia – ona je raczej przekierowuje. Zamiast tracić zasoby na naprawianie regresji, ponowne uruchamianie nieudanych procesów lub ciągłe naprawianie błędów w kolejnych etapach, system wykorzystuje je z góry na planowanie, weryfikację oraz izolację błędów.

To zmienia cel optymalizacji. Inżynieria grafów nie jest zaprojektowana tak, by zapewnić najtańsze wykonywanie zadań. Jej celem jest uzyskanie najbardziej przewidywalnego wyniku. Jedno uruchomienie OpenCode pochłonęło dużą ilość tokenów. Tę wartość nie należy interpretować jako dowodu na to, że ten podejście jest tanie. Wręcz przeciwnie – pokazują one coś przeciwnego, ponieważ inżynieria grafów świadomie inwestuje więcej zasobów obliczeniowych, aby osiągnąć izolację błędów, możliwość audytu, kontynuowalność oraz większą pewność. To, czy jest to dobra zamiana, zależy wyłącznie od problemu.

Kiedy to ma sens

Inżynieria grafów nie jest konieczna we wszystkich procesach AI. W przypadku zapytania SQL, małej funkcji lub kilku modyfikacji interfejsu zazwyczaj wystarcza dobrze napisany prompt, a dodawanie kontraktów, warstw walidacji oraz grafów wykonywania tylko spowolniłoby i skomplikowało sprawę.

Zaczyna to być korzystne, gdy koszt niepowodzenia przewyższa koszt dodatkowych obliczeń. Dotyczy to długotrwałych badań, prac nad dużą liczbą cech, pracowników wieloagentowych, systemów wrażliwych na kwestie bezpieczeństwa, automatyzacji przedsiębiorstw oraz wszelkich procesów, których wyniki muszą być weryfikowalne i powtarzalne. Im więcej kroków ma proces pracy, tym bardziej wartościowa staje się wyraźna koordynacja.

Główna lekcja nie dotyczy inteligencji. Tam, gdzie proces pracy jest skomplikowany, jego struktura ułatwia jego śledzenie, sprawdzanie, naprawianie i rozwijanie. Ta koncepcja jest również daleka od ukończenia – wykonywanie z uwzględnieniem zależności, inteligentniejsze planowanie, optymalizacja zasobów, ponowna kompilacja grafów częściowych oraz lepsza koordynacja między agentami to wszystko obszary, które pozostają nierozważone. Krótka wersja tej lekcji: używaj instrukcji do rozwiązywania zadań, a inżynierii grafów do budowania systemów.

Uwagi końcowe

Na początku oczekiwano, że poznamy grafy. Tym, czego naprawdę nauczyło to ćwiczenie, były granice, weryfikacja i koordynacja. Graf nie był tym, co miało znaczenie. Ważny był jasny cel każdego kroku, ograniczenie tego, w co agent może wierzyć, definicja tego, co musi wygenerować, oraz dowód ukończenia pracy, zanim przejdzie się do czegoś innego.

To nie jest jedyny sposób na budowanie systemów AI, a nie każdy proces pracy wymaga tak dużej struktury. Jednak w przypadku zadań złożonych, długotrwałych lub wymagających udziału wielu agentów, inżynieria grafów oferuje praktyczne rozwiązanie dla systemów, które są bardziej przewidywalne i łatwiejsze do rozwijania.

Jeśli trzeba zapamiętać jedno zdanie, niech będzie to następujący łańcuch: prompt określa życzenie, kontekst ustala, co agent może uznać za fakt, kontrakt precyzyjnie opisuje to, co ma zostać dostarczone, a graf jest mechanizmem pokazującym, że praca została ukończona.

W momencie tego eksperymentu ContractGraph wciąż się rozwijał, a jego repozytorium nie zostało jeszcze opublikowane, ponieważ najpierw miała zostać uproszczona architektura. Aby uzyskać szersze wprowadzenie do tego tematu, poszukaj ogólnego przewodnika po inżynierii grafów, ponieważ ten tekst dotyczy tylko jednej platformy, a nie całej dziedziny.