Agent Graph Engineering: ochrona agentów AI przed 36 błędami

Większość awarii produkcyjnych w systemach agentowych AI nie wynika z wadliwego promptu, lecz z braku strukturyzacji błędów oraz operowania na niezabezpieczonych interfejsach narzędziowych. Wdrożenie deklaratywnych reguł sterowania, izolacji w piaskownicach oraz klasyfikacji wyjątków pozwala wyeliminować naruszenia zasobów systemowych w 296 przeanalizowanych serwerach MCP i ograniczyć zbędne zużycie tokenów. Przejście od czytania odpowiedzi modelu do twardego ograniczania jego możliwości to kluczowy krok w ochronie infrastruktury IT w przedsiębiorstwie.

Deklaratywna kontrola narzędzi i eliminacja komunikatów w formie tekstu

Podejście Agent Graph Engineering zakłada, że narzędzia wywoływane przez modele nie mogą sygnalizować awarii poprzez zwracanie tekstowego komunikatu o błędzie. Zamiast tego infrastruktura wymaga zgłaszania strukturyzowanych wyjątków programistycznych, które wyraźnie rozdzielają informacje techniczne przeznaczone dla modelu od treści prezentowanych użytkownikowi. Taka izolacja zapobiega sytuacji, w której błąd kodu przekształca się w fałszywie poprawną odpowiedź.

Praktyka zwracania ciągów tekstowych typu „Error: could not issue refund” zmusza model LLM do wnioskowania o przyczynie awarii na podstawie języka naturalnego. Powoduje to, że warstwa aplikacyjna próbuje dopasowywać frazy tekstowe, co prowadzi do cichych błędów przy zmianie sformułowań. Ponadto krytyczne wyjątki programistyczne – takie jak ZeroDivisionError – zostają przechwycone i zamienione na grzeczne przeprosiny wygenerowane przez model, uniemożliwiając powiadomienie zespołu inżynieryjnego.

W paradygmacie Agent Graph Engineering narzędzia zgłaszają dedykowany wyjątek ToolError, który jest przekształcany w strukturyzowany obiekt zawierający maszynowo czytelny typ błędu (error_type). Wyjątki dzielą się na kategorie takie jak InvalidInputError, RateLimitedError oraz UpstreamServiceError. Konstrukcja ta rozdziela atrybut message (przeznaczony dla modelu LLM i zawierający parametry techniczne, na przykład przekroczenie limitu kwoty) od atrybutu user_message (przeznaczonego dla klienta i zawierającego informację biznesową). Wyjątki niebędące klasą ToolError nie są przechwytywane, co wymusza natychmiastowe zatrzymanie wykonania i rejestrację awarii w systemach monitoringu.

Wybór narzędzia przez model sterowany jest poprzez parametry description oraz planner_hint zawarte w dekoratorze rejestrującym, podczas gdy pełny docstring jest widoczny dla modelu dopiero na etapie wypełniania argumentów. Dla parametrów o zamkniętym zbiorze wartości trzeba stosować typ Literal zamiast typu str, co wymusza generowanie jawnych wartości w schemacie JSON. Dla akcji nieodwracalnych – takich jak wypłata środków – stosuje się rejestr transakcyjny (ledger) w bazie Postgres, który przypisuje identyfikator uruchomienia agenta do danej operacji, gwarantując egzekucję typu at-most-once w przypadku ponowienia próby po awarii procesu.

Tekst wprowadzany przez użytkownika oznacza się tagami izolującymi (demarcation) i czyści z ewentualnych prób zamknięcia znaczników. Weryfikacja wyjściowa (output screening) przebiega przed bramką zatwierdzenia przez człowieka, filtrując przedmioty o strukturze kluczy dostępowych lub identyfikatorów z innych zgłoszeń, co odciąża uwagę weryfikatora.

Jak ograniczyć koszty awarii agentów AI na produkcji?

Wykonywanie zadań przez autonomicznych agentów charakteryzuje się dynamicznym wyborem pętli wywołań, co uniemożliwia stosowanie tradycyjnych, globalnych reguł ponawiania prób. Bez jawnej klasyfikacji awarii systemy agentowe marnują budżet obliczeniowy na bezowocne powtórzenia lub wywołują niepożądane skutki uboczne. Wprowadzenie dedykowanych macierzy błędów oraz wzorców odporności na uszkodzenia pozwala precyzyjnie skierować problem do odpowiedniego poziomu obsługi.

Infrastruktura orkiestracji LangGraph oraz środowisko AgentWorks definują pięć warstw obsługi awarii, zastępując pojedyncze bloki przechwytywania wyjątków. Pierwsza warstwa wykorzystuje klucze idempotentności (idempotency keys) do zabezpieczenia wywołań zmieniających stan przed zwielokrotnieniem skutków ubocznych. Druga warstwa kwalifikuje błędy jako przejściowe (transient – błędy sieciowe lub kod 429, obsługiwane przez ponawianie z wykładniczym opóźnieniem) albo końcowe (terminal – błędy walidacji 400 lub braku uprawnień 403, zatrzymujące pętlę). Trzecia warstwa przekazuje strukturyzowany obiekt błędu do kontekstu modelu, umożliwiając mu samoistną korektę argumentów. Czwarta warstwa wdraża wyłączniki awaryjne (circuit breakers) oraz modele zastępcze (fallback models), chroniąc zewnętrzne interfejsy API przed przeciążeniem. Piąta warstwa ustala progi eskalacji do człowieka (human-in-the-loop) po wyczerpaniu limitu prób lub przy operacjach finansowych.

Macierz klasyfikacji błędów w orkiestracji agentowej precyzyjnie przydziela odpowiedzialność za naprawę problemu:

W orkiestratorze LangGraph kontrolę nad błędem przejściowym sprawuje prymityw RetryPolicy, konfigurujący parametry takie jak max_attempts, backoff_factor oraz opcję jitter, zapobiegającą przeciążeniom. Z kolei prymityw TimeoutPolicy ustala sztywne limity czasowe wykonania (run_timeout) lub braku postępu w strumieniu danych (idle_timeout). Po wyczerpaniu pętli ponowień uruchamiany jest węzeł error_handler, który atomowo aktualizuje stan i kieruje przepływ do procedur kompensacyjnych SAGA, cofających wcześniej wykonane kroki transakcji.

Należy uwzględnić koszt złożoności architektonicznej: badania wykazały, że wieloagentowy system orkiestracji grafowej osiąga wzrost jakości wykonania o 90,2%, jednak zużywa około 15-krotnie więcej tokenów w porównaniu do pojedynczej pętli konwersacyjnej.

Izolacja granic wykonania w ekosystemie Model Context Protocol

Dynamiczny rozwój ekosystemu Model Context Protocol ujawnił poważne luki w zabezpieczeniach interfejsów wykonawczych, z których większość działa z pełnymi uprawnieniami systemu operacyjnego. Brak kontroli dostępu umożliwia wstrzykiwanie instrukcji oraz nieautoryzowaną modyfikację zasobów dyskowych i sieciowych gospodarza. Rozwiązaniem tego problemu jest wprowadzenie deklaratywnych manifestów uprawnień i kontenerowej izolacji, które ograniczają możliwości wykonawcze bez modyfikacji kodu serwerów.

Standard Model Context Protocol opiera się na architekturze klient-serwer komunikującej się przez protokół JSON-RPC 2.0. Zbiór PulseMCP gromadzi ponad 6000 serwerów, jednak większość z nich uruchamia się jako lokalne podprocesy, dziedzicząc pełne uprawnienia użytkownika systemu operacyjnego. Stwarza to podatność na ataki typu tool poisoning, rug pull oraz ataki na poziomie aplikacji, w których złośliwy serwer modyfikuje docelowe adresy API lub próbuje wykraść prywatne klucze SSH.

W odpowiedzi na te zagrożenia stworzono ramkę bezpieczeństwa AgentBound, składającą się z dwóch elementów: deklaratywnej polityki kontroli dostępu AgentManifest oraz silnika egzekwowania reguł AgentBox. Model uprawnień AgentManifest wzorowany jest na systemie uprawnień platformy Android i definiuje uniwersalny słownik możliwości agenta, obejmujący dostęp do sieci (mcp.ac.network.client), systemu plików (mcp.ac.filesystem.read, mcp.ac.filesystem.write) oraz zmiennych środowiskowych (mcp.ac.system.env.read).

Silnik wykonawczy AgentBox izoluje serwery w kontenerach Docker, stosując reguły punktów montowania (mounts) dla plików oraz reguły iptables do ograniczenia ruchu sieciowego wyłącznie do zatwierdzonych domen. Ewaluacja ramki na zbiorze 296 najpopularniejszych serwerów z serwisu PulseMCP przyniosła następujące wyniki:

• Automatyczny generator manifestów AgentManifestGen osiągnął 80,9% dokładności w ocenie programistów oraz 96,4% zgodności w szczegółowej analizie ręcznej dla topowych serwerów.
• Silnik AgentBox całkowicie zablokował 100% ataków skierowanych na zasoby systemowe (wszystkie 9 możliwych do powstrzymania ataków w testach), w tym próby kradzieży kluczy SSH i manipulacji hostami w serwerze Google Maps.
• Narzut wydajnościowy izolacji kontenerowej ogranicza się do opóźnienia startu na poziomie 150-400 ms, podczas gdy opóźnienie wykonania pojedynczych operacji w czasie działania wynosi poniżej 0,6 ms na systemie macOS i 0,29 ms na systemie Debian.

Taksonomia 36 błędów i wielofazowa obsługa w SHIELDA

Procesy decyzyjne w złożonych przepływach agentowych ulegają zakłóceniom na poziomie wnioskowania, planowania oraz bezpośredniej egzekucji narzędziowej. Brak powiązania objawów wykonawczych z ich przyczynami w warstwie logiki prowadzi do powielania błędnych strategii. Ramka badawcza SHIELDA klasyfikuje uszkodzenia w ramach spójnej taksonomii oraz wdraża trójwymiarowy model obsługi wyjątków, umożliwiając automatyczną naprawę planu i bezpieczny powrót do stabilnego stanu.

Badania nad architekturą agentową pozwoliły zidentyfikować 36 typów wyjątków rozłożonych w 12 artefaktach systemowych, podzielonych na fazę wnioskowania i planowania (Reasoning/Planning – RP) oraz fazę wykonania (Execution – E). Do głównych artefaktów należą: Cel (Ambiguous Goal, Conflicting Goal), Kontekst (Context Corruption), Wnioskowanie (Contradictory Reasoning), Planowanie (Faulty Task Structuring), Pamięć (Memory Poisoning), Baza Wiedzy (Hallucinated Facts), Narzędzie (Tool Invocation Exception) oraz Interfejs (API Invocation Exception).

Ramka SHIELDA organizuje mechanizmy naprawcze w trójwymiarowy model kompozycyjny:

1. Obsługa lokalna (Local Handling): Baza 40 natywnych taktyk, w tym ponawianie z opóźnieniem (Retry with Backoff, wzorzec P018), ponowne formułowanie pytań, czyszczenie promptów oraz naprawa planu (Plan Repair, wzorzec P012).
2. Sterowanie przepływem (Flow Control): Decyzje o kontynuacji (Continue), pominięciu kroku (Skip) lub przerwaniu wątku (Abort).
3. Odzyskiwanie stanu (State Recovery): Operacje braku akcji (No-op), przywrócenia migawki pamięci (Rollback) lub kompensacji skutków zewnętrznych (Compensate).

W teście praktycznym z wykorzystaniem agenta AutoPR, wykonującego zadania w serwisie GitHub, wystąpienie błędu uprawnień podczas polecenia git push zostało sklasyfikowane w fazie wykonania jako ProtocolMismatchException. Po wyczerpaniu lokalnych prób ponowienia moduł Escalation Controller przeprowadził analizę przyczyn źródłowych (root cause analysis) wstecznie przez logi AgentOps. Wykazano, że pierwotną przyczyną błędu wykonawczego był błąd planowania Faulty Task Structuring polegający na wygenerowaniu planu modyfikującego chroniony plik workflow. Ramka SHIELDA zastosowała wzorzec P012 (Plan Repair / Abort / No-op), wstrzykując ograniczenie systemowe do kontekstu agenta i wymuszając wygenerowanie poprawnego planu bez naruszania reguł repozytorium.

Wnioski praktyczne i rekomendacje

• Skonfiguruj wywołania narzędzi tak, aby zgłaszały jawne wyjątki programistyczne ToolError z rozdzieleniem parametrów message i user_message, rezygnując ze zwracania komunikatów o błędach w formie tekstu.
• Wdróż deklaratywne manifesty uprawnień AgentManifest oraz izolację w piaskownicach kontenerowych AgentBox dla wszystkich serwerów Model Context Protocol, ograniczając dostęp do systemu plików, sieci oraz zmiennych środowiskowych.
• Zweryfikuj procedury ponawiania prób w orkiestratorze LangGraph, przydzielając prymitywy RetryPolicy i TimeoutPolicy do błędów przejściowych oraz wykorzystując funkcję interrupt() i trwały zapis stanu dla błędów wymagających decyzji człowieka.
• Wprowadź rejestr transakcyjny (ledger) w bazie danych Postgres dla wszystkich nieodwracalnych akcji zmieniających stan zewnętrzny, zabezpieczając system przed wielokrotnym wykonaniem tej samej operacji podczas ponawiania pętli.
• Zastosuj techniki rozgraniczania tekstu wprowadzanego przez użytkowników (demarcation) poprzez czyszczenie i ogrodzenie danych, a także wdrożenie automatycznych filtrów wyjściowych sprawdzających obecność kluczy i identyfikatorów przed przekazaniem wiersza do weryfikacji ludzkiej.

Źródła

• 3 Architectural Principles for Building Reliable AI Agents : r/AI_Agents – Reddit
• AgentBound: Securing Execution Boundaries of AI Agents – Programming Group
• Building Secure AI Agents: Microsoft Graph & Trio Gate Guide – YouTube
• Error Handling and Recovery Patterns for AI Agents – AgentWorks
• Fault Tolerance in LangGraph: Retries, Timeouts and Error Handlers – LangChain
• Graph Engineering Explained: The Missing Fifth Layer of AI Agent Architecture
• Graph-Based Agentic AI with LangGraph: Workflow Pathways for Long-Running Stateful Business Processes – arXiv
• How to Design AI Agent Guardrails: Best Practices for Input Validation, Output Filtering, and Safety Controls – StackAI