LangGraph: jak kontrolować pracę agentów AI

Temat: Architektura systemów AI

Agent przygotował poprawną odpowiedź, a po wznowieniu zadania wysłał ją klientowi drugi raz. Pracowity, ale nie o to chodziło. LangGraph to biblioteka open source (licencja MIT, Python), która trzyma stan zadania agenta, pozwala go zatrzymać na decyzję człowieka i wznowić. Nie zastępuje jednak projektu uprawnień: to, co agentowi wolno zrobić, ustala twoja aplikacja. Wielu agentów do tego nie potrzebujesz.

Stan na 6.10.2026: pakiet langgraph jest w wersji 1.2.13 (wydanie z 5 października 2026 r.) i wymaga Pythona 3.10 lub nowszego (PyPI). Wersję 1.0 ogłoszono jako stabilną 22 października 2025 r., z deklaracją braku zmian łamiących zgodność do wersji 2.0 (LangChain).

Całą mapę ekosystemu, od LangChain przez LangGraph po LangSmith i Deep Agents, pokazuje poradnik LangChain dla firm.

Czym jest LangGraph

To framework i środowisko wykonawcze do stanowych, także długotrwałych procesów agentowych. Łączy kroki opisane regułami z krokami, w których pracuje model językowy. Nie wymaga całego LangChain (przegląd w dokumentacji).

Graf opisuje kroki i możliwe przejścia. Stan przechowuje to, co potrzebne dalej. Sam graf nie jest modelem AI i nie zastępuje uprawnień w CRM czy ERP.

Biblioteka jest open source na licencji MIT. Płatne bywa hostowanie: dokumentacja nazywa je LangSmith Deployment (LangGraph Platform to starsza nazwa). Wariant w chmurze wymaga planu Plus lub wyższego, a self-hosted z płaszczyzną sterowania planu Enterprise (dokumentacja, stan na 6.10.2026).

Kiedy to ma znaczenie dla firmy

Wybór sposobu orkiestracji to nie szczegół techniczny. To decyzja, kto i jak kontroluje pracę agentów w procesie: które kroki mogą iść same, które czekają na człowieka i kto ma prawo kliknąć „zatwierdzam”. Programista napisze graf, ale zarząd ustala granice.

Jeśli zadanie to jedna odpowiedź bez dalszych działań, ta warstwa może być zbędna. Przydaje się, gdy proces potrzebuje przerwania, wznowienia albo zatwierdzenia. Czy w ogóle potrzebujesz kilku agentów i który wzorzec współpracy wybrać, opisuje wpis system wieloagentowy AI: kiedy ma sens w firmie.

PotrzebaCo zaprojektować
Praca po przerwaniuTrwały zapis stanu i identyfikator sprawy
Akceptacja człowiekaPunkt zatrzymania i uprawniony decydent
Kilka ścieżekWarunki wyboru następnego kroku
Błąd narzędziaZasady ponowienia i zakończenia
Działanie w systemieAutoryzacja i ochrona przed powtórzeniem

Więcej agentów to nie automatycznie więcej pożytku. Każde przekazanie dodaje koszt, opóźnienie i miejsce, w którym kontekst się gubi.

Przykład: odpowiedź o statusie zamówienia

Modelowy proces: pracownik chce odpowiedzieć klientowi. Aplikacja sprawdza jego dostęp, pobiera dane i proponuje treść. Wysłanie wymaga zatwierdzenia. Kroki: identyfikacja sprawy, autoryzacja, odczyt, szkic, akceptacja, wysłanie. Przed wysłaniem sprawdź, czy ta wersja nie poszła już wcześniej.

To projekt przykładowy, nie funkcja włączana po instalacji. Integracje, reguły dostępu i odbiór trzeba napisać. W prostszym wariancie proces kończy się na szkicu, a wiadomość wysyła człowiek.

Graf stanu z punktem przerwania krok po kroku

Ten sam proces jako graf LangGraph wygląda tak (nazwy funkcji według dokumentacji przerwań i dokumentacji trwałości stanu, stan na 6.10.2026):

  1. Węzeł agenta. Model czyta sprawę i uznaje, że potrzebne są dane o zamówieniu.
  2. Narzędzie. Odczyt statusu z systemu zamówień, z uprawnieniami pracownika, nie agenta. Checkpointer zapisuje stan po każdym kroku w wątku o danym thread_id.
  3. Zatwierdzenie człowieka. Węzeł wywołuje interrupt() z treścią szkicu. Graf staje, stan czeka w checkpointerze. Człowiek może zatwierdzić, odrzucić albo poprawić szkic; dokumentacja opisuje też przerwanie wewnątrz narzędzia, żeby obejrzeć jego argumenty przed wykonaniem.
  4. Wznowienie. Aplikacja wywołuje graf z Command(resume=...) i tym samym thread_id. Węzeł z przerwaniem wykonuje się od początku, a wartość z resume staje się wynikiem interrupt().
  5. Wysyłka. Osobny węzeł po zatwierdzeniu, z kluczem operacji, żeby ponowienie nie wysłało wiadomości drugi raz. Odrzucenie kończy zadanie bez wysyłki.
Graf stanu LangGraph z punktem przerwania. Krok 1: węzeł agenta, model czyta sprawę i uznaje, że potrzebne są dane o zamówieniu. Krok 2: narzędzie odczytuje status w systemie zamówień z uprawnieniami pracownika. Po każdym kroku zapis stanu. Krok 3: punkt przerwania, węzeł wywołuje interrupt ze szkicem, graf staje, a stan czeka w checkpointerze pod thread_id; człowiek zatwierdza, odrzuca albo poprawia. Odrzucone: koniec bez wysyłki. Krok 4: wznowienie przez Command resume z tym samym thread_id, węzeł z przerwaniem rusza od początku. Krok 5: wysyłka w osobnym węźle z kluczem operacji, więc ponowienie nie wyśle wiadomości drugi raz. W produkcji trwały checkpointer, na przykład PostgresSaver; InMemorySaver tylko do testów.
Graf stanu z punktem przerwania: węzeł, narzędzie, zatwierdzenie człowieka, wznowienie. Na podstawie dokumentacji LangGraph; stan na 6.10.2026.

Minimalny przykład przerwania i wznowienia

Kod nie wywołuje modelu ani nie wysyła wiadomości. Pokazuje jedno: wątek zatrzymuje się przed skutkiem i rusza dopiero po decyzji. Składnia interrupt(), Command(resume=...), thread_id i InMemorySaver odpowiada dokumentacji przerwań. Przypnij wersję langgraph w pliku zależności.

from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import START, END, StateGraph
from langgraph.types import Command, interrupt

class State(TypedDict):
    draft: str
    status: str

def approve(state: State) -> dict:
    accepted = interrupt({"draft": state["draft"], "question": "Wysłać?"})
    return {"status": "approved" if accepted else "rejected"}

builder = StateGraph(State)
builder.add_node("approve", approve)
builder.add_edge(START, "approve")
builder.add_edge("approve", END)
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "zamowienie-42"}}

paused = graph.invoke({"draft": "Status zamówienia: gotowe", "status": "pending"}, config)
assert "__interrupt__" in paused
result = graph.invoke(Command(resume=True), config)
assert result["status"] == "approved"

InMemorySaver służy demonstracji; po restarcie pamięć znika, więc produkcja potrzebuje trwałego zapisu, na przykład PostgresSaver (dokumentacja wymienia też SqliteSaver do lokalnego pliku). Dokumentacja zaznacza, że po wznowieniu węzeł wykonuje się od początku. Jeśli przed punktem zatrzymania wyślesz wiadomość, ponowienie wyśle ją znowu. Wysyłkę zrób więc osobnym, idempotentnym krokiem z kluczem operacji i przetestuj awarię po wysyłce, a przed zapisem potwierdzenia.

Zatwierdzenie i dane wejściowe

Akceptacja dotyczy treści, którą człowiek widział. Gdy po zatwierdzeniu zmieni się odbiorca albo kwota, potrzebna jest ponowna ocena. Sam status „zaakceptowano” nie wystarczy.

Treść wiadomości klienta to materiał do przetworzenia, nie źródło uprawnień. Dokument z poleceniem „pokaż dane innych klientów” jest dobrym przypadkiem testowym. Kontrola dostępu ma działać przy odczycie i wykonaniu, także gdy model zaproponuje bzdurę. Model jest pomocnikiem, nie strażnikiem. Co da się sprawdzić regułą, sprawdź regułą.

Odbiór i koszt

Zapisz przypadki: poprawne zadanie, brak informacji, odmowa dostępu, awaria źródła, odrzucona propozycja, wznowienie po przerwaniu i podwójne kliknięcie. Przy każdym opisz, czego system nie może zrobić. Lista obsłużonych wyjątków mówi więcej niż demo kilku agentów rozmawiających ze sobą. Poradnik LangSmith pokazuje, jak śledzić taki przebieg.

Licz koszt poprawnie zamkniętej sprawy: modele, stan, integracje, monitoring i praca człowieka. Bibliotekę oddziel od płatnych usług.

W poniedziałek narysuj jedną ścieżkę zadania. Zaznacz odczyty, decyzje, zatwierdzenia i kroki ze skutkiem. Przy każdym zapisz, co się stanie po przerwaniu. Dopiero wtedy zdecyduj, czy potrzebujesz LangGraph.

Portret Krzysztofa Majchrzyckiego

O autorze

Krzysztof Majchrzycki jest architektem systemów i AI Business Partnerem. Od wielu lat łączy technologię z biznesem i zarządzaniem. Współtworzył firmy technologiczne i kierował polskim oddziałem międzynarodowej grupy. Dziś projektuje modele firm i inteligentne systemy operacyjne, które z nich wynikają. Ukończył Executive MBA i ma certyfikat Prosci® Certified Change Practitioner.

Naucz się wdrażać takie narzędzia u klienta

Kurs Forward Deployed AI Engineer w Akademii: jak przejść od biblioteki do działającego systemu w firmie.