Pierwszy Agent w LangGraph: Kompletny Tutorial Krok po Kroku (Python)

Pierwszy Agent w LangGraph: Kompletny Tutorial Krok po Kroku (Python)

W 2024 roku, według raportu McKinsey, firmy, które aktywnie wdrażają rozwiązania AI, odnotowują średnio o 15% wyższą produktywność w porównaniu do tych, które tego nie robią. Jednak budowa zaawansowanych aplikacji AI, zdolnych do złożonego rozumowania i autonomicznego podejmowania decyzji, bywa wyzwaniem. Tradycyjne podejścia często prowadzą do spaghetti-kodu i trudności w zarządzaniu przepływem informacji. Właśnie tutaj z pomocą przychodzi LangGraph – biblioteka oparta na LangChain, która pozwala na budowanie agentów AI w sposób deklaratywny, wykorzystując grafy stanów. Przejdziemy przez cały proces stworzenia prostego, ale w pełni funkcjonalnego agenta, zdolnego do interakcji z użytkownikiem i wykorzystywania zewnętrznych narzędzi, krok po kroku.

Wiele polskich startupów i średnich przedsiębiorstw stoi przed dylematem, jak skalować swoje procesy bez drastycznego zwiększania zatrudnienia. Wykorzystanie agentów AI, potrafiących np. automatycznie analizować dane rynkowe, generować raporty, czy odpowiadać na zapytania klientów, staje się realnym rozwiązaniem. W tym artykule skupimy się na praktycznym aspekcie tworzenia takich agentów, począwszy od instalacji niezbędnych pakietów, aż po uruchomienie i testowanie pierwszego, autonomicznego systemu.

Kluczowe wnioski

• LangGraph to rozszerzenie LangChain umożliwiające deklaratywne budowanie agentów AI za pomocą grafów stanów.
• Agenty AI w LangGraph mogą autonomicznie podejmować decyzje, używać narzędzi i iterować nad problemami.
• Podstawowe elementy LangGraph to stan grafu, węzły (LLM, narzędzia, logika) i krawędzie (przejścia warunkowe).
• Praktyczne zastosowanie agentów obejmuje automatyzację obsługi klienta, analizę danych i dynamiczne zarządzanie projektami.
• Zrozumienie LangGraph pozwala tworzyć stabilne, skalowalne i łatwe w debugowaniu systemy AI.
• Wdrożenie agentów wymaga zwrócenia uwagi na bezpieczeństwo danych i zgodność z regulacjami, takimi jak AI Act.

Czym jest LangGraph i dlaczego go potrzebujemy?

LangGraph to biblioteka, która rozszerza możliwości LangChain, koncentrując się na budowaniu aplikacji multi-agentowych w oparciu o grafy stanów. Wyobraź sobie, że chcesz stworzyć system AI, który nie tylko odpowiada na pytania, ale także potrafi: wyszukać informacje w internecie, przetworzyć je, a następnie, na podstawie wyników, podjąć decyzję, czy potrzebuje dalszych danych, czy już może sformułować odpowiedź. Taki cykl myślowy, z pętlami i warunkowymi przejściami, jest trudny do zaimplementowania w tradycyjnym modelu „łańcuchów” LangChain.

LangGraph rozwiązuje ten problem, pozwalając na deklaratywne definiowanie logiki w postaci grafu. Każdy węzeł w grafie reprezentuje konkretną akcję (np. wywołanie modelu językowego, użycie narzędzia, wykonanie kodu Pythona), a krawędzie określają, jak system przechodzi między węzłami, często w oparciu o warunki. Dzięki temu agenty mogą:

• Autonomicznie podejmować decyzje: Agent sam decyduje, jakie narzędzie wykorzystać lub którą ścieżkę w grafie obrać.
• Prowadzić konwersacje z pamięcią: Graf stanu może przechowywać historię rozmowy i inne istotne zmienne.
• Iterować i poprawiać: Agenty mogą wracać do poprzednich kroków, analizować wyniki i próbować ponownie, jeśli początkowa próba się nie powiodła.

To narzędzie staje się szczególnie użyteczne, gdy budujesz złożone systemy, które wymagają czegoś więcej niż prostej sekwencji operacji. Myśl o nim jak o schemacie blokowym dla Twojej aplikacji AI, gdzie każdy blok to funkcja, a strzałki to logika decyzyjna. Dla firm, które chcą rozwijać zaawansowane aplikacje oparte na danych, LangGraph oferuje stabilną i przewidywalną architekturę.

Przygotowanie środowiska deweloperskiego

Zanim zaczniemy budować naszego agenta, musimy zadbać o odpowiednie środowisko. Będziemy potrzebować Pythona w wersji 3.9+ oraz kilku kluczowych bibliotek. Upewnij się, że masz zainstalowany pip.

Instalacja niezbędnych pakietów

Otwórz terminal lub wiersz poleceń i wykonaj następujące komendy:

pip install langchain_core langchain_openai langgraph 'langchain-community[tooling]'

• langchain_core: Podstawowe komponenty LangChain, takie jak interfejsy modeli językowych, schematy danych.
• langchain_openai: Integracja z modelami OpenAI (GPT-3.5, GPT-4). Jeśli chcesz użyć innego modelu, zainstaluj odpowiedni pakiet (np. langchain_google_genai dla Gemini). Warto też rozważyć pakiet ChatGPT, Claude, Gemini, DeepSeek AI Premium 30 dni bez limitów, aby mieć dostęp do szerokiej gamy modeli i testować ich wydajność w różnych scenariuszach.
• langgraph: Główna biblioteka do budowania grafów stanów.
• langchain-community[tooling]: Zawiera narzędzia (tools) takie jak wyszukiwarki internetowe, kalkulatory itp.

Konfiguracja kluczy API

Będziemy potrzebować kluczy API do usług, z których będziemy korzystać. W naszym przykładzie będzie to klucz OpenAI API do modelu językowego oraz klucz Tavily API do wyszukiwania w internecie. Tavily to świetna alternatywa dla Google Search API, często oferująca lepsze wyniki w kontekście RAG i agentów.

Najlepszą praktyką jest przechowywanie kluczy API w zmiennych środowiskowych. Możesz to zrobić, tworząc plik .env w katalogu głównym projektu lub eksportując zmienne bezpośrednio w terminalu.

Przykład pliku .env:

OPENAI_API_KEY="twoj_klucz_openai_tutaj"
TAVILY_API_KEY="twoj_klucz_tavily_tutaj"

Aby załadować te zmienne w Pythonie, użyjemy biblioteki python-dotenv:

pip install python-dotenv

Następnie w kodzie Pythona:

import os
from dotenv import load_dotenv

load_dotenv()

openai_api_key = os.getenv("OPENAI_API_KEY")
tavily_api_key = os.getenv("TAVILY_API_KEY")

if not openai_api_key or not tavily_api_key:
    raise ValueError("Pamiętaj, aby ustawić OPENAI_API_KEY i TAVILY_API_KEY w zmiennych środowiskowych lub pliku .env")

Podstawy LangGraph: Grafy, Węzły i Krawędzie

Zanim przejdziemy do kodu, wyjaśnijmy kluczowe koncepcje LangGraph:

• State (Stan): Reprezentuje aktualny kontekst lub dane, które przepływają przez graf. W naszym przypadku będzie to historia rozmowy, wyniki wyszukiwania itp. Stan jest mutowany (zmieniany) przez węzły.
• Nodes (Węzły): Funkcje lub komponenty, które przyjmują stan jako wejście i zwracają zaktualizowany stan. Węzły mogą być modelem językowym (LLM), narzędziem (Tool) lub dowolną funkcją Pythona realizującą logikę biznesową.
• Edges (Krawędzie): Definiują przepływ kontroli między węzłami. Krawędzie mogą być:
  • Proste (Start/End): Określają początek i koniec grafu.
  • Sekwencyjne: Od węzła A do węzła B.
  • Warunkowe: Od węzła A do węzła B lub C, w zależności od wyniku funkcji decyzyjnej. To serce elastyczności LangGraph.

Rozumiejąc te elementy, możemy wizualizować naszego agenta jako maszynę stanów, gdzie w każdym kroku agent wykonuje akcję i decyduje, co robić dalej na podstawie aktualnego stanu i wyniku poprzedniej akcji. To podejście jest znacznie bardziej odporne na błędy i elastyczne niż proste łańcuchy, szczególnie w scenariuszach, gdzie potrzebne jest dynamiczne planowanie i samokorekta, jak na przykład w przypadku chatbotów RAG na własnych danych, gdzie złożona logika odzyskiwania i generowania odpowiedzi jest kluczowa.

Budowa pierwszego agenta w LangGraph: Krok po kroku

Zbudujemy agenta, który potrafi odpowiadać na pytania, a jeśli uzna to za konieczne, użyć wyszukiwarki internetowej, aby zdobyć dodatkowe informacje. Będzie to podstawowy, ale ilustrujący przykład działania pętli decyzyjnej.

1. Definiowanie stanu grafu

Stan to centralne miejsce, gdzie przechowywane są wszystkie dane potrzebne agentowi. Definiujemy go jako słownik Pythona, gdzie kluczem jest nazwa zmiennej, a wartością jest typ danych i sposób jej aktualizacji. TypedDict z modułu typing jest idealny do tego celu.

from typing import TypedDict, Annotated, List, Union
from langchain_core.agents import AgentAction, AgentFinish
from langchain_core.messages import BaseMessage

class AgentState(TypedDict):
    chat_history: Annotated[List[BaseMessage], lambda x, y: x + y] # Lista wiadomości, append
    intermediate_steps: Annotated[List[tuple[AgentAction, str]], lambda x, y: x + y] # Wyniki narzędzi, append
    question: str # Aktualne pytanie użytkownika

• chat_history: Lista obiektów BaseMessage (wiadomości od użytkownika i AI), które będą tworzyć kontekst konwersacji. Annotated z funkcją lambda x + y oznacza, że nowe wiadomości będą dodawane do istniejącej listy.
• intermediate_steps: Lista krotek przechowujących akcje podjęte przez agenta (np. wywołanie narzędzia) i ich obserwacje (wyniki). Jest to kluczowe do śledzenia logiki agenta.
• question: Aktualne pytanie, które agent próbuje rozwiązać.

2. Tworzenie narzędzi (Tools)

Narzędzia to funkcje, które agent może wywołać, aby wykonać specyficzne zadania, takie jak wyszukiwanie w internecie, obliczenia, dostęp do baz danych itp. Użyjemy narzędzia TavilySearchResults do wyszukiwania w internecie.

from langchain_community.tools.tavily_research import TavilySearchResults

# Inicjalizacja narzędzi
search_tool = TavilySearchResults(max_results=3) # Pobierz 3 najlepsze wyniki
tools = [search_tool]

Możesz tworzyć również własne narzędzia, opakowując dowolną funkcję Pythona w dekorator @tool z langchain_core.tools. Na przykład, jeśli prowadzisz firmę logistyczną i chcesz, aby agent sprawdzał status przesyłek, mógłbyś stworzyć narzędzie check_shipment_status.

3. Inicjalizacja modelu językowego (LLM)

Do naszego agenta potrzebujemy potężnego modelu językowego, który będzie pełnił rolę „mózgu” – będzie rozumiał intencje użytkownika, decydował o użyciu narzędzi i generował odpowiedzi. Użyjemy ChatOpenAI. Jeśli potrzebujesz bardziej zaawansowanych możliwości, rozważ konto Claude Max X5 na 30 dni, który często wyróżnia się w złożonych zadaniach rozumowania i długich kontekstach.

from langchain_openai import ChatOpenAI

# Inicjalizacja modelu językowego
llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key=openai_api_key)

4. Implementacja węzłów (Nodes)

Teraz zdefiniujemy funkcje, które będą działać jako węzły w naszym grafie. Każda funkcja przyjmuje AgentState i zwraca słownik, który zostanie użyty do aktualizacji stanu.

Węzeł 1: Wywołanie modelu językowego (Agent)

Ten węzeł będzie odpowiedzialny za interakcję z modelem LLM. Agent będzie decydował, czy potrzebuje narzędzia, czy też może już zakończyć działanie.

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.messages import AIMessage, HumanMessage

# Tworzenie promptu dla agenta
# Prompt instruuje model, aby używał narzędzi, jeśli potrzebuje dodatkowych informacji.
# Prompt zawiera również historię rozmowy i dotychczasowe kroki pośrednie.
prompt = ChatPromptTemplate.from_messages([
    ("system", "Jesteś pomocnym asystentem AI. Używaj narzędzi, aby odpowiadać na pytania. Odpowiadaj po polsku."),
    ("placeholder", "{chat_history}"),
    ("human", "{question}"),
    ("placeholder", "{intermediate_steps}")
])

# Łączenie LLM z narzędziami poprzez bind_tools
# To jest kluczowe, aby LLM wiedział, jakie narzędzia ma do dyspozycji i jak ich używać.
llm_with_tools = llm.bind_tools(tools)

def call_agent(state: AgentState):
    messages = state["chat_history"] + [HumanMessage(content=state["question"])]
    
    # Dodanie kroków pośrednich do wiadomości dla LLM
    for action, observation in state["intermediate_steps"]:
        messages.append(AIMessage(content=f"Wywołałem narzędzie {action.tool} z argumentami {action.tool_input}. Wynik: {observation}"))

    # Wywołanie LLM z promptem i narzędziami
    response = llm_with_tools.invoke(messages)
    
    return {"chat_history": [response]}

Tutaj wykorzystujemy bind_tools z LangChain, aby