LangGraph

1. Przegląd koncepcji i problem systemowy

Próby zbudowania niezawodnego agenta produkcyjnego przy użyciu prostych pętli while True w Pythonie lub liniowych łańcuchów szybko napotykają krytyczne ograniczenia inżynierskie:

1. Brak trwałości (persistence): Jeśli serwer zostanie zrestartowany podczas 5-minutowego procesu agentowego, cały bieżący stan i postęp są bezpowrotnie tracone.
2. Nieprzewidywalność przepływu (Black Box Problem): Trudno przewidzieć, w którym momencie agent zdecyduje się zakończyć pracę, ani jak wymusić cofnięcie go o krok wstecz w przypadku błędu walidacji.
3. Niemożność długotrwałej pauzy (Human-in-the-Loop): Zatrzymanie wykonania programu w oczekiwaniu na potwierdzenie od użytkownika bez blokowania pamięci procesu w zwykłym kodzie jest niezwykle trudne.

LangGraph rozwiązuje te problemy, modelując systemy agentowe jako Orientowane Grafy Stanu (Stateful Graphs). Każdy złożony proces jest rozbijany na przejrzyste węzły (Nodes), krawędzie przejść (Edges) oraz jednolity, typizowany stan (State), który jest atomowo zapisywany w bazie danych po każdym kroku.

2. Taksonomia architektoniczna i model mentalny

Architektura LangGraph opiera się na czterech kluczowych encjach:

• 1. Shared State (Wspólny stan): Ściśle typizowany interfejs (poprzez TypedDict lub Pydantic). Definiuje schemat danych dostępnych dla wszystkich węzłów. Dla pól można określać specyficzne reduktory (Reducers), np. Annotated[list, add_messages], które automatycznie dopisują nowe wiadomości zamiast nadpisywać tablicę.
• 2. Nodes (Węzły grafu): Zwykłe funkcje synchroniczne lub asynchroniczne. Każdy węzeł przyjmuje bieżący stan, wykonuje obliczenia (wywołanie modelu, uruchomienie testów lub zapytanie do bazy danych) i zwraca częściową aktualizację stanu (State Delta).
• 3. Edges & Conditional Edges (Krawędzie przejść):
  • Zwykłe krawędzie: deterministyczne przejście z węzła A do węzła B.
  • Krawędzie warunkowe: funkcja-ruter analizuje ostatnie wyjście modelu i decyduje, dokierunkować przepływ (np.: jeśli wywołano narzędzie — przejdź do tools, jeśli znaleziono odpowiedź końcową — do END).
• 4. Checkpointers (Checkpointery): Sterowniki długotrwałego zapisu (MemorySaver do testów, PostgresSaver / SqliteSaver do produkcji). Tworzą niezmienne migawki (Snapshots) przy każdym superkroku.

3. Pipeline techniczny i mechanika wewnętrzna

Wykonanie grafu odbywa się zgodnie z modelem masowej synchronicznej równoległości (Bulk Synchronous Parallel, BSP):

1. State Initialization (Start sesji): Graf przyjmuje początkowe dane wejściowe i obiekt konfiguracyjny z kluczem thread_id. Checkpointer ładuje ostatnio zapisany stan dla tego wątku.
2. Superstep Execution (Wykonanie superkroku): Wszystkie aktywne węzły bieżącej fazy są wykonywane równolegle. Każdy węzeł odczytuje identyczną migawkę stanu i generuje własną łatkę aktualizacji.
3. Reducer Aggregation & Checkpoint Commit (Łączenie stanu): Po zakończeniu pracy wszystkich węzłów fazy system stosuje reduktory do otrzymanych zmian, formułuje nowy stan i atomowo zapisuje go w bazie danych.
4. Edge Routing & Interrupt Inspection (Rutynowanie i sprawdzanie przerw): Oceniane są przejścia warunkowe. Jeśli graf natrafi na punkt przerwania (interrupt_before), wykonanie jest bezpiecznie kończone, a sterowanie przekazywane zewnętrznej aplikacji.

4. Praktyczne scenariusze inżynierskie w produkcji

01. Autonomiczny cykl rozwoju i naprawy błędów kodu

Graf składający się z czterech węzłów:

• generate_code -> run_unit_tests -> evaluate_output.
• Jeśli testy przeszły pomyślnie — przejście do create_pr.
• Jeśli testy nie powiodły się — krawędź warunkowa cofa stan do generate_code wraz ze śladem stosu błędu (z ograniczeniem do maksymalnie 5 iteracji).

02. Proces finansowy Human-in-the-Loop

Agent analizuje sporne faktury klientów. Jeśli kwota zwrotu jest mniejsza niż $100, graf wykonuje zwrot automatycznie poprzez węzeł execute_refund. Jeśli kwota jest większa — graf zostaje przerwany (interrupt), generuje link do formularza akceptacji dla menedżera i wznawia pracę dopiero po otrzymaniu webhooka od człowieka.

03. System multiagentowy „Supervisor – Specjaliści”

Centralny węzeł Supervisor pełni rolę rutera najwyższego poziomu. W zależności od typu zadania przełącza kontekst między wyspecjalizowanymi podgrafami: ResearchSubgraph (wyszukiwanie w internecie i analityka) oraz DraftingSubgraph (generowanie kontraktów), kontrolując jeden wspólny kontekst korporacyjny.

5. Pułapki, typowe błędy i bezpieczeństwo

• Rozrost stanu (State Bloat): Przechowywanie w wspólnym stanie gigabajtowych plików PDF lub ogromnych tabel prowadzi do sytuacji, w której każdy checkpoint w PostgreSQL zajmuje setki milisekund. Przechowuj w stanie jedynie lekkie metadane i URL-e artefaktów w S3.
• Recursion Limit Exceeded: Jeśli krawędzie warunkowe nie mają gwarantowanego wyjścia z pętli, wykonanie zakończy się awarią systemową z powodu osiągnięcia limitu głębokości (domyślnie 25 kroków). Zawsze kontroluj licznik prób bezpośrednio w schemacie stanu.
• Nieserializowalne obiekty w State: Próba zapisania w stanie otwartego deskryptora pliku, połączenia z bazą danych lub zamknięcia funkcyjnego spowoduje awarię checkpointera przy próbie serializacji do JSON/Pickle.