LangGraph Nedir? Stateful AI Agent Geliştirme

LangChain ile basit zincir kurmak hızlıydı. Ama iş üretim ortamına gelince tablo değişiyordu: gerçek kullanıcılar, gerçek hatalar, saatlerce süren görevler. Döngü gerekince ne yaparsınız? Orta yolda çöken bir pipeline’ı baştan mı çalıştırırsınız? Kritik bir adımı insana onaylatmak istiyorsanız nasıl yaparsınız?

LangGraph bu soruları graph-tabanlı state machine mantığıyla yanıtlıyor. İş akışı doğrusal bir bant değil; düğümler ve kenarlardan oluşan bir çizge. Fark küçük görünse de production ölçeğinde neyi inşa edebileceğinizi köklü biçimde değiştiriyor.

LangGraph nedir?

LangGraph, LangChain ekibinin 2024’te geliştirdiği bir Python çerçevesi. Adındaki “Graph” tesadüf değil: iş akışını yönlü bir çizge (directed graph) olarak modelliyor. Her düğüm bir hesaplama adımı, her kenar düğümler arası geçiş.

LangChain Expression Language (LCEL) doğrusal zincirler için tasarlanmıştı: düğüm A bitti, düğüm B başlasın. LangGraph’ta döngüler birinci sınıf vatandaş. Düğüm A’dan B’ye gidebilir, oradan tekrar A’ya dönebilirsiniz. Kendi kendini düzelten agentlar ve uzun süreli görevler için bu ayrım belirleyici.

LangGraph bugün üretim kalitesinde AI agent geliştirmenin en yaygın araçlarından biri; LangChain belgeleri “agentlar için önerilen yol” olarak sunuyor.

Neden bu kadar ilgi gördüğü anlaşılır. Tek seferlik LLM çağrıları giderek yetersiz kalıyor: birden fazla araç, dış servis ve belirsizlik içeren görevler; uzun zaman alan ve ara verilen iş akışları; kullanıcıyla etkileşimli devam eden süreçler. Bunların hepsi grafiği doğal bir çerçeve haline getiriyor. Uzun süreli görevlerde durumu koruyabilmek, akışı belirli bir noktada durdurabilmek ve kaldığı yerden sürdürebilmek kolaylık değil, zorunluluk.

Temel kavramlar

Dört yapı taşını kavramak yeterli:

StateGraph tüm iş akışını tanımlayan çerçeve. Grafiğin state’ini, düğümlerini ve kenarlarını burada bildirirsiniz.

State TypedDict ile tanımlanan veri yapısı. Her düğüm bu state’i okur, güncellenmiş halini döndürür. Düğümler arası bilgi akışının tek kanalı bu.

from typing import TypedDict, Annotated
import operator

class AgentState(TypedDict):
    mesajlar: Annotated[list, operator.add]  # her düğüm listeye ekler
    sonraki_adim: str

Node (düğüm) bir Python fonksiyonu. State alır, state döndürür. LLM çağrısı yapabilir, bir API’ye istek atabilir, hesaplama yapabilir. Tek kısıtlama: girdi de çıktı da aynı State şemasına uymalı.

Edge (kenar) düğümler arası geçiş. Normal kenar her zaman izlenir; conditional kenar state’e göre hedefi dinamik belirler. Döngü ve dallanma mantığı bu ikinci türden geliyor.

from langgraph.graph import StateGraph, END

graph = StateGraph(AgentState)

# Düğümler ekle
graph.add_node("dusun", dusun_fonksiyonu)
graph.add_node("arac_cagir", arac_fonksiyonu)

# Normal kenar: araç bitti, düşünmeye dön
graph.add_edge("arac_cagir", "dusun")

# Conditional kenar: state'e göre karar
graph.add_conditional_edges(
    "dusun",
    karar_ver,  # "arac_cagir" veya END döndürür
    {"arac_cagir": "arac_cagir", END: END}
)

Bu kod iki şeyi açıkça görünür kılıyor: iş akışının tüm mantığı grafikte, fonksiyonların içine gömülü değil. dusun düğümü ne yaptığını biliyor ama nereye gideceğini bilmiyor; geçiş kararı koşullu kenara devredilmiş. Bu ayrışma testleri önemli ölçüde kolaylaştırıyor: dusun fonksiyonunu sahte bir state ile çalıştırıp sonucunu izole edebilirsiniz, grafik yürütücüsüne gerek kalmadan.

Conditional kenarlar LangGraph’ın asıl gücünü burada taşıyor. Döngü, yeniden deneme ve hata kurtarma mantığı bu kenarlarla doğrudan grafik yapısına yazılıyor. Kontrol akışını kod gövdesine yaymak yerine topolojide görünür kılmak büyük takımlarda kodu kavrama süresini kısaltıyor; yeni birinin branch logic’ini anlamak için fonksiyon çağrı zincirini takip etmesi gerekmiyor.

İlk ajan: minimal örnek

from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, BaseMessage
from typing import TypedDict, Annotated
import operator

@tool
def hava_durumu(sehir: str) -> str:
    """Belirtilen şehrin hava durumunu döndürür."""
    return f"{sehir}: 22°C, parçalı bulutlu"

class AgentState(TypedDict):
    messages: Annotated[list[BaseMessage], operator.add]

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
araclar = [hava_durumu]
llm_with_tools = llm.bind_tools(araclar)

def ajan_dugumu(state: AgentState):
    response = llm_with_tools.invoke(state["messages"])
    return {"messages": [response]}

def devam_et_mi(state: AgentState):
    son_mesaj = state["messages"][-1]
    if hasattr(son_mesaj, "tool_calls") and son_mesaj.tool_calls:
        return "arac_cagir"
    return END

graph = StateGraph(AgentState)
graph.add_node("ajan", ajan_dugumu)
graph.add_node("arac_cagir", ToolNode(araclar))

graph.set_entry_point("ajan")
graph.add_conditional_edges("ajan", devam_et_mi)
graph.add_edge("arac_cagir", "ajan")

app = graph.compile()

result = app.invoke({"messages": [HumanMessage("İstanbul'da hava nasıl?")]})
print(result["messages"][-1].content)

Bu kod LangGraph’ın temel döngüsünü gösteriyor: ajan araç çağrısı yapar, araç çalışır, ajan sonucu görür, yeterince iyiyse durur. Döngünün tamamı grafik kenarlarıyla ifade ediliyor; kontrol akışı kodun içine dağılmış değil, grafik topolojisinde açık ve okunabilir.

Checkpoint: kaldığı yerden devam

Bir görev 15. adımda çöktüğünde iş akışını baştan çalıştırmak yerine tam kaldığı noktadan devam edebilirsiniz. Bu, LangGraph’ı benzer yaklaşımlardan ayıran özellik.

MemorySaver geçici, bellek içi checkpoint tutar. Test ve geliştirme için yeterli:

from langgraph.checkpoint.memory import MemorySaver

memory = MemorySaver()
app = graph.compile(checkpointer=memory)

config = {"configurable": {"thread_id": "kullanici-42"}}

# İlk çalıştırma
result = app.invoke(
    {"messages": [HumanMessage("Uçuş rezervasyonu yap")]},
    config=config
)

# Aynı thread_id ile ikinci çalıştırma — önceki state korunur
result2 = app.invoke(
    {"messages": [HumanMessage("Tarih: 15 Temmuz")]},
    config=config
)

SqliteSaver kalıcı checkpoint yazar. Uygulama yeniden başlasa bile thread geçmişi korunur:

from langgraph.checkpoint.sqlite import SqliteSaver

with SqliteSaver.from_conn_string("checkpoints.db") as memory:
    app = graph.compile(checkpointer=memory)

Production ortamında PostgresSaver ile veritabanı destekli checkpoint da mümkün. Uzun süren araştırma pipeline’ları, çok adımlı otomasyon görevleri veya kullanıcı etkileşimi gerektiren iş akışları için bu özellik işe yarar.

Human-in-the-loop

Bazı kararlar makineye bırakılamaz. Para transferi, dosya silme, kritik API çağrısı; bunları ajanın tek başına onaylaması kabul edilemez. LangGraph, interrupt_before ve interrupt_after ile ajanı tam istediğiniz noktada durdurur.

from langgraph.types import Command, interrupt

def kritik_adim(state: AgentState):
    # Ajan burada durur, insan onayı bekler
    onay = interrupt({
        "mesaj": "Para transferi onaylansın mı?",
        "miktar": state["miktar"],
        "hedef": state["hedef_hesap"]
    })

    if onay["karar"] == "onayla":
        return {"transfer_durumu": "tamamlandi"}
    return {"transfer_durumu": "iptal"}

# İnsan kararını verdikten sonra agent devam eder
app.invoke(
    Command(resume={"karar": "onayla"}),
    config=config
)

Pratik kullanım şöyle işliyor: ajan tüm hazırlığı yapar, insan sadece kritik kararı verir. Tekrarlayan işler otomatikleşir, risk noktaları insan denetiminde kalır. Bankacılık, hukuk ve tıp gibi alanlarda bu pattern ajan güvenilirliğini artırıyor.

Kurumsal ortamlarda ise bu yaklaşım iş akışının yalnızca eşik üstü öğelerini insana ileten bir kuyruk düzeni kurmayı mümkün kılıyor. Veri zenginleştirme, içerik moderasyonu veya müşteri eskalasyonu gibi senaryolarda ajan otomatik işlenebilen tüm öğeleri tamamlar; gerisi uzman kuyruğuna düşer. Ajanın o noktaya kadar derlediği bağlam ve özet, insanın sıfırdan başlamak yerine yalnızca karar vermek için masaya oturmasını mümkün kılıyor. Yüksek otomasyon oranı korunurken kritik noktalarda insan denetimi de yerli yerinde kalıyor. İş akışını tasarlarken hangi adımın insana kalması gerektiğini önceden belirlemek, sonradan eklemekten çok daha az maliyetli.

Multi-agent: supervisor pattern

Tek bir ajan her şeyi bilemez. Araştırma, kod yazma ve analiz gibi uzmanlık gerektiren görevler için LangGraph’ta multi-agent mimarisi kurabilirsiniz.

Supervisor modelinde bir yönetici ajan görevi alır, uygun uzmanlara delege eder, sonuçları birleştirir.

from langchain_core.messages import SystemMessage

def supervisor(state):
    sistem = SystemMessage(content="""
        Mevcut çalışanlar: arastirmaci, yazar, analist
        Göreve göre uygun çalışanı seç.
        Görev tamamlandıysa BITIR de.
    """)
    response = llm.invoke([sistem] + state["messages"])
    return {"sonraki": response.content.strip()}

def rota_belirle(state):
    return state["sonraki"]  # "arastirmaci", "yazar", "analist" veya "BITIR"

supervisor_graph = StateGraph(MultiAgentState)
supervisor_graph.add_node("supervisor", supervisor)
supervisor_graph.add_node("arastirmaci", arastirmaci_ajan)
supervisor_graph.add_node("yazar", yazar_ajan)

supervisor_graph.set_entry_point("supervisor")
supervisor_graph.add_conditional_edges("supervisor", rota_belirle, {
    "arastirmaci": "arastirmaci",
    "yazar": "yazar",
    "BITIR": END
})
supervisor_graph.add_edge("arastirmaci", "supervisor")
supervisor_graph.add_edge("yazar", "supervisor")

CrewAI’nın rol tabanlı yaklaşımına kıyasla bu mimari daha ince kontrol sunuyor. Her ajan geçişi grafikte açıkça tanımlı olduğundan davranışı izlemek ve hata ayıklamak çok daha kolay.

Supervisor mimarisinin pratik bir avantajı da izlenebilirlik. LangSmith entegrasyonuyla her ajan geçişi ayrı bir span olarak kaydediliyor; hangi uzmanın ne iş yaptığını, kaç token harcandığını ve nerede süre geçtiğini tam olarak görüyorsunuz. Bir hata durumunda hangi ajan, hangi adımda ve hangi state ile çöktüğünü bulup yalnızca o düğümü yeniden çalıştırabilirsiniz; grafiğin tamamını başa sarmak gerekmez.

LangGraph ve alternatifler

Hangi durumda LangGraph’ı tercih etmeli, hangisinde başka bir çerçeve?

LangGraph için: uzun süren, kesintiye dayanıklı iş akışları; döngü, kendi kendini düzeltme veya retry mekanizması; human-in-the-loop onay noktaları; production telemetri.

CrewAI için: rol tabanlı çoklu ajan simülasyonu ve hızlı prototipleme.

AutoGen için: kod yazan ve çalıştıran ajan çiftleri ve Microsoft ekosistemi.

Karar verirken pratik soru şu: “İş akışım 10 dakikadan uzun sürecek ve hata kurtarma gerektirecek mi?” Evetse LangGraph büyük olasılıkla doğru tercih. Sıfırdan AI agent yapımı yazısı bu framework kararından bağımsız temel kavramları kavramak için iyi bir başlangıç.

Platform ve deployment

LangGraph’ı üretim ortamına almak için birkaç yol var.

LangSmith izleme aracı olarak öne çıkıyor. Her düğüm çalışması, LLM çağrısı ve state geçişi otomatik kaydediliyor. Karmaşık bir grafikte hangi dalda ne bozuldu bulmak dakikalar yerine saniyeler alıyor. Üç ortam değişkeni yeterli:

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY=ls_...
export LANGCHAIN_PROJECT="production-agent"

Kodunuzda başka değişiklik gerekmez.

LangGraph Cloud serverless ajan hosting sunuyor. Grafiğinizi deploy edersiniz, platform checkpoint yönetimi, ölçeklendirme ve monitoring katmanını üstlenir. Multi-tenant senaryolarda her kullanıcıya izole bir thread_id verirsiniz; aralarında state sızması olmaz.

Self-host açık kaynak LangGraph sunucusu ile kendi altyapınızda çalışır. Docker imajı mevcut; checkpoint için PostgreSQL bağlanır. Maliyet kontrolü ve veri egemenliği öncelikliyse bu yol daha uygun.

Kurulum ve başlangıç

pip install langgraph langchain-openai

Checkpoint için SQLite:

pip install "langgraph[sqlite]"

LangGraph 0.2+ ile StateGraph, ToolNode, checkpoint ve interrupt API’leri stabil. Önemli değişiklikler için resmi changelog’u takip etmek yeterli.

RAG ile LangGraph’ı birlikte kullanmak yaygın: retrieval adımını ayrı bir düğüm olarak ekler, LLM düğümüne bağlarsınız. Function calling LangGraph araç düğümlerinin altyapısı; nasıl çalıştığını anlamak hata ayıklamasını kolaylaştırıyor. LLM halüsinasyon sorunları için LangGraph’ın retry ve self-correction döngüleri kullanışlı bir çözüm.