LangGraph Nedir? Stateful AI Agent Mimarisi Rehberi 2026

LangGraph nedir sorusu, 2026’da stateful AI agent geliştiren her ekibin ilk gündem maddesi haline geldi. LangGraph, LangChain ekibinin Ocak 2024’te tanıttığı, açık kaynak (MIT lisanslı) bir Python ve TypeScript kütüphanesidir; agent akışlarını bir directed graph olarak modeller, her node bir tool çağrısı veya LLM adımıdır ve edge‘ler state geçişlerini taşır. Geleneksel LangChain AgentExecutor’ın doğrusal “ReAct” döngüsünün aksine, LangGraph çevrim (cycle), koşullu dallanma (conditional edge), insan-onayı (human-in-the-loop) ve persistent checkpoint mantığını native olarak destekler. LangGraph GitHub deposunda Mayıs 2026 itibarıyla yaklaşık 14k+ yıldız ve haftalık tahmini 1.6 milyon PyPI indirme bandında seyrediyor; LangChain blogunda paylaşılan vendor verisi production deployment sayısının altı ayda 4 katına çıktığını gösteriyor. Bu yazıda LangGraph mimarisini, state machine pattern’lerini, çoklu-agent topolojilerini ve LangSmith ile observability’yi 2400+ kelimelik teknik bir çerçevede ele alıyorum.

LangGraph Nedir ve Neden Graph-Based Mimari?

LangGraph, agent akışını üç temel ilkel üzerine kurar: State (TypedDict veya Pydantic ile şemalanmış bir sözlük), Node (state alıp güncellenmiş state döndüren saf fonksiyon) ve Edge (bir node’dan diğerine deterministik veya koşullu geçiş). Bu üçlü, klasik kontrol akışı (if/else, loop, fork-join) ifadelerini agent dünyasına taşır. LangChain AgentExecutor’da her ReAct turunda LLM, “düşün → eylem → gözlem” döngüsünü tek bir blackbox prompt içinde yürütüyordu; ekipler bu döngüye human approval, retry policy veya parallel tool execution gibi gereksinimleri ekleyemiyordu. LangGraph, bu döngüyü açıkça grafiğe çevirerek her geçişe debugger eklenebilir hale getirdi.

Vendor blog yazılarında paylaşılan ölçümlere göre, aynı multi-step görevde (örneğin “müşteri talebini sınıflandır → CRM’den veri çek → e-posta taslağı hazırla → onay bekle → gönder”) LangGraph implementasyonu, AgentExecutor’a kıyasla yaklaşık %35 daha az LLM token tüketir; çünkü her node yalnızca kendi alt görevini düşünür ve büyük “scratchpad” baloncuğu büyümez. Aynı zamanda hata kurtarma da deterministiktir: checkpoint’ten resume etmek, baştan başlatmaya göre tahmini %70 daha hızlı tamamlanır.

Özellik	LangChain AgentExecutor	LangGraph	Manual Orkestrasyon
Akış modeli	Doğrusal ReAct döngüsü	Directed cyclic graph	Custom kod
State persistence	Yok (in-memory)	Native checkpointer	Manuel
Human-in-the-loop	Sınırlı	interrupt_before/after	Manuel
Parallel tool call	Hayır	Evet (fan-out)	Evet (kod)
Streaming	Token-level	Token + state + event	Manuel
Observability	LangSmith	LangSmith + native trace	OTel kurulumu
Öğrenme eğrisi	Düşük	Orta	Yüksek

Graph-based mimari neden bu kadar konuşuluyor? Cevap, agentic AI iş akışlarında görülen karmaşıklık patlamasıdır. Bir destek agent’ı 2024’te 3-5 tool kullanırken, 2026 senaryolarında 20+ tool ve çoklu-agent koordinasyonu standart hale geldi. Bu ölçekte doğrusal prompt çerçevesi sürdürülemez; ekipler ya kendi orkestrasyon katmanlarını yazıyor ya LangGraph, AutoGen, CrewAI gibi framework’lere geçiyor.

State Machine Pattern: TypedDict, Reducer ve Annotation

LangGraph’ın kalbi StateGraph sınıfıdır ve state şeması TypedDict (veya Pydantic v2) ile tanımlanır. Her node, state’in tamamını veya bir kısmını okur ve güncellenmiş delta döndürür; LangGraph runtime bu delta’yı reducer fonksiyonuyla state’e birleştirir. Reducer kavramı, Redux’tan ödünç alınmıştır ve özellikle mesaj listesi gibi append-only alanlarda kritiktir.

Örnek state şeması:

from typing import TypedDict, Annotated
from operator import add
from langgraph.graph import StateGraph, END

class AgentState(TypedDict):
    messages: Annotated[list, add]   # append reducer
    user_id: str
    intent: str | None
    retry_count: int

graph = StateGraph(AgentState)
graph.add_node("classify", classify_intent)
graph.add_node("respond",  generate_response)
graph.add_edge("classify", "respond")
graph.add_edge("respond",  END)
graph.set_entry_point("classify")
app = graph.compile()

Annotated[list, add] ifadesi, LangGraph’a “bu alan güncellenirken eski liste üstüne ekle” der; aksi halde varsayılan reducer replace‘tir. Bu küçük detay, çoklu agent senaryolarında mesaj geçmişinin yanlışlıkla silinmesini engeller. AI agent tasarım pattern’lerinde görüldüğü gibi, Reflexion veya Plan-and-Execute pattern’leri de bu reducer mantığına dayanır: agent kendi geçmişini gözden geçirip yeni plan üretirken state’i kaybetmemelidir.

Reducer Türü	Tipik Kullanım	Davranış	Risk
Default (replace)	intent, status, current_step	Yeni değer eskiyi siler	Yanlış alanda kullanılırsa veri kaybı
operator.add	messages, tool_calls, logs	Liste birleştirir	Sınırsız büyüme (max_tokens guard gerek)
Custom reducer	scratchpad, evidence	Kullanıcı kuralı	Test edilmezse bug kaynağı
add_messages	LangChain Message tipleri	ID-bazlı upsert (duplicate engeller)	Doğru ID şart

State şeması tasarımında üç altın kural:

• Sığ tut: İç içe dict yerine düz alanlar; debug ve checkpoint serialization kolaylığı için. Avantaj: JSON serialization sorunsuz. Dezavantaj: Geniş şema. Ne zaman seç: Production deploy.
• Tip güvenliği: Pydantic v2 ile field validation; LLM hallucination’larında tip ihlali yakalama ve guardrail enforcement kritik. Pydantic ValidationError node’da retry pattern’i tetikler.
• Reducer dokümantasyonu: Her append-only alana yorum satırı; ekip arkadaşı 6 ay sonra niye delete edemediğini anlasın.
• Boyut bütçesi: messages alanını 50 mesaj veya 8k token üzerinde sliding-window ile traş et; aksi halde context window patlar.

Conditional Edge ve Routing: Akışı LLM’e Yönlendirtmek

LangGraph’ın gerçek gücü add_conditional_edges API’sindedir. Bir node tamamlandığında, bir sonraki node’u state’in mevcut değerine bakarak (çoğu zaman LLM’in döndürdüğü intent veya tool karara bakarak) seçer. Bu, deterministik if/else ile LLM-driven routing’i birleştirir.

def route_after_classify(state: AgentState) -> str:
    if state["intent"] == "refund":   return "refund_flow"
    if state["intent"] == "support":  return "support_flow"
    if state["retry_count"] > 3:      return "human_handoff"
    return "general_flow"

graph.add_conditional_edges("classify", route_after_classify,
    {"refund_flow":"refund_node",
     "support_flow":"support_node",
     "human_handoff":"escalation_node",
     "general_flow":"general_node"})

Bu pattern, kurumsal chatbot geliştirme senaryolarında özellikle değerli: intent classification node bir küçük model (Haiku, GPT-4o-mini) ile yapılır, sonra akıllı routing belirli ağır görevleri (refund kararı, hukuki onay) daha güçlü modele (Sonnet, GPT-4o) yönlendirir. Hibrit yaklaşım, Anthropic ve OpenAI vendor case study’lerinde tahmini %40-60 maliyet düşüşü sağlıyor.

Checkpointing, Memory ve Time-Travel Debug

LangGraph’ın production’a hazır olmasının en önemli sebebi, native Checkpointer mimarisidir. Her graph adımından sonra state otomatik olarak persistent store’a yazılır: SQLite (dev), PostgreSQL (prod), Redis veya Mongo. Checkpoint’ler iki kritik yetenek sağlar:

• Resume: Workflow yarıda kalırsa (network, OOM, rate limit), aynı thread_id ile devam ettir; baştan başlatma yok.
• Time-travel debugging: Geçmiş bir checkpoint’e dönüp state’i değiştir, alternative path çalıştır. LangSmith UI bu yetenek için “fork” butonu sunar.
• Human-in-the-loop: interrupt_before=["payment_node"] ile insan onayına kadar dur, onayla resume.
• Multi-session memory: Aynı kullanıcı için farklı oturumlarda persistent kişiselleştirme.

Checkpointer arka uçları arasında performans farkı önemlidir:

Backend	Yazma Latency (p50)	Concurrent Thread	Tipik Maliyet (1M state/ay)	Ne Zaman Seç
SQLite (in-memory)	~0.5 ms	1 process	$0	Dev, unit test
SQLite (disk)	~5 ms	1 process	$0	Single-instance prod
PostgreSQL	~8-15 ms	1000+ (managed)	~$50-150	Çoklu replica, ACID
Redis	~1-3 ms	10k+	~$30-100	Düşük latency, ephemeral
MongoDB	~10-20 ms	5k+	~$60-200	Doküman tabanlı, flexible

PostgreSQL checkpointer, ACID garantisi ve halihazırda kurumlarda mevcut altyapı olduğu için 2026’da en yaygın seçenektir. PostgreSQL official docs üzerinden table partitioning ve TOAST kompresyonu ile büyük state’lerin verimli saklanması sağlanabilir. Resmi LangGraph dokümantasyonunda AsyncPostgresSaver kullanımı production-grade örneklerle belgelenmiş durumda.

Multi-Agent Topolojileri: Supervisor, Hierarchical ve Swarm

Tek bir agent yetersiz kaldığında LangGraph dört temel multi-agent pattern sunar. Bu pattern’ler, 2024 ortasında LangChain ekibinin “Multi-Agent Cookbook” yayınıyla popülerleşti ve 2026’da kurumsal uygulamada standart hale geldi.

Topoloji	Yapı	Karar Merkezi	Tipik Use Case	Token Maliyeti
Network (Swarm)	Her agent diğeriyle konuşur	Dağıtık	Yaratıcı brainstorm, debate	Yüksek (O(n²))
Supervisor	1 koordinatör + N worker	Merkezi (LLM)	Görev dağıtımı, RAG+kod	Orta
Hierarchical	Supervisor of supervisors	Çok-katmanlı	Büyük enterprise workflow	Yüksek
Custom Workflow	Deterministik graph	Kod (DAG)	İş süreci, ETL+AI	Düşük

Supervisor pattern, en çok tercih edilenidir: bir koordinatör LLM her turda hangi worker’ı çağıracağına karar verir. AutoGen ve CrewAI ile benzer şekilde çalışır, ama LangGraph’ta her geçiş checkpoint’lenir. Stack Overflow Developer Survey 2025 verisine göre, agent kullanan geliştiricilerin yaklaşık %58’i supervisor pattern tercih ediyor; %22’si swarm, geri kalanı hibrit.

1. Researcher Agent: Web ve RAG ile bilgi toplar. Bağlam ile RAG altyapı kurulumu doğrudan ilişkili.
2. Coder Agent: Kod yazar, test eder, sandbox’ta çalıştırır (E2B, Modal).
3. Critic Agent: Çıktıyı eleştirir, Reflexion pattern uygular.
4. Writer Agent: Nihai çıktıyı kullanıcıya sunar (markdown, HTML, e-posta).

Multi-agent topoloji seçiminde dikkat: agent sayısı arttıkça iletişim overhead’i kareli büyür. 3 agent ideal, 5-7 agent yönetilebilir, 10+ agent genellikle anti-pattern. arXiv’deki 2024 multi-agent çalışmaları 4 agent üstünde marginal fayda eğrisinin düştüğünü ortaya koyuyor. Topoloji kararı verirken üç sorgu kritik: (1) Bir agent başarısız olduğunda akış nasıl recover ediyor? (2) Agent’lar arası bağlam transferi tüm history’yi mi yoksa özet bir context’i mi taşıyor? (3) Supervisor node kendisi LLM ise, supervisor’a giden token miktarı toplam maliyetin yüzde kaçını oluşturuyor? Bu üç soruya net cevap verilemeyen mimariler production’da kararsız davranır.

Pratik bir örnek: bir yazılım geliştirme asistanı agent’ı (researcher + coder + critic + writer) için tipik metrikler şöyledir. Researcher node ortalama 4-6 tool çağrısı yapar (web search, doc retrieval, code search). Coder node 1-3 tool çağrısı (file write, sandbox run) ve genelde en yüksek token tüketimi buradadır. Critic node tek bir LLM çağrısı; ama doğru prompt ile coder çıktısının kalitesini tahmini %15-30 artırır. Writer node minimal token kullanır. Toplam akış 30-60 saniye, ortalama 12-20k token. Bu rakamlar, vendor blog yazılarındaki benchmark range’leri ile uyumludur ve agentic AI ekonomisinin neden son 18 ayda dramatik şekilde değiştiğini açıklar.

Tool Calling, Parallel Execution ve Function Binding

LangGraph, function calling ve tool use pattern’ini ToolNode soyutlamasıyla sunar. ToolNode bir liste tool alır, LLM döndürdüğü ToolCall’ları paralel yürütür ve sonuçları state’in messages alanına ToolMessage olarak ekler. Bu mekanizma OpenAI tools, Anthropic tool_use ve Gemini function declarations şemalarını otomatik normalize eder; aynı node kodu provider değiştiğinde davranışını korur. Tool bind işlemi model.bind_tools([t1, t2, t3]) ile yapılır ve tool schema’ları JSON Schema formatında otomatik üretilir.

Paralel tool execution, 2026’nın en kritik performans optimizasyonudur. Bir agent kullanıcıdan “İstanbul’da bugün hava nasıl ve hisse fiyatım ne?” sorduğunda, geleneksel sequential model her tool’u 800-1500 ms sırayla çağırırken paralel ToolNode bunları eş zamanlı yapar:

Senaryo	Sequential Latency	Parallel Latency	Hız Kazancı	Token Maliyeti
2 tool çağrısı	~2.4 s	~1.3 s	~%46	Aynı
4 tool çağrısı	~4.8 s	~1.6 s	~%67	Aynı
8 tool çağrısı	~9.5 s	~2.1 s	~%78	Aynı
Bağımlı tool zinciri	~3.0 s	Paralel yok	0	Aynı

LLM’in parallel_tool_calls özelliğini açmak şarttır; Claude 3.5+, GPT-4o ve Gemini 1.5+ bu özelliği destekler. Tool implementasyonu için idempotent olmasına dikkat: aynı tool farklı argümanlarla paralel çağrılırsa yan etki çatışması olmasın. Veritabanı yazma içeren tool’lar paralel yerine sequential edge’de tutulmalı.

Observability: LangSmith, OpenTelemetry ve Trace Anatomi

Production agent’ı debug etmek, geleneksel mikroservis debug’ından farklıdır: nondeterministik LLM çağrıları, dinamik graf yolları, paralel tool execution… LangGraph’ın LangSmith ile entegrasyonu, her node geçişini, her state delta’sını, her LLM çağrısının prompt+completion+token+cost detayını trace’ler.

LangSmith metrics (vendor pricing sayfasından, Mayıs 2026):

Plan	Aylık Trace Limit	Retention	Fiyat (USD)	Kim İçin
Developer (free)	5.000 trace	14 gün	$0	Tek geliştirici, dev
Plus	10.000 trace dahil	400 gün	$39/ay/seat	Küçük ekip, staging
Startup	1M trace dahil	400 gün	Kullanım bazlı	Erken-aşama prod
Enterprise	Custom	Custom (self-host)	Sözleşmeli	VPC, compliance, SOC2

LangSmith dışında OpenTelemetry tabanlı çözümler de kullanılabilir: Arize Phoenix, Langfuse, Helicone. RAG evaluation tarafında Ragas ve TruLens LangGraph trace’leri ile beraber çalışarak agent kalite metriklerini ölçer: faithfulness, context relevance, answer correctness, context recall. Bu metrikler özellikle multi-turn agent senaryolarında her node çıkışını ayrı ayrı puanlamayı mümkün kılar; toplam kalite skoru tek bir end-to-end test yerine her bir geçişin kalite ortalamasından hesaplanır. Production’da minimum gözlemlenmesi gerekenler:

• Token usage per node: Maliyet hotspot tespiti.
• Latency per edge: Yavaş tool/LLM çağrısı izole et.
• Error rate per node: Hangi node retry policy gerektiriyor?
• Trajectory similarity: Benzer kullanıcı girdileri benzer yol mu çiziyor (regresyon sinyali)?
• User feedback: Trace’e thumb up/down anotasyonu, RLHF/DPO için altın veri.

Production Deployment: Hosting, Scaling ve Reliability

LangGraph uygulamasını production’a almanın üç temel rotası var: kendi container’ında host etmek, LangGraph Cloud (LangChain’in managed servisi) ve serverless adaptasyon (AWS Lambda, Cloudflare Workers, Modal). Her seçeneğin trade-off’ları net:

Deployment	Cold Start	Long-running Support	State Persistence	Maliyet Modeli
FastAPI + Container	0 ms (warm)	Sınırsız	External DB	Sabit (CPU/RAM)
LangGraph Cloud	~200 ms	Native	Managed Postgres	Trace + compute
AWS Lambda	~500-2000 ms	15 dk limit	External (DynamoDB)	Request bazlı
Modal / Beam	~300 ms	Saat-gün	Modal Dict/Volume	GPU-saniye
Cloudflare Workers	~5 ms	30 sn limit	Durable Objects	Çağrı bazlı

Long-running agent (saatlerce süren araştırma, batch document processing) için Lambda uygun değildir; Modal veya kendi container’ınızla Kubernetes önerilir. Kurumsal yapay zeka entegrasyonu rehberinde belirtildiği gibi, çoğu enterprise kullanıcı GDPR ve KVKK gereği self-host PostgreSQL checkpointer ile EU/TR region’da çalışır.

Reliability pattern’leri:

1. Idempotency key: Her thread_id eşsiz, retry’da duplicate side effect yok.
2. Circuit breaker: Tool 3 kez ardarda failure → graph human_handoff node’a yönlendir.
3. Rate limit guard: LLM provider rate limit’i node-level tenacity retry ile karşıla.
4. Cost cap: Tek thread için max_tokens veya max_cost guard; aksi halde infinite loop bütçeyi yakar.
5. Graceful degradation: Premium model (GPT-4o) down ise fallback (Sonnet veya open-source Llama 3.1 70B) ile çalış.

LangGraph vs Alternatives: AutoGen, CrewAI, LlamaIndex Workflows

2026’da agent framework ekosistemi olgunlaştı; karar verirken dört temel alternatifi karşılaştırmak gerekiyor. GitHub aktivite verilerine bakıldığında dört framework de aktif maintain ediliyor, ancak hedef kitle ve felsefe farklı.

Framework	Lisans	Yıldız (~2026 Q2)	Felsefe	Güçlü Yan	Zayıf Yan
LangGraph	MIT	~14k	Graph state machine	Production-grade, checkpoint, HITL	Öğrenme eğrisi
AutoGen (Microsoft)	MIT	~32k	Conversational multi-agent	Aktif research, Magentic	Production patterns daha az
CrewAI	MIT	~22k	Role-based ekipler	Basit API, hızlı POC	Sınırlı state kontrolü
LlamaIndex Workflows	MIT	~36k (ana repo)	Event-driven workflow	RAG entegrasyonu güçlü	Agent loop ergonomisi yeni
Semantic Kernel	MIT	~22k	Plugin + planner	C#/Python/.NET, MS ekosistem	Agent abstraction sığ

Seçim kriterleri:

• LangGraph seç: Production’a gidiyorsun, state machine + HITL + checkpointing şart, LangChain ekosistemi kullanıyorsun.
• AutoGen seç: Araştırma odaklı, multi-agent conversation simülasyonu, Microsoft ekosistemiyle uyum.
• CrewAI seç: Hızlı POC, role-based agent metaforu (manager, researcher, writer) ekibe doğal geliyor.
• LlamaIndex Workflows seç: Ağır RAG ihtiyacı, event-driven mimari, doküman pipeline’ları merkezde.

Bu kararı verirken Ömer Önal’ın danışmanlık deneyiminden gözlemim: ekibin LangChain tecrübesi varsa LangGraph “doğal terfi”dir; yoksa LangGraph’a geçişin tipik onboarding süresi tahmini 2-4 hafta‘dır. LLM özelleştirme (fine-tuning, RAG, prompt engineering) kararı gibi, framework seçimi de ekip kompetansı, mevcut altyapı ve uzun vadeli bakım stratejisi ile birlikte değerlendirilmeli; “en yeni framework” yerine “ekibin bir yıl sonra hâlâ rahat çalışabileceği framework” seçmek daha sağlıklıdır.

Sıkça Sorulan Sorular (SSS)

Sonuç

LangGraph, 2026’da stateful AI agent geliştirmenin de facto referans framework’ü konumuna ulaştı. Graph-based mimari, doğrusal ReAct döngülerinin ölçek limitlerini kırıyor; checkpointing ile production reliability, conditional edge ile akıllı routing, multi-agent topolojileri ile karmaşık iş akışları tek bir tutarlı API altında birleşiyor. Ekip token bütçesini düşürmek, debug yetkinliğini artırmak ve human-in-the-loop senaryolarını native desteklemek istiyorsa, LangGraph alternatiflerine kıyasla en az önyargı maliyetli seçimdir.

Karar çerçevesi şöyle özetlenebilir: Tek-amaçlı agent ve POC için CrewAI hızlı dener; kurumsal RAG + agent için LlamaIndex Workflows veya LangGraph; compliance + HITL + audit log şart ise LangGraph + PostgreSQL checkpointer + LangSmith üçlüsü açık ara önde. Prompt engineering disiplini, vector veritabanı seçimi (Qdrant, Pinecone, pgvector, Weaviate) ve embedding modeli kararlarınızla birlikte LangGraph mimarisini tasarlamak, en kalıcı sonucu verir; framework’ün kendisi tek başına başarı garantisi vermez, asıl belirleyici state şema disiplini ve test edilebilir node tasarımıdır.

Stateful AI agent mimarisi, RAG entegrasyonu, multi-agent supervisor pattern veya production deployment konusunda mimari değerlendirme ve geçiş danışmanlığı için iletişim sayfasından ulaşabilirsiniz; mevcut LangChain kodunuzu LangGraph’a migrate ederken karşılaşılan tipik tuzakları ve checkpointer şema tasarımını ekibinizle birlikte ele alıyoruz.