LangGraph Nedir? Durum Bilgili Yapay Zeka Ajanları Oluşturma Rehberi

Çoğu ajan kodu basit başlar; sonra yeniden denemeler, araç çağrıları, dallanmalar ve insan onayı eklendikçe kırılgan hale gelir. Bir LLM’i bağlayıp birkaç araç verdiğinizde düz bir script yeterli olabilir, ancak iş akışı döngü yapmalı, duruma göre yönlenmeli veya bir noktada durup kullanıcı onayı beklemeliyse daha açık bir orkestrasyon modeline ihtiyacınız vardır. LangGraph bu ihtiyacı, ajanı paylaşımlı duruma sahip bir grafik olarak modelleyerek çözer. Bu yazıda LangGraph’ın ne olduğunu, nasıl uygulanacağını ve ajanınız gerçek servisleri çağırdığında API testinin nerede devreye girdiğini adım adım ele alacağız.

Apidog'u bugün deneyin

LangGraph nedir?

LangGraph, uzun süre çalışan, durum bilgisi olan ajanlar oluşturmak için kullanılan düşük seviyeli bir orkestrasyon çerçevesi ve çalışma zamanıdır. LangChain’in arkasındaki ekip olan LangChain Inc tarafından geliştirilmiştir, ancak LangChain’den ayrı kullanılabilir.

Kurulum:

pip install -U langgraph

LangGraph’ta ajanınızı bir grafik olarak tanımlarsınız:

• Düğümler iş yapar: model çağırır, araç çalıştırır, veri dönüştürür.
• Kenarlar sıradaki adımı belirler.
• Paylaşımlı durum her düğümden geçer ve düğümler bu durumu okuyup güncelleyebilir.
• Döngüler grafikte doğal olarak ifade edilir; araçtan modele geri dönmek gibi akışlar düz if bloklarına gömülmez.

Klasik bir zincir şu yapıya benzer:

Adım 1 -> Adım 2 -> Adım 3 -> Bitti

LangGraph ise şuna izin verir:

Model -> Araç -> Model -> Karar
                  ├── Devam et
                  └── Bitir

Gerçek ajan davranışı genelde çizgisel değildir. “Düşün, araç çağır, sonucu gözlemle, tekrar karar ver” modeli bir döngüdür. LangGraph’ın temel avantajı bu döngüyü açık, test edilebilir ve sürdürülebilir hale getirmesidir.

LangGraph hangi sorunu çözer?

Ajan tabanlı iş akışlarında genelde şu ihtiyaçlar ortaya çıkar:

• Durma koşullu döngüler: Araç çağırmaya devam et, ancak sonsuz döngüye girme.
• Duruma göre dallanma: Modelin çıktısına göre farklı düğüme git.
• Kalıcılık: Çökme, zaman aşımı veya yeniden başlatma sonrası kaldığın yerden devam et.
• Döngüde insan: Çalışmayı duraklat, kullanıcıya onaylat veya düzenlet, sonra devam et.
• Akış: Model token’larını ve ara adımları işlem devam ederken yayınla.

Bu davranışları düz Python koduyla yazabilirsiniz, ancak birkaç araç ve birkaç hata durumu eklendiğinde kod hızla karmaşıklaşır. LangGraph bu akışı bir durum makinesi gibi yönetir.

Temel kavramlar: grafik, durum, düğümler ve kenarlar

LangGraph’ta temel yapı dört parçadan oluşur.

1. Durum

Durum, tüm çalışma boyunca taşınan paylaşımlı nesnedir. Genellikle TypedDict ile tiplenir. Sohbet tabanlı ajanlarda sık kullanılan hazır şema MessagesState’tir.

2. Düğümler

Düğümler normal Python fonksiyonlarıdır. Mevcut durumu alır ve duruma eklenecek kısmi bir güncelleme döndürür.

3. Kenarlar

Kenarlar düğümleri birbirine bağlar.

• add_edge() sabit geçişler için kullanılır.
• add_conditional_edges() koşullu yönlendirme için kullanılır.

4. START ve END

START grafiğin başlangıç noktasını, END ise bitiş noktasını temsil eder.

Minimal bir LangGraph yapısı:

from langgraph.graph import StateGraph, START, END, MessagesState

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

builder = StateGraph(MessagesState)

builder.add_node("model", call_model)
builder.add_node("tools", tool_node)

builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model")  # döngü

graph = builder.compile()

Buradaki kritik satır:

builder.add_edge("tools", "model")

Bu satır araç çalıştıktan sonra kontrolü tekrar modele döndürür. Model yeni bir araç çağırabilir veya işi bitirebilir.

Basit bir uygulama akışı

LangGraph ile bir araç kullanan ajan kurarken tipik akış şöyledir:

1. Kullanıcı mesajını duruma ekle.
2. Model düğümünü çalıştır.
3. Model araç çağırmak istiyor mu kontrol et.
4. Araç çağrısı varsa araç düğümünü çalıştır.
5. Araç sonucunu tekrar modele gönder.
6. Model işi bitirene kadar döngüyü sürdür.

Bu akış düz kodda genelde karmaşık while ve if bloklarına dönüşür. LangGraph’ta ise akış grafikte açıkça görünür.

Kalıcılık ve döngüde insan

Uzun süren ajanlarda bellek ve kurtarma kritik hale gelir. LangGraph bunu checkpointer ile sağlar.

Basit geliştirme örneği:

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())

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

graph.invoke(
    {"messages": [user_message]},
    config
)

Burada:

• InMemorySaver geliştirme için uygundur.
• thread_id, konuşma veya iş akışını ayırt etmek için kullanılır.
• LangGraph her adımdan sonra durum anlık görüntüsü kaydedebilir.
• Sonraki çağrıda aynı thread_id ile devam edilebilir.

Üretimde yeniden başlatmalardan sonra da devam etmek istiyorsanız bellek içi kayıt yerine veritabanı destekli checkpointer kullanmanız gerekir. LangGraph bu amaçla SQLite ve Postgres gibi seçenekler sunar.

Bu yapı, döngüde insan senaryolarını da kolaylaştırır. Örneğin:

1. Ajan bir karar noktasına gelir.
2. Grafik duraklatılır.
3. Mevcut durum kullanıcıya gösterilir.
4. Kullanıcı onaylar veya düzenler.
5. Grafik aynı kontrol noktasından devam eder.

Bu model onay kapıları, manuel düzeltmeler ve hassas işlemler için kullanışlıdır.

LangGraph’ın LangChain ile ilişkisi

LangChain daha geniş bir araç kitidir:

• Model sarmalayıcıları
• Prompt şablonları
• Retriever’lar
• Belge yükleyiciler
• Sağlayıcı entegrasyonları

LangGraph ise ajanların kontrol akışını yöneten orkestrasyon katmanıdır.

LangGraph kullanmak için LangChain zorunlu değildir. Bir düğüm içinde istediğiniz model istemcisini çağırabilirsiniz. Yine de birçok ekip ikisini birlikte kullanır, çünkü LangChain’in model ve araç soyutlamaları pratik olabilir.

	LangChain	LangGraph
Rol	Bileşenler ve entegrasyonlar	Orkestrasyon ve çalışma zamanı
Kontrol akışı	Doğrusal zincirler	Döngü ve dallanmalar içeren grafikler
Yerleşik durum	Sınırlı	Paylaşımlı, tipli, kalıcı
Kalıcılık / devam etme	Odak noktası değil	Kontrol noktası kaydediciler + iş parçacığı kimlikleri
En iyi kullanım	Model çağrılarını ve araçları birleştirmek	Durum bilgisi olan, çok adımlı ajanlar

Mevcut kodları güncellerken sürüm farklarına dikkat edin. LangGraph v1.0 serisiyle birlikte bazı hazır ajan yardımcılarının içe aktarma yolları değişebilir. Eski örnekleri doğrudan kopyalamadan önce kurulu sürümünüzü ve resmi referansı kontrol edin.

Özel ajanları sıfırdan tasarlamak istiyorsanız özel bir yapay zeka ajanı oluşturma rehberine de bakabilirsiniz.

LangGraph Platform ve Studio

Açık kaynak LangGraph kütüphanesi temel geliştirme için yeterlidir. Üretime yaklaştığınızda iki ek araç önem kazanır.

LangGraph Studio

LangGraph Studio, görsel bir ajan IDE’sidir. Grafiğinizi çalıştırmanıza, düğümler arasındaki akışı izlemenize ve her adımda durumu görmenize yardımcı olur.

Döngü ve koşullu yönlendirme içeren ajanlarda bu özellikle faydalıdır. Log satırları içinde kaybolmak yerine ajanın hangi düğümden hangi düğüme geçtiğini görsel olarak takip edebilirsiniz.

LangGraph Platform

LangGraph Platform, ajanlarınızı dağıtmak için yönetilen altyapı tarafıdır. API uç noktaları, uzun süreli çalışmalar için kalıcılık ve farklı barındırma seçenekleri sunar.

LangGraph kütüphanesini kullanmak için Platform zorunlu değildir. Ancak ajanları üretimde çalıştırırken orkestrasyon altyapısını kendiniz yönetmek istemiyorsanız değerlendirebilirsiniz.

LangGraph ne zaman kullanılır?

LangGraph şu durumlarda iyi bir tercihtir:

• Ajanınız araç çağırıp sonucu kontrol ediyor ve tekrar karar veriyorsa.
• Model çıktısına göre farklı dallara gitmeniz gerekiyorsa.
• Çalışma uzun sürebiliyor ve çökme sonrası devam etmesi gerekiyorsa.
• Kullanıcı onayı veya manuel düzenleme gerekiyorsa.
• Birden fazla aktör veya alt ajan aynı durumu paylaşıyorsa.

Şu durumlarda ise gereksiz olabilir:

• Tek bir model çağrısı yapıyorsanız.
• Kısa ve doğrusal bir zincir yeterliyse.
• “Bu metni özetle” gibi basit bir görev yürütüyorsanız.

Kısacası: İş akışınız gerçekten dallanıyor ve döngü yapıyorsa LangGraph kullanın. Sadece sıralı birkaç adımınız varsa daha basit bir yapı yeterli olabilir.

API testi ve mock nerede devreye girer?

LangGraph ajanınızın güvenilirliği, çağırdığı API’lerin güvenilirliğine bağlıdır. Tipik bir ajan şunları çağırabilir:

• LLM API’si
• Arama API’si
• CRM API’si
• Kendi backend servisleriniz
• Dosya, ödeme veya bildirim servisleri

LangGraph bu çağrıları orkestre eder; ancak API sözleşmelerini test etmez. Bu ayrı bir sorumluluktur ve Apidog burada kullanılabilir.

Geliştirme sırasında iki pratik problem ortaya çıkar.

1. Canlı API çağrıları maliyetli ve yavaştır

Her test çalıştırmasında gerçek LLM veya araç API’sine gitmek:

• Token maliyeti oluşturur.
• Rate limit’e takılabilir.
• Testleri yavaşlatır.
• Deterministik olmayan sonuçlar üretir.

Bunun yerine ajanın bağlı olduğu API’yi mock’layabilirsiniz. Böylece araç uç noktası sabit, hızlı ve tahmin edilebilir yanıt döndürür.

Örneğin araç API’nizin şu yanıtı döndürdüğünü varsayın:

{
  "status": "ok",
  "customer_id": "cus_123",
  "plan": "pro"
}

Ajanınızın grafiğini geliştirirken bu yanıtı mock olarak kullanabilir ve gerçek CRM sistemine bağlanmadan yönlendirme mantığını test edebilirsiniz.

2. Yanıt şekli değişirse grafik bozulabilir

Bir araç API’si sessizce alan adını değiştirirse koşullu kenarınız yanlış veriyi okuyabilir.

Örneğin kodunuz şunu bekliyorsa:

if response["status"] == "ok":
    return "next_step"

Ancak API artık şunu döndürüyorsa:

{
  "state": "ok"
}

ajanınız yanlış dala gidebilir, erken durabilir veya döngüye girebilir.

Bu yüzden API yanıtlarını API onaylamaları ile sabitlemek önemlidir. Böylece alan değişiklikleri grafiğe ulaşmadan yakalanır.

Tam ajan odaklı test akışı için Yapay Zeka ajanları için Apidog test donanımı rehberini inceleyebilirsiniz.

Önemli ayrım şudur: Apidog ajanı orkestre etmez. LangGraph orkestrasyonu yönetir. Apidog ise ajanın çağırdığı API’leri test etmenize, mock’lamanıza ve sözleşmelerini doğrulamanıza yardımcı olur.

Sıkça sorulan sorular

LangGraph, LangChain’in yerini mi alıyor?

Hayır. LangGraph orkestrasyon çalışma zamanıdır. LangChain ise model sarmalayıcıları, prompt şablonları, retriever’lar ve entegrasyonlar gibi daha geniş bir bileşen setidir. Aynı ekip tarafından geliştirilirler, ancak ayrı kütüphanelerdir.

LangGraph’a başlamak için LangChain bilmek gerekir mi?

Hayır. Bir StateGraph tanımlayıp düğümler ve kenarlar ekleyebilir, düğüm içinde istediğiniz model istemcisini çağırabilirsiniz. LangChain entegrasyonları kullanışlıdır, ancak zorunlu değildir.

LangGraph çağrılar arasında bilgiyi nasıl hatırlar?

Checkpointer kullanarak. Grafiği bir kontrol noktası kaydediciyle derler ve çağrıda thread_id geçirirsiniz. LangGraph her adımdan sonra durum anlık görüntüsü kaydedebilir ve aynı iş parçacığı için sonraki çağrıda devam edebilir.

Ajanımın çağırdığı API’leri nasıl test ederim?

Grafikten ayrı test edin ve mock’layın. Geliştirme sırasında LLM ve araç uç noktalarını mock’layarak hızlı ve düşük maliyetli testler çalıştırın. Yanıt şemalarını assertion’larla doğrulayarak alan değişikliklerinin ajanı bozmasını engelleyin. ChatGPT API’sini test etme rehberi, kimlik doğrulama, akış ve araç çağrısı gibi ajanların sık kullandığı yüzeyleri kapsar.

Sonuç

LangGraph, döngü yapan, dallanan, kalıcılık gerektiren ve gerektiğinde insan onayı bekleyen ajanlar için net bir yapı sağlar. İş akışını paylaşımlı duruma sahip bir grafik olarak modelleyebilir, checkpointer ile bellek ve kurtarma ekleyebilir, Studio ve Platform ile hata ayıklama ve dağıtım süreçlerini destekleyebilirsiniz.

Ancak LangGraph sadece orkestrasyonu yönetir. Ajanınızın çağırdığı API’ler için ayrı bir test ve mock katmanı gerekir. Geliştirme maliyetini düşürmek, araç yanıtlarını sabitlemek ve sözleşme değişikliklerini erken yakalamak için bu API’leri Apidog ile test edip mock’layabilirsiniz. Bir uç noktayı mock’lamak ve ajanınız onu gerçek ortamda kullanmadan önce yanıtlarını doğrulamak için Apidog’u indirin.