Çoğu ajan kodu basit başlar ve ardından kendi yeniden denemeleri altında çöker. Bir LLM'i bağlarsınız, ona bazı araçlar verirsiniz ve iş akışının döngü yapması, dallanması veya bir insan için duraklaması gerektiği anda, düz hatlı komut dosyası dağılır. LangGraph tam da bu karmaşa için oluşturulmuş bir çerçevedir: bir ajanı paylaşımlı duruma sahip bir grafik olarak modeller, böylece döngüler ve dallanmalar karışık if ifadeleri yerine birinci sınıf yapılar haline gelir. Bu kılavuz, LangGraph'ın ne olduğunu, çözdüğü sorunu ve ajanınız gerçek servisleri çağırdığında API testinin nerede devreye girdiğini açıklar.
LangGraph nedir
LangGraph, uzun süre çalışan, durum bilgisi olan ajanlar oluşturmak için 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 kendi odak noktası olan ayrı bir kütüphanedir. pip install -U langgraph komutuyla ayrı olarak kurarsınız ve LangChain ekosisteminin geri kalanı olmadan kullanabilirsiniz.
Temel fikir basittir. Ajanınızı bir grafik olarak tanımlarsınız. Düğümler iş yapar (bir modeli çağırır, bir aracı çalıştırır, veriyi dönüştürür). Kenarlar neyin sonra çalışacağına karar verir. Paylaşımlı bir durum nesnesi her düğümden akar ve her düğüm onu okuyup ona geri yazabilir. Kenarlar geriye doğru işaret edebildiği için grafik döngü yapabilir. Bu, basit bir zincirin iyi yapamadığı kısımdır.
LangChain'in eski Chain soyutlamasını kullandıysanız, fark kontrol akışının şeklindedir. Bir zincir bir ardışık düzen gibidir: birinci adım, ikinci adım, üçüncü adım, bitti. Bir grafik, bir düğümün mevcut durumu incelemesine, ardından farklı bir dala atlamasına, yeniden denemek için geri dönmesine veya paralel çalışan ve sonuçlarını birleştiren birkaç düğüme yayılmasına olanak tanır. Gerçek ajanların buna ihtiyacı vardır, çünkü "akıl yürüt, hareket et, gözlemle, tekrar akıl yürüt" bir döngüdür, bir çizgi değil.
LangGraph'ın çözdüğü sorun
Ajan tabanlı iş akışları doğası gereği döngüseldir. Bir ajan bir aracı çağırır, sonuca bakar, işin bitip bitmediğine karar verir ve bitmediyse tekrar dener. Bunu iç içe koşullu ifadelerle modellemek hızla okunaksız hale gelir ve üretim ajanlarının gerçekten ihtiyaç duyduğu şeyleri eklediğinizde daha da kötüleşir:
- Durma koşullu döngüler. Görev tamamlanana kadar araçları çağırmaya devam edin, sonsuza kadar dönmeden.
- Duruma göre dallanma. Modelin döndürdüğü şeye bağlı olarak farklı bir düğüme yönlendirme.
- Kalıcılık. Bir çökmeden, zaman aşımından veya yeniden başlatmadan kurtulun ve son iyi noktadan devam edin.
- Döngüde insan. Duraklatın, bir kişinin durumu incelemesine veya düzenlemesine izin verin, ardından devam edin.
- Akış. Belirteçleri ve ara adımları sadece sonunda değil, gerçekleştikçe yayınlayın.
LangGraph, bunların her birini el yapımı bir şey yerine yerleşik bir yeteneğe dönüştürür. Dayanıklı yürütmeye sahip bir durum makinesi elde edersiniz, böylece bir ajan dakikalarca veya saatlerce çalışabilir ve kaldığı yerden devam edebilir.
Temel kavramlar: grafik, durum, düğümler, kenarlar
Dört temel öğe çerçevenin çoğunu taşır. İşte nasıl bir araya geldikleri.
Durum, tüm çalışma boyunca paylaşılan, tipli bir nesnedir. Şeklini bir şema ile, genellikle bir TypedDict ile tanımlarsınız ve LangGraph her düğümün güncellemelerini buna birleştirir. Yaygın bir başlangıç noktası, çalışan bir sohbet mesajları listesini tutan önceden oluşturulmuş bir şema olan MessagesState'tir.
Düğümler fonksiyonlardır. Her biri mevcut durumu alır ve kısmi bir güncelleme döndürür. Onları add_node() ile kaydedersiniz.
Kenarlar düğümleri birbirine bağlar. add_edge() ile normal bir kenar her zaman A'dan B'ye gider. add_conditional_edges() ile koşullu bir kenar, durumu okuyan ve bir sonraki düğümün adını döndüren bir yönlendirme fonksiyonu çalıştırır; bu, "model bir araç istediğinde, onu çalıştır; aksi takdirde bitir" ifadesini nasıl belirttiğinizdir.
START ve END, yürütmenin başladığı ve durduğu özel işaretleyicilerdir.
İşte minimal bir grafiğin şekli. Pseudo-kod düzeyindedir, ancak API adları gerçektir.
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") # loop back
graph = builder.compile()
add_edge("tools", "model") satırı döngüdür. Araçlar çalıştıktan sonra, kontrol modele geri döner ve model daha fazla araç çağırabilir veya durabilir. Bu döngü, LangGraph'ın var olmasının tüm nedenidir.
Kalıcılık ve döngüde insan
Bir kontrol noktası kaydedici (checkpointer) ile bir grafik derleyin, her adımdan sonra durumun bir anlık görüntüsünü kaydeder. Yapılandırmada bir thread_id geçirin ve LangGraph, o iş parçacığı için bir sonraki çağrıda en son kontrol noktasını geri yükler. Düğümleriniz değişmez; çalışma zamanı kaydetme ve geri yüklemeyi yönetir.
from langgraph.checkpoint.memory import InMemorySaver
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)
InMemorySaver geliştirme için iyidir. Yeniden başlatmalardan sağ çıkan bir şey için LangGraph, veritabanı destekli kaydediciler sunar (tek bir sunucu için SQLite, çoklu örnek ölçeği için Postgres). Durum kalıcı olduğu için, neredeyse ücretsiz olarak döngüde insan özelliğini de elde edersiniz. Grafiği seçilen bir noktada kesintiye uğratabilir, mevcut durumu bir kişinin incelemesi veya düzenlemesi için gösterebilir ve ardından tam o kontrol noktasından devam edebilirsiniz. Onay kapıları, manuel düzeltmeler ve "emin misiniz?" adımlarının hepsi bunun üzerine kuruludur.
Akış, bunu tamamlar. LangGraph, çalışma ilerledikçe model belirteçlerini ve düğüm düzeyindeki güncellemeleri akışla sağlayabilir, böylece bir kullanıcı arayüzü, bir dönen simgeye bakmak yerine ajanın düşündüğünü gösterebilir.
LangGraph'ın LangChain ile ilişkisi
Bu insanları yanıltıyor, bu yüzden doğrudan konuşalım. LangChain daha geniş araç kitidir: model sarmalayıcıları, istem şablonları, alıcılar, belge yükleyiciler ve yüzlerce sağlayıcıyla entegrasyonlar. LangGraph, bu araç kitinin ajan bölümlerinin altındaki orkestrasyon katmanıdır.
LangGraph'ı kullanmak için LangChain'e ihtiyacınız yok. Durumunuzu, düğümlerinizi ve kenarlarınızı tanımlayabilir ve bir düğüm içinde istediğiniz herhangi bir model istemcisini çağırabilirsiniz. Birçok ekip ikisini birlikte kullanır, çünkü LangChain'in model ve araç soyutlamaları kullanışlıdır ve LangGraph'ın önceden oluşturulmuş create_react_agent yardımcısı (langgraph.prebuilt içinde), özel bir grafiğe ihtiyacınız olmadığında size birkaç satırda çalışan bir araç çağıran ajan sunar.
| 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 kullanıcılar için bir not: LangGraph v1.0 serisi (2025 sonlarından beri kararlı), önceden oluşturulmuş ajan yardımcısını langchain.agents.create_agent'a doğru kaydırmaktadır, bu nedenle eski kod parçalarını kopyalamadan önce tam içe aktarma yolu için kurulu sürümünüzü ve resmi referansı kontrol edin. Baştan özel ajanlar oluşturmak da burada faydalı bir beceridir; daha geniş bir resim için özel bir yapay zeka ajanı oluşturma konulu rehberimize bakın.
LangGraph Platform ve Studio
Açık kaynak kütüphane çekirdeği oluşturur, ancak ürünü piyasaya sürdüğünüzde iki bitişik ürün önem kazanır.
LangGraph Studio, görsel bir ajan IDE'sidir. Grafiğinizi oluşturur, çalıştırmanıza olanak tanır ve her düğümdeki durumu gösterir, böylece yürütmenin düğümleriniz ve kenarlarınız arasında nasıl adım adım ilerlediğini izleyebilirsiniz. Döngüler ve koşullu yönlendirme içeren her şey için, ajanın gerçekten izlediği yolu görmek, günlük satırlarını okumaktan daha iyidir.
LangGraph Platform, yönetilen dağıtım tarafıdır: ajanlarınız için API uç noktaları, uzun süreli çalışmalar için yerleşik kalıcılık ve kendi kendine barındırılanlardan bulutta tam olarak yönetilenlere kadar değişen barındırma seçenekleri. Kütüphaneyi kullanmak için buna ihtiyacınız yok; ajanlar için kendi başınıza çalıştırmak yerine üretimde altyapı istediğinizde mevcuttur.
LangGraph ne zaman kullanılır
Ajanınızın gerçek bir kontrol akışı olduğunda LangGraph'a başvurun. İyi sinyaller:
- İş bir dizi değil, bir döngüden ibaret (araçları çağır, kontrol et, tekrarla).
- Modelin neye karar verdiğine göre dallanmanız gerekiyor.
- Bir çalışma uzun sürebilir ve bir çökmeden kurtulup devam etmesini istiyorsunuz.
- Bir insan, çalışma sırasında bir şeyi onaylamalı veya düzenlemelidir.
- Durumu paylaşan birden çok aktör veya alt ajanı koordine ediyorsunuz.
Tek bir model çağrısı veya kısa doğrusal bir zincir işi hallettiğinde atlayın. "Bu metni özetle" gibi durumlar için bir grafik, ihtiyacınız olmayan bir ek yüktür. Yapıyı gerçekten dallanan ve döngü yapan iş akışları için saklayın.
API testi ve sahtesinin nerede devreye girdiği
Geliştirmede ekipleri zorlayan kısım burası. Bir LangGraph ajanı, yalnızca çağırdığı API'ler kadar güvenilirdir ve birçok API'yi çağırır: LLM uç noktası, ayrıca her araç API'si (arama, bir CRM, kendi arka ucunuz). LangGraph bu çağrıları orkestre eder; onları test etmez. Bu ayrı bir iştir ve Apidog burada devreye girer.
Hızla iki sorun ortaya çıkar. Birincisi, her test çalıştırmasında canlı API'lere vurmak belirteçleri yakar ve hız limitlerini aşar. Bir ajanın bağlı olduğu API'yi taklit edebilirsiniz, böylece bir araç uç noktası, grafik mantığı üzerinde çalışırken deterministik, anında bir yanıt döndürür. LLM uç noktasını aynı şekilde taklit edin ve yalnızca yönlendirmeyi test etmek için belirteçlere para ödemeyi bırakırsınız.
İkincisi, düğümleriniz bir yanıt şekli varsayar. Bir aracın API'si sessizce bir alan adını değiştirirse, koşullu kenarınız yanlış şeyi okur ve ajan döngüye girer veya durur. Bu sözleşmeleri API onaylamaları ile sabitlemek, grafiğinize ulaşmadan önce sapmaları yakalar. Ve ajanlar hazırlık ve üretim ortamlarında anahtarları kullandığı için, bunları ortamlarda yönetmek sırları düğüm kodunuzdan uzak tutar. Tam ajan odaklı iş akışını istiyorsanız, Yapay Zeka ajanları için Apidog test donanımı bunu baştan sona anlatır. Açık olmak gerekirse, bunların hiçbiri ajanı orkestre etmez; Apidog, altındaki API'leri test eder ve taklit eder.
Sıkça sorulan sorular
LangGraph, LangChain'in yerini mi alıyor? Hayır. LangGraph, orkestrasyon çalışma zamanıdır; LangChain ise daha geniş bileşenler ve entegrasyonlar kümesidir. Aynı ekipten ayrı kütüphanelerdir ve LangGraph'ı LangChain olmadan çalıştırabilir veya ikisini birlikte kullanabilirsiniz. LangGraph, basit zincirlerin zorlandığı durum bilgisi olan, döngüsel kontrol akışını yönetir.
LangGraph'a başlamak için LangChain'i bilmem gerekiyor mu? Hayır. Bir StateGraph tanımlayabilir, düğümler ve kenarlar ekleyebilir ve bir düğüm içinde istediğiniz herhangi bir model istemcisini çağırabilirsiniz. LangChain'in model sarmalayıcıları kullanışlıdır, ancak isteğe bağlıdır. Temel grafik ilkeleriyle başlayın ve geri kalanını yalnızca ihtiyacınız olduğunda ekleyin.
LangGraph çağrılar arasında nasıl bilgi hatırlar? Kontrol noktası kaydediciler (checkpointers) aracılığıyla. Grafiğinizi bir kontrol noktası kaydedici ile derleyin ve bir thread_id geçirin, LangGraph her adımdan sonra bir durum anlık görüntüsü kaydeder ve ardından o iş parçacığı için bir sonraki çağrıda geri yükler. Konuşma belleği ve çökme kurtarmayı, düğüm mantığınızı değiştirmeden bu şekilde elde edersiniz.
Ajanımın çağırdığı API'leri nasıl test ederim? Grafikten ayrı olarak test edin ve taklit edin. Geliştirme sırasında çalıştırmaların hızlı ve ücretsiz olması için LLM ve araç uç noktalarını taklit edin ve değiştirilen bir alanın bir düğümü bozmaması için yanıt şekillerini onaylayın. ChatGPT API'sini test etme hakkındaki kılavuzumuz, bir ajanın bağlı olduğu tam yüzeyler olan kimlik doğrulama, akış ve araç çağrılarını kapsar.
Sonuç
LangGraph, döngü yapan, dallanan, kalıcılık sağlayan ve bir insan için duraklayan ajanlar için eksik yapıyı size sunar. İş akışını paylaşımlı duruma sahip bir grafik olarak modelleyin, bellek ve kurtarma için kontrol noktası kaydedicilere güvenin ve hata ayıklama ve dağıtıma hazır olduğunuzda Studio ve Platformu kullanın. Çerçeve orkestrasyonu yönetir. Ajanınızın çağırdığı API'lerin hala kendi güvenlik ağına ihtiyacı vardır, bu nedenle geliştirmeyi ucuz tutmak ve araç sözleşmelerinizi dürüst tutmak için onları Apidog'da taklit edin ve test edin. Bir uç noktayı taklit etmek ve ajanınız onu gerçekte kullanmadan önce yanıtlarını onaylamak için Apidog'u indirin.