Kurs Python · Moduł 11: RAG i systemy wieloagentowe
LangGraph - Graph-Based Agent Workflows
W tej lekcji9
Łańcuch z poprzednich lekcji idzie zawsze w jedną stronę: badacz, analityk, pisarz, koniec. A co, jeśli pisarz musi odesłać pracę do badacza albo agent przed zakupem biletów powinien zapytać człowieka o zgodę? Prawdziwy szlak przez sawannę ma zawrócenia i rozwidlenia.
LangGraph to framework do budowania złożonych, stanowych aplikacji AI opartych na grafach. Pozwala tworzyć cykle, rozgałęzienia i zaawansowane przepływy sterowania dla agentów. Myśl o nim jak o mapie szlaków: węzły to obozy, krawędzie to ścieżki, a stan to plecak, który nosisz od obozu do obozu.
Czym jest LangGraph?
LangGraph rozszerza możliwości LangChain o:
- State Management - zarządzanie stanem między krokami
- Cycles - możliwość tworzenia pętli (w przeciwieństwie do DAG)
- Branching - warunkowe rozgałęzienia przepływu
- Human-in-the-loop - punkty wstrzymania dla interakcji z człowiekiem
Schemat pokazuje typowy graf agenta z narzędziami, w którym przepływ może wracać do agenta wiele razy:
┌─────────────────────────────────────────────────────────────┐
│ LangGraph Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ │
│ │ START │ │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ Agent │────▶│ Condition │ │
│ │ Node │ │ (Router) │ │
│ └──────────┘ └──────┬───────┘ │
│ ▲ │ │
│ │ ┌─────────┼─────────┐ │
│ │ ▼ ▼ ▼ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ │ Tool A │ │ Tool B │ │ END │ │
│ │ └───┬────┘ └───┬────┘ └────────┘ │
│ │ │ │ │
│ └───────┴──────────┘ │
│ (cycle back) │
│ │
└─────────────────────────────────────────────────────────────┘Agent decyduje, router wybiera ścieżkę do narzędzia albo do końca, a po użyciu narzędzia przepływ wraca do agenta.
Instalacja i podstawy
Najważniejszy element LangGraph to stan. Definiujemy go jako TypedDict, czyli słownik z opisanymi typami kluczy:
# pip install langgraph langchain-openai
from langgraph.graph import StateGraph, END
from langgraph.checkpoint.memory import MemorySaver
from typing import TypedDict, Annotated, Literal
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage
import operator
# Definicja stanu - kluczowy element LangGraph
class AgentState(TypedDict):
messages: Annotated[list, operator.add] # Lista wiadomości
current_step: str
iteration_count: int
# Model LLM
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)Annotated[list, operator.add] mówi LangGraph, jak łączyć aktualizacje: nowe wiadomości są doklejane do listy, a nie ją zastępują. Klucze bez adnotacji są nadpisywane. Dla czatu jest też gotowy reduktor add_messages z modułu langgraph.graph.message.
Podstawowy graf agenta
Budowa grafu ma zawsze tę samą kolejność: definicja stanu, StateGraph, węzły (add_node), krawędzie (add_edge) i kompilacja (compile). Zaczynamy od stanu i węzła agenta:
from langgraph.graph import StateGraph, START, END
# Definicja stanu
class State(TypedDict):
messages: Annotated[list, operator.add]
next_action: str
# Funkcje węzłów
def agent_node(state: State) -> State:
"""Węzeł agenta - podejmuje decyzje."""
messages = state["messages"]
response = llm.invoke(messages)
return {
"messages": [response],
"next_action": "tool" if response.tool_calls else "end"
}Węzeł to zwykła funkcja: dostaje stan, zwraca słownik z tymi kluczami, które chce zmienić. Żeby model w ogóle zwracał tool_calls, trzeba mu podpiąć narzędzia metodą llm.bind_tools(tools), inaczej lista będzie zawsze pusta.
Drugi węzeł wykonuje narzędzia, a router wybiera kolejny krok:
def tool_node(state: State) -> State:
"""Węzeł narzędzi - wykonuje akcje."""
last_message = state["messages"][-1]
# Wykonaj tool calls
tool_results = []
for tool_call in last_message.tool_calls:
result = execute_tool(tool_call)
tool_results.append(result)
return {"messages": tool_results, "next_action": "agent"}
def router(state: State) -> Literal["tool", "end"]:
"""Router - decyduje o następnym kroku."""
return state["next_action"]execute_tool to miejsce na Twoją logikę. W praktyce zastąpisz ten węzeł gotowym ToolNode z langgraph.prebuilt.
Teraz łączymy wszystko w graf:
# Budowa grafu
workflow = StateGraph(State)
# Dodaj węzły
workflow.add_node("agent", agent_node)
workflow.add_node("tool", tool_node)
# Dodaj krawędzie
workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
"agent",
router,
{
"tool": "tool",
"end": END
}
)
workflow.add_edge("tool", "agent") # Cykl z powrotem do agenta
# Kompilacja grafu
app = workflow.compile()
# Uruchomienie
result = app.invoke({
"messages": [HumanMessage(content="Jaka jest pogoda w Serengeti?")],
"next_action": ""
})add_conditional_edges pyta router o nazwę ścieżki i tłumaczy ją słownikiem na węzeł. Krawędź z "tool" z powrotem do "agent" tworzy cykl.
ReAct Agent z LangGraph
Ten wzorzec jest tak popularny, że istnieje gotowiec. Najpierw narzędzia z dekoratorem @tool, znanym z lekcji o systemach multi-agentowych:
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
# Definicja narzędzi
@tool
def get_weather(location: str) -> str:
"""Pobiera pogodę dla lokalizacji Safari."""
weather_data = {
"Serengeti": "28°C, słonecznie",
"Masai Mara": "25°C, pochmurnie",
"Kruger": "30°C, gorąco"
}
return weather_data.get(location, f"Brak danych dla {location}")
@tool
def search_animals(query: str) -> str:
"""Wyszukuje informacje o zwierzętach Safari."""
return f"Informacje o {query}: Fascynujące zwierzę afrykańskiej sawanny!"
@tool
def calculate_safari_cost(days: int, people: int) -> str:
"""Oblicza koszt Safari."""
cost_per_day = 200
total = days * people * cost_per_day
return f"Koszt Safari: {total} USD ({days} dni, {people} osoby)"Każde narzędzie ma docstring, który model czyta jako opis, i typy parametrów, które mówią mu, co podać.
create_react_agent buduje cały graf agent-narzędzia w jednej linijce:
# Tworzenie agenta ReAct
tools = [get_weather, search_animals, calculate_safari_cost]
react_agent = create_react_agent(llm, tools)
# Uruchomienie
result = react_agent.invoke({
"messages": [HumanMessage(content="Oblicz koszt 5-dniowego Safari dla 4 osób")]
})
print(result["messages"][-1].content)Model sam wywoła calculate_safari_cost z days=5 i people=4. Uwaga: w LangGraph 1.0 create_react_agent jest oznaczony jako deprecated, a nowy kod powinien używać create_agent z pakietu langchain.agents.
Multi-Agent z LangGraph
Graf świetnie nadaje się do zespołu agentów. Każdy agent to węzeł, a pole current_agent w stanie mówi, kto jest następny:
from langgraph.graph import StateGraph, START, END
from typing import Literal
class MultiAgentState(TypedDict):
messages: Annotated[list, operator.add]
current_agent: str
task_complete: bool
# Agenci specjaliści
def researcher_agent(state: MultiAgentState) -> MultiAgentState:
"""Agent badawczy - zbiera informacje."""
system_prompt = "Jesteś badaczem Safari. Zbieraj informacje o zwierzętach i lokalizacjach."
response = llm.invoke([
{"role": "system", "content": system_prompt},
*state["messages"]
])
return {
"messages": [AIMessage(content=f"[Researcher]: {response.content}")],
"current_agent": "analyzer"
}Badacz dopisuje swoją odpowiedź do messages i wskazuje analityka jako kolejnego.
Analityk i pisarz działają tak samo, tylko pisarz kończy pracę flagą task_complete:
def analyzer_agent(state: MultiAgentState) -> MultiAgentState:
"""Agent analityczny - analizuje dane."""
system_prompt = "Jesteś analitykiem. Analizuj zebrane informacje i wyciągaj wnioski."
response = llm.invoke([
{"role": "system", "content": system_prompt},
*state["messages"]
])
return {
"messages": [AIMessage(content=f"[Analyzer]: {response.content}")],
"current_agent": "writer"
}
def writer_agent(state: MultiAgentState) -> MultiAgentState:
"""Agent pisarski - tworzy końcowy raport."""
system_prompt = "Jesteś pisarzem. Stwórz angażujący raport na podstawie analizy."
response = llm.invoke([
{"role": "system", "content": system_prompt},
*state["messages"]
])
return {
"messages": [AIMessage(content=f"[Writer]: {response.content}")],
"current_agent": "end",
"task_complete": True
}Każdy agent widzi całą historię wiadomości, bo messages rośnie z każdym węzłem.
Pozostaje router i graf:
def router(state: MultiAgentState) -> Literal["analyzer", "writer", "end"]:
"""Router między agentami."""
return state["current_agent"]
# Budowa grafu multi-agent
multi_agent_graph = StateGraph(MultiAgentState)
multi_agent_graph.add_node("researcher", researcher_agent)
multi_agent_graph.add_node("analyzer", analyzer_agent)
multi_agent_graph.add_node("writer", writer_agent)
multi_agent_graph.add_edge(START, "researcher")
multi_agent_graph.add_conditional_edges(
"researcher",
router,
{"analyzer": "analyzer"}
)
multi_agent_graph.add_conditional_edges(
"analyzer",
router,
{"writer": "writer"}
)
multi_agent_graph.add_conditional_edges(
"writer",
router,
{"end": END}
)
multi_agent_app = multi_agent_graph.compile()
# Uruchomienie pipeline
result = multi_agent_app.invoke({
"messages": [HumanMessage(content="Przygotuj raport o lwach w Serengeti")],
"current_agent": "researcher",
"task_complete": False
})Kolejność jest liniowa, ale router pozwala łatwo dodać powrót do badacza.
Checkpointing i Persistence
Domyślnie graf zapomina wszystko po invoke. Checkpointer zapisuje stan po każdym kroku, co pozwala kontynuować konwersację:
from langgraph.checkpoint.memory import MemorySaver
from langgraph.checkpoint.sqlite import SqliteSaver # pip install langgraph-checkpoint-sqlite
import sqlite3
# Memory checkpoint (w pamięci)
memory_checkpointer = MemorySaver()
# SQLite checkpoint (trwały)
sqlite_checkpointer = SqliteSaver(sqlite3.connect("safari_agent.db", check_same_thread=False))
# Kompilacja z checkpointerem
app_with_memory = workflow.compile(checkpointer=memory_checkpointer)MemorySaver trzyma stan w pamięci i traci go przy restarcie. SqliteSaver z pakietu langgraph-checkpoint-sqlite zapisuje go w pliku bazy SQLite.
Rozmowy rozróżnia thread_id w konfiguracji:
# Uruchomienie z thread_id dla kontynuacji
config = {"configurable": {"thread_id": "safari-session-1"}}
# Pierwsza wiadomość
result1 = app_with_memory.invoke(
{"messages": [HumanMessage(content="Opowiedz mi o lwach")]},
config
)
# Kontynuacja rozmowy (ten sam thread_id)
result2 = app_with_memory.invoke(
{"messages": [HumanMessage(content="A co z ich polowaniami?")]},
config
)
# Historia jest zachowana!
print(result2["messages"])Drugie wywołanie z tym samym thread_id widzi pierwszą wiadomość, więc model wie, że "ich" oznacza lwy.
Human-in-the-loop
Niektórych decyzji agent nie powinien podejmować sam. Najpierw stan, węzły i router:
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
class HumanLoopState(TypedDict):
messages: Annotated[list, operator.add]
needs_approval: bool
approved: bool
def agent_node(state: HumanLoopState) -> HumanLoopState:
"""Agent proponuje akcję."""
response = llm.invoke(state["messages"])
# Sprawdź czy akcja wymaga zatwierdzenia
needs_approval = "delete" in response.content.lower() or "buy" in response.content.lower()
return {
"messages": [response],
"needs_approval": needs_approval
}
def human_approval_node(state: HumanLoopState) -> HumanLoopState:
"""Punkt zatwierdzenia przez człowieka."""
# Ten węzeł zatrzymuje wykonanie
# Użytkownik musi zatwierdzić przed kontynuacją
return {"approved": state.get("approved", False)}
def execute_node(state: HumanLoopState) -> HumanLoopState:
"""Wykonuje zatwierdzoną akcję."""
return {"messages": [AIMessage(content="Akcja wykonana!")]}
def approval_router(state: HumanLoopState) -> Literal["human", "execute", "end"]:
"""Router sprawdzający czy potrzeba zatwierdzenia."""
if state.get("needs_approval") and not state.get("approved"):
return "human"
elif state.get("approved"):
return "execute"
return "end"Węzeł human niczego nie liczy, jest tylko miejscem postoju. Zwraca jeden klucz bez zmian, bo zwrócenie całego stanu dokleiłoby wszystkie wiadomości drugi raz przez reduktor operator.add.
Kompilujemy graf z checkpointerem i interrupt_before:
# Graf z human-in-the-loop
human_loop_graph = StateGraph(HumanLoopState)
human_loop_graph.add_node("agent", agent_node)
human_loop_graph.add_node("human", human_approval_node)
human_loop_graph.add_node("execute", execute_node)
human_loop_graph.add_edge(START, "agent")
human_loop_graph.add_conditional_edges(
"agent",
approval_router,
{"human": "human", "execute": "execute", "end": END}
)
human_loop_graph.add_edge("human", "agent") # Po zatwierdzeniu wróć do agenta
human_loop_graph.add_edge("execute", END)
# Kompilacja z interrupt_before dla human node
app = human_loop_graph.compile(
checkpointer=MemorySaver(),
interrupt_before=["human"] # Zatrzymaj przed human node
)Router zwraca "end", dlatego słownik ścieżek tłumaczy tę nazwę na END. Bez niego LangGraph zgłosi błąd nieznanego węzła end.
Uruchomienie zatrzymuje się przed węzłem human, a my zatwierdzamy i wznawiamy:
# Uruchomienie - zatrzyma się przed human node
config = {"configurable": {"thread_id": "approval-1"}}
result = app.invoke(
{"messages": [HumanMessage(content="Usuń wszystkie pliki")]},
config
)
# Sprawdź stan
state = app.get_state(config)
print(f"Needs approval: {state.values.get('needs_approval')}")
# Użytkownik zatwierdza
app.update_state(config, {"approved": True})
# Kontynuuj wykonanie
final_result = app.invoke(None, config)update_state zapisuje zgodę, a invoke(None, config) wznawia graf i router kieruje przepływ do execute. W nowszych wersjach wygodniejsza jest funkcja interrupt() wywoływana wewnątrz węzła.
Branching i Parallel Execution
Dwie niezależne gałęzie mogą działać jednocześnie. Najpierw funkcje węzłów:
from langgraph.graph import StateGraph, START, END
from typing import Literal
class ParallelState(TypedDict):
query: str
weather_result: str
animal_result: str
combined_result: str
def weather_branch(state: ParallelState) -> ParallelState:
"""Pobiera pogodę równolegle."""
# Symulacja wywołania API
return {"weather_result": "Pogoda: 28°C, słonecznie"}
def animal_branch(state: ParallelState) -> ParallelState:
"""Pobiera info o zwierzętach równolegle."""
return {"animal_result": "Zwierzęta: Lwy, słonie, żyrafy"}
def combine_results(state: ParallelState) -> ParallelState:
"""Łączy wyniki z równoległych gałęzi."""
combined = f"{state['weather_result']}. {state['animal_result']}"
return {"combined_result": combined}Każda gałąź zapisuje inny klucz stanu, więc nie ma konfliktu.
Dwie krawędzie z START rozgałęziają przepływ:
# Graf z równoległym wykonaniem
parallel_graph = StateGraph(ParallelState)
parallel_graph.add_node("weather", weather_branch)
parallel_graph.add_node("animals", animal_branch)
parallel_graph.add_node("combine", combine_results)
# Równoległe krawędzie
parallel_graph.add_edge(START, "weather")
parallel_graph.add_edge(START, "animals")
parallel_graph.add_edge("weather", "combine")
parallel_graph.add_edge("animals", "combine")
parallel_graph.add_edge("combine", END)
parallel_app = parallel_graph.compile()
result = parallel_app.invoke({"query": "Safari info"})
print(result["combined_result"])weather i animals wykonują się w tym samym kroku, a combine rusza dopiero, gdy obie skończą.
Supervisor Pattern
W tym wzorcu jeden agent zarządza resztą. Supervisor pyta model, kto ma pracować:
from langgraph.graph import StateGraph, START, END
from typing import Literal
class SupervisorState(TypedDict):
messages: Annotated[list, operator.add]
next_worker: str
completed_workers: list[str]
def supervisor_node(state: SupervisorState) -> SupervisorState:
"""Supervisor decyduje który worker ma działać."""
system_prompt = """Jesteś supervisorem zarządzającym zespołem:
- researcher: zbiera informacje
- analyst: analizuje dane
- writer: tworzy raporty
Na podstawie zadania i dotychczasowych wyników, wybierz następnego workera.
Odpowiedz TYLKO nazwą workera lub 'FINISH' jeśli zadanie ukończone."""
completed = state.get("completed_workers", [])
response = llm.invoke([
{"role": "system", "content": system_prompt},
{"role": "user", "content": f"Completed: {completed}\nTask: {state['messages'][-1].content}"}
])
next_worker = response.content.strip().lower()
return {"next_worker": next_worker}Supervisor zwraca tylko nazwę kolejnego workera.
Fabryka tworzy węzły workerów, a router tłumaczy decyzję:
def worker_node(worker_name: str):
"""Fabryka węzłów workerów."""
def node(state: SupervisorState) -> SupervisorState:
prompts = {
"researcher": "Jesteś badaczem. Zbierz informacje.",
"analyst": "Jesteś analitykiem. Przeanalizuj dane.",
"writer": "Jesteś pisarzem. Napisz raport."
}
response = llm.invoke([
{"role": "system", "content": prompts[worker_name]},
*state["messages"]
])
completed = state.get("completed_workers", []) + [worker_name]
return {
"messages": [AIMessage(content=f"[{worker_name}]: {response.content}")],
"completed_workers": completed
}
return node
def supervisor_router(state: SupervisorState) -> Literal["researcher", "analyst", "writer", "end"]:
"""Router supervisora."""
next_worker = state.get("next_worker", "").lower()
if next_worker == "finish" or next_worker == "end":
return "end"
return next_workerJeśli model odpowie czymś spoza listy, router zwróci nieznaną nazwę i graf się wysypie, dlatego w produkcji wymuś format odpowiedzi.
Każdy worker oddaje sterowanie supervisorowi:
# Budowa grafu supervisora
supervisor_graph = StateGraph(SupervisorState)
supervisor_graph.add_node("supervisor", supervisor_node)
supervisor_graph.add_node("researcher", worker_node("researcher"))
supervisor_graph.add_node("analyst", worker_node("analyst"))
supervisor_graph.add_node("writer", worker_node("writer"))
supervisor_graph.add_edge(START, "supervisor")
# Wszystkie krawędzie prowadzą z powrotem do supervisora
for worker in ["researcher", "analyst", "writer"]:
supervisor_graph.add_edge(worker, "supervisor")
supervisor_graph.add_conditional_edges(
"supervisor",
supervisor_router,
{
"researcher": "researcher",
"analyst": "analyst",
"writer": "writer",
"end": END
}
)
supervisor_app = supervisor_graph.compile()
# Uruchomienie
result = supervisor_app.invoke({
"messages": [HumanMessage(content="Przygotuj kompletny raport o Safari w Serengeti")],
"completed_workers": []
})Polecam zaczynać od grafu liniowego, a cykle i supervisora dodawać, gdy naprawdę potrzebujesz decyzji w trakcie.
LangGraph to potężne narzędzie do budowania złożonych przepływów AI. W następnej lekcji poznasz subagentów i hierarchie agentów!
Zapamiętaj: LangGraph to mapa szlaków, na której wolno zawrócić, rozdzielić się i poczekać na decyzję przewodnika.
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Czym jest LangGraph?
2. Co umożliwia LangGraph w porównaniu do standardowych chainów?
To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Układanie w poziomie
Ułóż elementy:
- Układanie w pionie
Ułóż kroki budowania grafu w LangGraph:
- Edytor kodu
Zdefiniuj klasę State z TypedDict i Annotated dla messages.
- Klikanie w kolejności
Ułóż tworzenie węzła w LangGraph:
- Edytor kodu
Zaimplementuj graf z researcher, analyzer i writer agentami.