LangGraph ile durumlu ajan akışı kurmanın adımları

LangGraph nedir, hangi sorunu çözer?

LangGraph, bir yapay zeka ajanının iş akışını bir grafik olarak tanımlamaya yarayan bir kütüphanedir. Akıştaki her adım bir düğümdür, adımlar arasındaki geçişler ise kenarlardır. Tüm düğümlerin okuyup güncelleyebildiği ortak bir durum (state) nesnesi bulunur. Bu yapı, bir dil modelinin tek bir çağrısıyla çözülemeyen işleri parçalamaya olanak tanır: önce bilgi topla, sonra karar ver, gerekirse aracı çağır, sonucu kontrol et, yetersizse döngüye gir.

Düz bir araç zinciri her adımı sabit sırayla çalıştırır. Gerçek iş akışlarında ise sıra, önceki adımın sonucuna bağlıdır. Koşullu geçişler, döngüler, paralel dallar ve bir insanın onayını bekleyen duraklar bu gereksinimin tipik örnekleridir. LangGraph, bu akışı açık bir yapı halinde çizmeye ve her adımın durumunu izlemeye imkan verdiği için kontrolü daha kolay ajanlar kurmaya yardım eder.

Temel yapı taşları

• State (durum): Akışın ortak bellek alanıdır. Çoğunlukla TypedDict ile tanımlanır; ihtiyaca göre dataclass ya da Pydantic modeli de kullanılabilir. Her anahtarın, bir düğümden gelen güncellemenin mevcut değerle nasıl birleşeceğini belirleyen bir birleştirici (reducer) işlevi olabilir. Varsayılan davranış değeri değiştirmektir; sohbet geçmişi gibi listelerde ise ekleme yapan bir birleştirici kullanılır.
• Düğümler: Durumu alıp durumun yalnızca değişen kısmını döndüren Python işlevleridir. add_node ile grafiğe eklenir.
• Kenarlar: add_edge sabit bir geçiş tanımlar. add_conditional_edges ise bir yönlendirme işleviyle durumuna göre bir sonraki düğümü seçer.
• START ve END: Akışın başlangıç ve bitiş noktalarını işaretleyen sanal düğümlerdir.
• StateGraph: Grafiği tanımladığınız sınıftır. Durum şemasıyla oluşturulur.
• compile: Grafik yapısını doğrular ve çalıştırılabilir hale getirir. Kalıcılık için kullanılan checkpointer da bu adımda verilir.

Bu bileşenlerin adları ve kullanımları resmî dokümantasyondaki grafik API anlatımıyla uyumludur; sürümler arasında ayrıntılar değişebileceğinden güncel dokümana başvurmak gerekir.

Adım adım bir ajan akışı tasarlamak

Akışı kod yazmadan önce kâğıt üzerinde çizin. Her kutu bir düğüm olsun, her ok bir geçiş. Sonra şu sırayla ilerleyin:

• Durumu tanımlayın: Akış boyunca hangi bilgileri taşımanız gerekiyor? Kullanıcı sorusu, çekilen belgeler, planın adımları, ara sonuçlar, hata sayacı gibi.
• Düğümleri yazın: Her düğüm tek bir sorumluluk taşısın: bir dil modeli çağrısı, bir araç çalıştırması, bir doğrulama ya da bir biçimlendirme.
• Geçişleri bağlayın: Sabit geçişleri add_edge ile, karara bağlı geçişleri yönlendirme işleviyle tanımlayın.
• Başlangıç ve bitişi belirleyin: START düğümünden ilk düğüme ve son düğümden END noktasına bağlayın.
• Derleyin ve çalıştırın: Grafiği compile edip önce basit girdilerle çalıştırın.
• Gözlemleyin: Her adımdan sonra durumun nasıl değiştiğini kontrol edin. Beklenmeyen yönlendirmeler çoğunlukla durum anahtarlarındaki hatalardan kaynaklanır.

Bu sıra bilinçli olarak tasarımla başlar. Doğrudan koda atlayan ekipler, grafiği sonradan tekrar şekillendirmek zorunda kalır.

Örnek: iade taleplerini inceleyen ajan

Örneğin bir e-ticaret şirketi, müşteri iade taleplerini ön değerlendiren bir ajan kurmak istiyor. Akış şöyle tasarlanır.

İlk düğüm talebi sınıflandırır: ürün hasarlı mı, yanlış mı gönderilmiş, cayma hakkı mı? İkinci düğüm sipariş sistemini sorgulayan bir aracı çağırır. Üçüncü düğüm, şirketin iade politikasını içeren belgeden ilgili bölümü getirir. Dördüncü düğüm bu bilgilerle bir karar önerisi üretir. Koşullu geçiş devreye girer: öneri açıkça politikaya uygunsa akış doğrudan yanıt düğümüne gider; sınırda bir durum varsa ya da tutar yüksekse akış, bir insanın onayını bekleyen durağa yönlendirilir. Onaydan sonra müşteri yanıtı hazırlanır ve akış END noktasına ulaşır. Araç çağrısı hata verirse durumdaki hata sayacı artırılır ve belirli bir sınıra gelince akış bir uzmana devredilir.

Bu yapı, ajanın hangi adımda ne yaptığını görünür kılar ve riskli kararı insana bırakır.

Kalıcılık ve insan onayı

Durumlu ajanların en büyük avantajı, akışın bir noktada durup sonradan devam edebilmesidir. compile sırasında bir checkpointer verildiğinde LangGraph, durumu adımlar arasında kaydeder. Her çalıştırma, yapılandırmada verilen bir thread_id ile tanımlanır. Böylece aynı kullanıcıyla yapılan konuşma kaldığı yerden sürebilir, bir hata sonrası akış baştan başlamadan yeniden denenebilir ve geçmiş durumlar incelenebilir. Bellek içinde çalışan bir checkpointer denemeler için uygundur; üretimde kalıcı bir depolama gerekir.

İnsan onayı için interrupt çağrısı kullanılır. Bir düğüm içinde interrupt çağrıldığında akış durur, bir değer dışarıya verilir. Onay geldiğinde akış, Command nesnesinin resume alanıyla devam ettirilir ve verilen değer interrupt çağrısının dönüş değeri olur. Önemli bir ayrıntı: düğüm devam ettirilirken baştan çalıştırılır; bu yüzden düğümün dış etkileri, örneğin ödeme ya da e-posta gönderimi, tekrar edildiğinde zarar vermeyecek biçimde tasarlanmalıdır.

Sık yapılan hatalar

• Her şeyi tek düğümde yapmak: Düğüm büyüdükçe akışın avantajı kaybolur. Her düğüm tek sorumluluk taşımalıdır.
• Duruma gereğinden fazla veri koymak: Büyük belge metinlerini durumda taşımak hem maliyeti artırır hem hata ayıklamayı zorlaştırır.
• Sonsuz döngü riski: Döngü içeren akışlarda çıkış koşulu ve adım sınırı tanımlanmalıdır. LangGraph, bir çalıştırma için adım sınırı koymaya imkan verir.
• Dış etkileri tekrar edilebilir bırakmak: Devam ettirme sırasında düğüm yeniden çalışabileceği için tekrar edilmesi riskli işlemler korunmalıdır.
• Yönlendirme işlevini karmaşıklaştırmak: Karar mantığı okunamaz hale gelirse akışı denetlemek zorlaşır.
• Test ve izlemeyi ertelemek: Ajanın hangi yoldan geçtiği kayıt altına alınmazsa hatalar yeniden üretilemez.

Küçük ve basit bir grafikle başlayıp aşamalı büyütmek, bu hataların çoğunu önler.

Bu beceriyi Mindset programlarında nerede çalışırsınız

Mindset kataloğundaki Agentic Workflows Mimarisi eğitimi, Agentic Workflow Kavramsal Temelleri, Workflow Tasarım Desenleri, Durum Yönetimi ve Kalıcılık, Araç Ekosistemi ve Entegrasyonlar ile Güvenlik, Yönetişim ve Uyum modüllerini içerir. Bu başlıklar, bu sayfadaki durum, kalıcılık ve kontrol konularıyla doğrudan ilişkilidir ve araçtan bağımsız bir mimari bakış sağlar.

Python ile Yapay Zekâ Ajanları (AI Agent) Geliştirme Eğitimi ise Tek Ajanlı Sistemler Kurma, Çoklu Ajanlarla Çalışma, Ajanları Araçlarla Donatma ve Ajan Sistemlerinde İzleme, Gözlemlenebilirlik ve Değerlendirme modüllerini kapsar. Yazılım ve veri ekipleri, kendi iş akışlarını ajan olarak kurmak için bu başlıkları uygulama temeli olarak kullanabilir. Bu eğitimlerin modül başlıklarında LangGraph adı geçmemektedir; konu araçtan bağımsız ilkelerle işlenir.