LangGraph ile AI Agent Yapımı: Python Rehberi (2026)

LangGraph, Python’da durum taşıyan (stateful) AI agent’lar inşa etmek için geliştirilmiş bir framework. Tek seferlik LLM çağrısı değil, gerçek döngüler ve koşullu akışlar içeren agent’lar kurmak istiyorsanız işe yarayan araç bu. Bu rehberde kurulumdan çalışan bir projeye kadar her adımı geçeceğiz; kod blokları kopyala-yapıştır kullanıma hazır.

LangGraph’ın ne olduğunu ilk kez duyuyorsanız detaylı nedir yazısına göz atabilirsiniz. Aşağıda yalnızca farka değinip hemen koda geçiyoruz.

LangGraph Neden Gerekli?

Birçok otomasyon görevi tek bir LLM çağrısıyla bitmez. “Şu soruyu araştır, sonucu analiz et, yetersizse tekrar araştır” gibi bir akış için döngü ve karar noktası gerekiyor. LangChain Expression Language (LCEL) bu tür döngüleri desteklemiyor; her çağrı bağımsız bir zincir adımı.

LangGraph bunu çözmek için akışı bir graf olarak modelliyor. Her adım bir node, geçiş bir edge. State tek bir nesnede tutuluyor, her node bu state’i okuyup güncelleyebiliyor. Döngü kurmak için bir edge’i önceki node’a bağlamak yeterli.

LangGraph özellikle şu durumlarda işe yarıyor:

• Döngü gerektiren akışlar: “Yeterince iyi değil, tekrar dene” mantığı.
• Koşullu yönlendirme: sonuca göre farklı yol izleme.
• Çok adımlı hafıza: konuşma boyunca biriken veriler.
• Araç orkestrasyonu: LLM araç çağırıyor, sonucu işliyor, devam ediyor.

Farklı framework’lerin ne yaptığını karşılaştırmalı görmek için agent framework karşılaştırma rehberine bakabilirsiniz.

Kurulum ve Ortam Hazırlama

Python 3.10 veya üstü gerekiyor. Sanal ortam kullanmak bağımlılık sorunlarını önler.

python -m venv langgraph-env
source langgraph-env/bin/activate
# Windows: langgraph-env\Scripts\activate

Gerekli paketleri yükleyin:

pip install langgraph langchain-openai langchain-community tavily-python python-dotenv

Anthropic modeli tercih ederseniz langchain-openai yerine langchain-anthropic kurun; kod yapısı aynı kalıyor, yalnızca import ve model sınıfı değişiyor.

API anahtarlarını .env dosyasına ekleyin:

OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...

Kodda bu değerleri yüklemek için:

from dotenv import load_dotenv
load_dotenv()

StateGraph: Temel Yapı Taşları

LangGraph’ın özü StateGraph. Bir grafik tanımlıyorsunuz, node’lar ekliyorsunuz, aralarına edge’ler çekiyorsunuz.

State her şeyin döndüğü merkez. TypedDict ile tanımlanıyor:

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

Annotated[list, add_messages] burada kritik: her yeni mesaj listeyi sıfırlamak yerine biriktiriyor. Konuşma geçmişi bu yapıyla otomatik korunuyor.

Node bir Python fonksiyonu. State alıyor, state döndürüyor:

def my_node(state: State) -> dict:
    # state'i oku, bir şeyler yap
    return {"messages": [...]}

Edge iki node arasındaki bağlantı. Basit edge her koşulda aynı node’a gidiyor. Koşullu edge ise bir fonksiyonun döndürdüğü değere bakıyor.

START ve END grafın girişini ve çıkışını işaret eden built-in node’lar; bunları ayrıca tanımlamanıza gerek yok.

Graf derlenmeden önce geçerlilik kontrolü yapılmıyor. compile() çağrısından sonra da bazı hatalar yalnızca .invoke() sırasında yüzey çıkıyor. Bu yüzden geliştirme aşamasında print_ascii() ile grafiği görselleştirmek, olası bağlantı hatalarını erken yakalamak için işe yarıyor.

İlk Agent: Çalışan Bir Örnek

Aşağıdaki kod OpenAI model kullanan minimal bir agent. Kullanıcı mesajı alıyor, LLM’e gönderiyor, yanıtı döndürüyor:

from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

model = ChatOpenAI(model="gpt-4o-mini")

def agent_node(state: State) -> dict:
    response = model.invoke(state["messages"])
    return {"messages": [response]}

# Graf inşası
graph_builder = StateGraph(State)
graph_builder.add_node("agent", agent_node)
graph_builder.add_edge(START, "agent")
graph_builder.add_edge("agent", END)

graph = graph_builder.compile()

Çalıştırmak için:

from langchain_core.messages import HumanMessage

result = graph.invoke({
    "messages": [HumanMessage(content="Python'da liste nasıl sıralanır?")]
})
print(result["messages"][-1].content)

Graf derlendikten sonra .invoke() ile senkron, .astream() ile akış modunda kullanılabiliyor. Uzun çalışan agent’lar için .astream() her adımda token’ları döküyor; kullanıcıya anlık geri bildirim vermek istediğinizde .invoke() yerine bunu tercih edin.

Debug ipucu: Derlenmemiş graph_builder üzerinde .get_graph().print_ascii() çağırırsanız terminal’de grafiğin ASCII görseli çıkıyor. Hangi node’ların bağlandığını hızlıca doğrulamak için kullanışlı.

Conditional Routing: Döngü Kurmak

Gerçek agent mantığı burada başlıyor. Araç çağrısı döngüsü şu işi yapıyor: LLM araç mı kullandı diye kontrol ediyor, araçları çalıştırıyor, sonra tekrar LLM’e dönüyor.

def should_continue(state: State) -> str:
    last_message = state["messages"][-1]
    # LLM araç çağırdıysa tools node'una, yoksa bitir
    if last_message.tool_calls:
        return "tools"
    return END

graph_builder.add_conditional_edges(
    "agent",
    should_continue,
    {"tools": "tools_node", END: END}
)

add_conditional_edges üç argüman alıyor: kaynak node, karar fonksiyonu, çıktı-hedef haritası. Fonksiyon string döndürüyor, harita o string’i ilgili node’a yönlendiriyor.

Bu yapıyla döngü kuruluyor: agent → tools → agent → tools → ... şeklinde LLM sonuca ulaştığına karar verene kadar devam ediyor.

Tool Entegrasyonu

LangGraph’ın ToolNode’u araç çalıştırmayı otomatikleştiriyor. Araç listesi veriyorsunuz, node gerisini hallediyor.

Tavily arama aracı için:

from langchain_community.tools.tavily_search import TavilySearchResults

search_tool = TavilySearchResults(max_results=3)
tools = [search_tool]

Özel araç eklemek için @tool decorator:

from langchain_core.tools import tool

@tool
def calculate(expression: str) -> str:
    """Matematiksel ifadeyi hesaplar."""
    try:
        return str(eval(expression))
    except Exception as e:
        return f"Hata: {e}"

tools = [search_tool, calculate]

Modeli araçlarla bağlayın:

model_with_tools = model.bind_tools(tools)

ToolNode oluşturun:

from langgraph.prebuilt import ToolNode

tools_node = ToolNode(tools)

ToolNode gelen araç çağrılarını otomatik çalıştırıyor ve sonuçları mesaj olarak state’e yazıyor. Araçları tek tek elle çağırmanıza gerek kalmıyor.

Tam Proje: Web Araştırma Ajanı

Aşağıda baştan sona çalışan, kopyala-yapıştır hazır bir araştırma agent’ı var:

import os
from dotenv import load_dotenv
from typing import Annotated
from typing_extensions import TypedDict

from langchain_openai import ChatOpenAI
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain_core.messages import HumanMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode

load_dotenv()

# State tanımı
class State(TypedDict):
    messages: Annotated[list, add_messages]

# Araçlar
search = TavilySearchResults(max_results=3)
tools = [search]

# Model
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
model_with_tools = model.bind_tools(tools)

# Node'lar
def agent_node(state: State) -> dict:
    response = model_with_tools.invoke(state["messages"])
    return {"messages": [response]}

tools_node = ToolNode(tools)

# Karar fonksiyonu
def should_continue(state: State) -> str:
    last = state["messages"][-1]
    if last.tool_calls:
        return "tools"
    return END

# Graf inşası
builder = StateGraph(State)
builder.add_node("agent", agent_node)
builder.add_node("tools", tools_node)

builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", should_continue)
builder.add_edge("tools", "agent")

graph = builder.compile()

# Çalıştır
if __name__ == "__main__":
    query = "2026'da en çok kullanılan açık kaynak LLM modelleri hangileri?"
    result = graph.invoke({"messages": [HumanMessage(content=query)]})
    print(result["messages"][-1].content)

Bu kod çalıştırıldığında agent önce Tavily ile arama yapıyor, sonuçları LLM’e gönderiyor, model sentezlenmiş bir yanıt üretiyor. Araç çağrısı gerektirmeyen sorularda doğrudan yanıt dönüyor.

Sık karşılaşılan hatalar:

• OPENAI_API_KEY veya TAVILY_API_KEY eksikse AuthenticationError veya ValueError alırsınız. .env dosyasının proje köküne konulduğunu kontrol edin.
• langchain_community paketi yüklü değilse TavilySearchResults için pip install langchain-community gerekiyor.
• gpt-4o-mini yerine Claude modeli kullanmak isterseniz langchain-anthropic kurun ve ChatAnthropic sınıfıyla değiştirin; akışın geri kalanı aynı kalıyor.

LangGraph mı, CrewAI mı?

Her iki framework da agent orkestrasyonu için kullanılıyor ama yaklaşımları farklı.

Kaynak: LangGraph resmi dokümantasyon ve CrewAI GitHub.

Tercih için pratik bir kural: karmaşık döngüler, koşullu akışlar ve üretim ortamında izleme gerektiren projelerde LangGraph daha uygun. Rol tabanlı, hızlı prototip ihtiyacı olan çok ajanlı kurulumlar için CrewAI daha kolay başlangıç noktası. İkisini birlikte kullananlar da var - LangGraph’ın tek agent döngüsünü CrewAI’ın rol yönetimiyle birleştiren mimariler mümkün ama karmaşıklığı artırıyor; iyi bir neden olmadan bu yola girmemek daha mantıklı. CrewAI rehberi için adım adım CrewAI yazısına bakabilirsiniz.

LangChain ile LangGraph arasındaki farkı merak ediyorsanız LangChain vs LangGraph karşılaştırması ek bağlam sunuyor.

Sonraki Adımlar

StateGraph, node/edge ve conditional routing’i öğrendikten sonra çalışan bir web araştırma ajanı kurdunuz. Buradan nereye gidileceğine dair birkaç yön:

• Paralel node’lar: fan-out/fan-in pattern ile aynı anda birden fazla araç çalıştırın.
• Kalıcı hafıza: MemorySaver checkpointer ile konuşmalar arası state’i koruyun.
• LangSmith izleme: her adımın logunu kayıt altına almak için birkaç satır ek kod gerekiyor.
• Çok ajanlı mimariler: supervisor pattern için sıfırdan AI agent yapımı yazısına bakın.

LangGraph hızla gelişen bir ekosistem; dokümantasyon sürekli güncelleniyor. Versiyon takibi için GitHub release sayfasını düzenli kontrol etmek iyi bir alışkanlık.