Bu yazıda LangChain 1.0 sürümünde gelen çok önemli bir yeniliğe değineceğiz: Langchain Middleware (Ara Katman). Eğer AI ajanları (agents) ile çalışıyorsanız, bu yazıyı mutlaka okumalısınız çünkü middleware, ajanlarınızın davranışları üzerinde size üst seviye kontrol verecek oyun değiştirici!
Neden Middleware’e İhtiyaç Var?
Hepimiz basit bir AI ajanı yapmayı biliyoruz değil mi? Model bir şeyler söylüyor, gerekirse araçları (tools) kullanıyor, sonuç veriyor. Demo için harika çalışıyor! Ama işler gerçek hayata döndüğünde sorunlar başlıyor [1].
İşte bazı gerçek dünya problemleri:
- Kontext Kontrolü: Model’e ne gösterdiğiniz, ne aldığınızı belirler. Ama standart ajan döngüsünde (agent loop) bu kontrolü tam olarak elinizde tutamıyorsunuz.
- Uzun Konuşmalar: Sohbet uzadıkça token limitleri aşılıyor, maliyet artıyor.
- Hassas İşlemler: Ajan para iadesi mi yapıyor? E-posta mı gönderiyor? Bunları otomatik olarak çalıştırmak riskli!
- Özel Durumlar: Her projenin kendine özgü ihtiyaçları var ama framework’ün sunduğu kalıplar yeterli gelmiyor.
LangChain ekibi 3 yıl boyunca geliştiricilerden sürekli aynı geri bildirimi aldı: “Daha fazla kontrole ihtiyacımız var!” [2]. Ve sonunda LangChain 1.0 ile middleware konseptini getirerek bu sorunu çözdüler.
LangChain 1.0 ve LangGraph 1.0 Nedir?
Eylül 2025’te LangChain ve LangGraph’in ilk kararlı sürümleri (v1.0) yayınlandı [1]. Bu büyük bir olay çünkü şu anlama geliyor: 2.0’a kadar hiçbir kırılma (breaking change) olmayacak! Büyük şirketler artık LangChain’i güvenle production’da kullanabiliyor [7].
İki framework, farklı amaçlar:
- LangChain 1.0: Hızlı ajan geliştirmek için. Yüksek seviye API’ler, standart kalıplar, ve tabii ki middleware desteği [1].
- LangGraph 1.0: Karmaşık, özelleştirilmiş workflow’lar için. Düşük seviyeli kontrol, kalıcı durum (persistent state), uzun süreli ajanlar [1].
En güzeli? İkisini birlikte kullanabiliyorsunuz! LangChain ile başlayıp, ihtiyaç duyduğunuzda LangGraph’e geçebiliyorsunuz [9].
Middleware Nedir? Web Sunucularından Öğrenelim
Middleware kavramını anlamak için web geliştirmeden bir örnek verelim. Express.js veya Django kullandıysanız middleware’i bilirsiniz [15]:
İstek → Middleware 1 → Middleware 2 → Ana İşlem → Middleware 2 → Middleware 1 → Yanıt
LangChain middleware’i tam olarak aynı mantıkla çalışıyor, sadece HTTP istekleri yerine AI ajan çağrılarını (agent calls) durduruyor [17]! Tıpkı FastAPI middleware’inin HTTP isteklerini kontrol etmesi gibi, LangChain middleware’i de ajanınızın karar verme sürecini kontrol ediyor [17].
Middleware’in Sihirli Altyapısı: LangGraph Runtime
Çok önemli bir detay: LangChain 1.0’da create_agent ile oluşturduğunuz ajanlar aslında LangGraph’in durable runtime’ı üzerine kurulu [1][28]. Yani middleware kullandığınızda, arka planda LangGraph’in güçlü altyapısından faydalanıyorsunuz!
LangGraph Ne Sağlıyor?
Middleware’in bu kadar güçlü olmasının sebebi, LangGraph’in sunduğu özellikler [5][27]:
1. Durable State (Kalıcı Durum)
- Middleware’ler state’i güvenle güncelleyebilir
- Sunucu yeniden başlatılsa bile durum korunur
- Uzun süreli konuşmalarda tutarlılık sağlanır
2. Checkpointing (Kontrol Noktaları)
- HumanInTheLoopMiddleware’in çalışmasını mümkün kılar
- Ajanın herhangi bir noktasından devam edebilirsiniz
- Multi-gün onay süreçlerini destekler
3. Pregel/BSP Algoritması
- Deterministik çalışma garantisi
- Paralel execution desteği
- Middleware’lerin sıralı ve güvenilir çalışması
4. Built-in Persistence
- Veritabanı mantığı yazmadan state kaydedilir
- Background job’lar desteklenir
- Uzun süreli workflow’lar mümkün
LangChain + LangGraph = En İyi İkili
Bu ikilinin nasıl birlikte çalışıtığına [1][9] dair basit bir örnek aşağıda:
# LangChain'de middleware ile ajan oluşturun
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware
# Bu, arka planda LangGraph runtime kullanıyor!
agent = create_agent(
model="gpt-4o",
tools=[...],
middleware=[SummarizationMiddleware(...)]
)
# İhtiyaç duyduğunuzda, bu ajanı LangGraph workflow'una entegre edin
from langgraph.graph import StateGraph
# LangGraph orchestration
graph = StateGraph(...)
graph.add_node("research_agent", agent) # LangChain ajanını düğüm olarak ekle
graph.add_node("analysis_agent", another_agent)
Bu yaklaşım size şunu sağlıyor [28]:
- Başlangıç: LangChain’in basit API’si ile hızlı başlayın
- Özelleştirme: Middleware ile çoğu ihtiyacınızı karşılayın
- İleri Seviye: Gerektiğinde LangGraph’in tam kontrolüne geçin
- Hibrit: İkisini aynı projede birlikte kullanın
Sonuç: Middleware sadece LangChain’e ait bir özellik değil – aslında LangChain ve LangGraph’in güçlerini birleştiren bir köprü! [1]
Middleware Hook’ları: Kontrol Noktaları
Hook Nedir? Basit Bir Açıklama
“Hook” (kanca) kelimesi yazılım dünyasında çok kullanılır ama aslında çok basit bir kavram. Düşünün ki bir süreç var (mesela AI ajanınızın çalışma döngüsü) ve bu süreç belirli adımlardan geçiyor. Hook’lar, bu sürecin belirli noktalarına “asabileceğiniz” kancalar gibidir [14][15].
Günlük hayattan örnek verelim: Restoranda yemek siparişi veriyorsunuz. Garson sizin masanıza geldiğinde (hook noktası), “Ekstra acı sos istiyorum” diyebilirsiniz. Mutfağın normal çalışma sürecini bozmadan, belirli bir noktada müdahale etmiş olursunuz. Middleware hook’ları da tam olarak böyle çalışıyor – ajanınızın normal akışını bozmadan, kritik noktalarda kendi kodunuzu çalıştırabiliyorsunuz!
LangChain 1.0 middleware’i üç ana “hook” (kanca) sunuyor [2][14]:
1. before_model: Model Çağrısından Önce
Model’i çağırmadan hemen önce devreye girer. Kullanım alanları [14]:
- Girdi doğrulama (validation)
- Durum güncellemesi (state update)
- Başka bir düğüme (node) atlama
- Loglama ve metrik toplama
@before_model
def log_before_model(state: AgentState, runtime: Runtime) -> dict:
print(f"Model'e {len(state['messages'])} mesaj gönderiliyor")
return None
2. after_model: Model Yanıtından Sonra
Model cevap verdikten sonra ama araçlar çalışmadan önce devreye girer [14]:
- Çıktı doğrulama
- Hassas bilgileri maskeleme
- Ek metadata ekleme
- Flow kontrolü
@after_model
def validate_output(state: AgentState, runtime: Runtime) -> dict:
son_mesaj = state["messages"][-1]
if "YASAK_KELIME" in son_mesaj.content:
return {
"messages": [AIMessage("Bu içeriği sağlayamıyorum.")],
"jump_to": "end"
}
return None
3. modify_model_request: İstek Modifikasyonu
Model çağrısını tam olarak değiştirebilirsiniz [14]:
- Kullanılabilecek araçları filtreleme
- Prompt’u değiştirme
- Model ayarlarını güncelleme
- Farklı bir model seçme
@wrap_model_call
def dynamic_model_selection(request: ModelRequest, handler) -> ModelResponse:
# Uzun konuşmalarda daha güçlü model kullan
if len(request.messages) > 50:
request.model = "gpt-4o"
else:
request.model = "gpt-4o-mini"
return handler(request)
Middleware Çalışma Sırası
Birden fazla middleware kullandığınızda, sıra önemli [14][15]:
Kullanıcı Girdisi
↓
Middleware 1: before_model
↓
Middleware 2: before_model
↓
Middleware 1,2: modify_model_request
↓
LLM Çağrısı (LangGraph Runtime)
↓
Middleware 2: after_model
↓
Middleware 1: after_model
↓
Nihai Yanıt
Gördüğünüz gibi, before_model ve modify_model_request sırayla (1→2) çalışıyor, ama after_model ters sırada (2→1) dönüyor [14]. Tıpkı soğan katmanları gibi!
Neden soğan katmanları gibi? Soğanı düşünün: Dış katmandan başlayıp içe doğru gidersiniz (Middleware 1 → Middleware 2 → Model), sonra içeriden tekrar dışarı çıkarken aynı katmanları ters sırada geçersiniz (Model → Middleware 2 → Middleware 1). Yani middleware’ler “sarmalama” (wrapping) mantığıyla çalışıyor – tıpkı soğan katmanlarının birbirini sarması gibi [15]!
Hazır Middleware’ler: Hemen Kullanmaya Başlayın
LangChain 1.0 ile birlikte production-ready middleware’ler geliyor [11][12]:
1. SummarizationMiddleware: Konuşma Geçmişini Özetle
Uzun sohbetlerde token limitlerine yaklaşınca otomatik olarak eski mesajları özetliyor [12][13]:
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware
agent = create_agent(
model="gpt-4o",
tools=[...],
middleware=[
SummarizationMiddleware(
model="gpt-4o-mini", # Özet için ucuz model
trigger={"tokens": 4000}, # 4000 token'da tetikle
keep={"messages": 20} # Son 20 mesajı koru
)
]
)
2. HumanInTheLoopMiddleware: İnsan Onayı Al
Kritik işlemler öncesi insan onayı iste [12][19]:
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="gpt-4o",
tools=[e_posta_gonder, para_iadesi_yap],
checkpointer=InMemorySaver(), # LangGraph checkpointing!
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"para_iadesi_yap": { # Bu araç için onay iste
"allowed_decisions": ["approve", "edit", "reject"]
},
"e_posta_oku": False # Bu araç otomatik çalışsın
}
)
]
)
3. PIIMiddleware: Kişisel Verileri Koru
E-posta, telefon, hesap numarası gibi hassas bilgileri otomatik olarak maskeliyor [19]:
from langchain.agents.middleware import PIIMiddleware
agent = create_agent(
model="gpt-4o",
tools=[...],
middleware=[
PIIMiddleware("email", strategy="redact"), # E-postaları kaldır
PIIMiddleware("phone", detector=r"\b\d{3}-\d{3}-\d{4}\b",
strategy="mask") # Telefonları maskele
]
)
4. TodoListMiddleware: Görev Planlaması
Karmaşık görevleri otomatik olarak alt görevlere böl [12][19]:
from langchain.agents.middleware import TodoListMiddleware
agent = create_agent(
model="gpt-4o",
tools=[kod_oku, kod_yaz, test_calistir],
middleware=[TodoListMiddleware()]
)
5. ModelFallbackMiddleware: Yedek Model
Birincil model başarısız olursa alternatif modelleri dene [13]:
from langchain.agents.middleware import ModelFallbackMiddleware
fallback = ModelFallbackMiddleware(
"openai:gpt-4o-mini", # İlk yedek
"anthropic:claude-sonnet-4-5-20250929" # İkinci yedek
)
agent = create_agent(
model="openai:gpt-4o", # Ana model
middleware=[fallback]
)
6. ToolRetryMiddleware: Araç Hatalarını Yeniden Dene
Araç çağrıları başarısız olursa otomatik retry yap [13][25]:
from langchain.agents.middleware import ToolRetryMiddleware
retry = ToolRetryMiddleware(
max_retries=3,
backoff_factor=2.0, # Exponential backoff
initial_delay=1.0,
jitter=True # Rastgele gecikme ekle
)
agent = create_agent(model="gpt-4o", middleware=[retry])
Özel Middleware Nasıl Yazılır?
Kendi middleware’inizi yazmak çok kolay [3][14]:
from langchain.agents.middleware import AgentMiddleware, ModelRequest
class RateLimitMiddleware(AgentMiddleware):
def __init__(self, max_calls_per_minute: int = 60):
super().__init__()
self.max_calls = max_calls_per_minute
self.call_times = []
def before_model(self, state, runtime):
import time
current_time = time.time()
# 1 dakikadan eski çağrıları temizle
self.call_times = [t for t in self.call_times
if current_time - t < 60]
if len(self.call_times) >= self.max_calls:
raise Exception("Rate limit aşıldı!")
self.call_times.append(current_time)
return None
Context Engineering: Middleware’in Gücü
Middleware’in asıl amacı context engineering (bağlam mühendisliği) [2][17]. AI ajanları başarısız olduğunda, genellikle AI kötü değildir – AI’ya doğru bilgi verilmemiştir [17]!
Middleware sayesinde:
- Model’e ne gösterildiğini tam kontrol edebilirsiniz
- Bağlam kirlenmesini (context pollution) önleyebilirsiniz
- Bağlam karantinası (context quarantine) uygulayabilirsiniz
- Her adımda özel mantık enjekte edebilirsiniz
Gerçek Dünya Örneği: Multi-Agent Sistem
Middleware’leri çok ajanlı sistemlerde (multi-agent systems) kullanmak çok güçlü [20]:
from langchain.agents import create_agent
# Supervisor ajan - tüm middleware'ler burada
supervisor = create_agent(
model="gpt-4o",
tools=[alt_ajan_1, alt_ajan_2, alt_ajan_3],
middleware=[
SummarizationMiddleware(...),
HumanInTheLoopMiddleware(...),
CustomGuardrailMiddleware(...) # Özel güvenlik katmanı
]
)
En güzel yanı? Middleware’leri sadece supervisor seviyesinde tanımlasanız bile, alt ajanlara (subordinate agents) otomatik olarak uygulanıyorlar [20]! Kompozisyon (composability) tam burada parlıyor.
Kurulum ve Başlangıç
Middleware’i denemek için [5][27]:
# Python 3.10+ gerekli pip install --pre -U langchain pip install -U langchain-openai langchain-anthropic # JavaScript npm install langchain@next
Basit bir örnek:
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware
agent = create_agent(
model="gpt-4o",
tools=[arama_araci, hesap_makinesi],
middleware=[
SummarizationMiddleware(
model="gpt-4o-mini",
trigger={"tokens": 3000}
)
]
)
# Kullanımı çok basit!
sonuc = await agent.invoke({
"messages": [{"role": "user", "content": "Merhaba!"}]
})
Production’da Dikkat Edilecekler
Middleware’leri production’da kullanırken [19][24]:
- Bir seferde bir middleware ekleyin: Test edin, sonra diğerini ekleyin
- Checkpointer kullanın: HumanInTheLoop için şart (LangGraph özelliği!)
- Loglama ekleyin: Her middleware’de ne olduğunu takip edin
- Maliyet izleyin: Özellikle SummarizationMiddleware ekstra LLM çağrısı yapar
- Rate limiting ekleyin: Production’da mutlaka limit koyun
Sonuç: Middleware ile Yeni Dönem
LangChain 1.0’ın middleware sistemi, AI ajan geliştirmede devrim niteliğinde [5][14]. Web framework’lerindeki middleware’lerin başarısını AI dünyasına taşırken, LangGraph’in güçlü altyapısından faydalanıyor [1][27].
Artık şunları yapabiliyoruz:
- Tam kontrol: Her adımda tam kontrol (LangGraph runtime sayesinde)
- Modüler: Lego gibi birleştir
- Yeniden kullanılabilir: Bir kez yaz, her yerde kullan
- Güvenli: Güvenlik ve guardrail’ler built-in
- İzlenebilir: Her şey loglanabilir
- Birlikte çalışır: LangChain ve LangGraph mükemmel uyum
Bu sadece başlangıç! Middleware ekosistemi büyüdükçe, community daha fazla kullanışlı middleware paylaşacak. Sizin de kendi middleware’inizi yazıp paylaşmanızı teşvik ediyorum!
Middleware ile AI ajanlarınızı bir üst seviyeye taşıyın. Production-ready, güvenli ve kontrol edilebilir sistemler kurmanın zamanı geldi diyorsanız VBO AI&LLM Bootcamp harika bir adres.
Kaynaklar
[1] LangChain and LangGraph Agent Frameworks Reach v1.0 Milestones – https://blog.langchain.com/langchain-langgraph-1dot0/
[2] Agent Middleware – https://blog.langchain.com/agent-middleware/
[3] Middleware – Docs by LangChain – https://docs.langchain.com/oss/python/langchain/middleware
[4] LangChain 1.0 — A second look – https://medium.com/mitb-for-all/langchain-a-second-look-6ed720e27fec
[5] LangChain Middleware v1-Alpha: A Comprehensive Guide – https://colinmcnamara.com/blog/langchain-middleware-v1-alpha-guide
[6] Authentication & Access Control – https://langchain-ai.github.io/langgraphjs/concepts/auth/
[7] LangChain and LangGraph 1.0: Powering the Next Generation of AI Agents – https://joshuaberkowitz.us/blog/news-1/langchain-and-langgraph-1-0-powering-the-next-generation-of-ai-agents-1547
[8] How to add custom middleware – https://langchain-ai.github.io/langgraphjs/how-tos/http/custom_middleware/
[9] LangGraph 1.0 released: no breaking changes – https://medium.com/@romerorico.hugo/langgraph-1-0-released-no-breaking-changes-all-the-hard-won-lessons-8939d500ca7c
[10] langgraph/docs/docs/how-tos/http/custom_middleware.md – https://github.com/langchain-ai/langgraph/blob/main/docs/docs/how-tos/http/custom_middleware.md
[11] Agent Middleware – LangChain Blog – https://blog.langchain.com/agent-middleware/
[12] Middleware Documentation – https://docs.langchain.com/oss/python/langchain/middleware
[13] Middleware Reference – https://reference.langchain.com/python/langchain/middleware/
[14] LangChain Middleware v1-Alpha Guide – https://colinmcnamara.com/blog/langchain-middleware-v1-alpha-guide
[15] Go Deep with LangChain Middleware – https://medium.com/data-science-collective/building-deep-agents-with-langchain-1-0s-middleware-architecture-7fdbb3e47123
[16] LangChain Middleware: precise control around the agent loop – https://medium.com/@pankaj_pandey/langchain-middleware-precise-control-around-the-agent-loop-1030a1c8e3ea
[17] LangChain v1.0 Middleware: Context engineering – https://medium.com/@aayushmaan162/langchain-v1-0-middleware-context-engineering-as-a-first-class-citizen-577f020fb378
[18] Using middleware with stateful tools in LangChain 1.x – https://github.com/langchain-ai/docs/issues/674
[19] Build Production-Ready LLM Agents with LangChain 1.0 Middleware – https://codecut.ai/langchain-1-0-middleware-production-agents/
[20] LangChain 1.0 Multi-Agent Systems – https://medium.com/mitb-for-all/langchain-a-second-look-6ed720e27fec
[21] Agent Middleware Blog Post – https://blog.langchain.com/agent-middleware/
[22] Middleware Docs – https://docs.langchain.com/oss/python/langchain/middleware
[23] Middleware in LangChain 1.0 alpha – https://changelog.langchain.com/announcements/middleware-in-langchain-1-0-alpha
[24] Build Production-Ready Agents – https://codecut.ai/langchain-1-0-middleware-production-agents/
[25] Middleware API Reference – https://reference.langchain.com/python/langchain/middleware/
[26] LangChain 1.0 Second Look – https://medium.com/mitb-for-all/langchain-a-second-look-6ed720e27fec
[27] LangChain Middleware Comprehensive Guide – https://colinmcnamara.com/blog/langchain-middleware-v1-alpha-guide
[28] LangChain Official Site – https://www.langchain.com/langchain
[29] LangChain 1.0 Release – https://blog.langchain.com/langchain-langgraph-1dot0/
[30] Custom Middleware GitHub – https://github.com/langchain-ai/langgraph/blob/main/docs/docs/how-tos/http/custom_middleware.md
[31] Kapak Görseli: Photo by Luke van Zyl on Unsplash
