LangGraph 1.2.10 ile İnsan Onaylı Destek Akışı: Kurulum ve Gerçek Test

Kısa sonuç: LangGraph 1.2.10, “tek istem gönder, cevap al” kalıbından daha denetlenebilir bir otomasyon kurmak isteyenler için düşük seviyeli bir grafik çalışma zamanıdır. 3 Ağustos 2026’da macOS üzerinde Python 3.13 ile kurduk; erişilebilirlik destek talebini maskeleyen, önceliklendiren, yüksek riskte insan onayı isteyen ve kaldığı yerden devam eden anahtarsız bir örnek çalıştırdık. Örnek bir dil modeli kullanmadığı için ücretsiz ve tekrarlanabilir; aynı mimariye daha sonra istediğiniz yerel ya da bulut modelini ekleyebilirsiniz.

LangGraph ne işe yarar, kimler için?

LangGraph, bir ajanın veya iş akışının adımlarını düğümler, geçişlerini de kenarlar olarak tanımlar. Durum verisi adımlar arasında taşınır. Böylece modelin her şeyi tek seferde yapmasını beklemek yerine “kişisel veriyi maskele, sınıflandır, gerekiyorsa insana sor, sonra hedef sisteme yaz” gibi sınırları görünür bir süreç kurabilirsiniz.

Bu yaklaşım; destek operasyonu, belge yönlendirme, onay gerektiren içerik üretimi ve uzun süren araç görevleri geliştiren Python ekiplerine uygun. Yalnız sohbet kutusu isteyen son kullanıcı içinse fazla düşük seviyeli kalır: hazır masaüstü arayüzü yoktur ve grafik, veri deposu ile model bağlantısını geliştirici kurar.

Mimari: model değil, denetim katmanı

LangGraph’ın çekirdeği modelden bağımsızdır. Bir düğüm normal Python işlevi, bir dil modeli çağrısı veya izinli bir araç olabilir. Koşullu kenar, hangi düğümün sırada çalışacağını seçer. Checkpointer, aynı thread_id için durumu saklar; interrupt() yürütmeyi durdurup insana soru verir; Command(resume=...) aynı akışı sürdürür.

Bu ayrım izinleri daraltmayı kolaylaştırır. Örneğin maskeleme düğümü yalnız metni okuyabilir, sınıflandırıcı dış ağa çıkamaz, son düğüm yalnız destek kuyruğuna yazabilir. Gözlemlenebilirlik için her düğümün giriş, çıkış, süre ve hata kodunu kişisel veriyi ayıklayarak kaydedebilirsiniz. LangSmith izleme seçeneği vardır; ancak çekirdeği çalıştırmak için LangSmith hesabı zorunlu değildir.

Kurulum: Python sürümünü önce kontrol edin

LangGraph 1.2.10, Python 3.10 veya üstünü istiyor. İlk denememiz macOS’un Python 3.9.6 sürümünde bu koşul nedeniyle kurulmadan durdu. Python 3.13.12 ile temiz sanal ortamda kurulum ve bağımlılık denetimi başarılı oldu:

python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "langgraph==1.2.10" \
  "langgraph-checkpoint-sqlite==3.1.1"
python -m pip check

Sürüm sabitlemek, bugün çalışan örneğin yarın farklı bir bağımlılık çözümüyle değişmesini önler. SQLite eklentisi, kalıcı yerel kontrol noktaları kuracak ekipler içindir; aşağıdaki küçük örnek, ayrıca dosya oluşturmamak için RAM içindeki InMemorySaver ile çalışır.

Adım adım gerçek kullanım: erişilebilirlik talebini yönlendirme

1. Kullanıcının destek metni maskele düğümüne girer; e-posta adresi model veya kayıt sistemine ulaşmadan silinir.
2. onceliklendir, ekran okuyucu, ödeme, giriş ve veri sızıntısı gibi yerel kuralları kontrol eder.
3. Normal talep doğrudan yanıt kuyruğuna gider. Yüksek öncelik insan_onayi düğümünde durur.
4. İnceleyen kişi soruyu, maskelenmiş talebi ve istenen izni görür; “onaylandı” kararıyla aynı iş parçacığını sürdürür.
5. Son düğüm hedef ekibi ve karar kaydını üretir. Gerçek sistemde bu düğüm, yalnız tek bir kuyruğa yazabilen dar kapsamlı bir araçla değiştirilir.

Çalışan örnek kod

import re
from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import START, END, StateGraph
from langgraph.types import Command, interrupt

class Durum(TypedDict, total=False):
    metin: str
    temiz: str
    oncelik: str
    karar: str
    sonuc: str

def maskele(s):
    temiz = re.sub(r"[\w.+-]+@[\w.-]+", "[E-POSTA MASKELENDI]", s["metin"])
    return {"temiz": temiz}

def siniflandir(s):
    sinyaller = ("ekran okuyucu", "ödeme", "giriş yapamıyorum", "veri sızıntısı")
    return {"oncelik": "yüksek" if any(x in s["temiz"].lower() for x in sinyaller) else "normal"}

def rota(s):
    return "onay" if s["oncelik"] == "yüksek" else "sonuc"

def onay(s):
    karar = interrupt({"soru": "Erişilebilirlik ekibine aktarılsın mı?", "talep": s["temiz"]})
    return {"karar": str(karar)}

def sonuc(s):
    hedef = "erişilebilirlik ekibi" if s["oncelik"] == "yüksek" else "genel destek"
    return {"sonuc": f"Hedef: {hedef}; karar: {s.get('karar', 'gerekmiyor')}"}

g = StateGraph(Durum)
for ad, islev in [("maskele", maskele), ("siniflandir", siniflandir),
                   ("onay", onay), ("sonuc", sonuc)]:
    g.add_node(ad, islev)
g.add_edge(START, "maskele")
g.add_edge("maskele", "siniflandir")
g.add_conditional_edges("siniflandir", rota)
g.add_edge("onay", "sonuc")
g.add_edge("sonuc", END)

grafik = g.compile(checkpointer=InMemorySaver())
ayar = {"configurable": {"thread_id": "destek-001"}}
ilk = grafik.invoke({"metin": "Ekran okuyucu ödeme düğmesine ulaşamıyor. Hesap: ali@example.com"}, ayar)
print(ilk["__interrupt__"][0].value)
son = grafik.invoke(Command(resume="onaylandı"), ayar)
print(son["sonuc"])

Gerçek çıktıda onay sorusu maskelenmiş metinle gösterildi; devam komutundan sonra “Durum: yüksek; hedef: erişilebilirlik ekibi; insan kararı: onaylandı” sonucu alındı. pip check bozuk bağımlılık bildirmedi. Dil modeli, bulut hesabı ve API anahtarı kullanılmadı.

Model ve araç bağlantısını güvenli ekleme

Bir model ekleyecekseniz onu maskelemeden sonraki ayrı bir düğüme koyun. Model yalnız temiz metni ve gerekli alanları görsün; ağ erişimi olmayan yerel model, hassas veride daha kontrollü olabilir. Araç çağrısı için serbest kabuk, tam dosya sistemi veya genel amaçlı veritabanı anahtarı vermeyin. “Destek kaydı oluştur” gibi şeması doğrulanan, hedefi sabit ve geri alınabilir araçlar tanımlayın.

İnsan onayını sadece ekranda bir düğme olarak düşünmeyin: onay veren kimlik, gösterilen özet, izin kapsamı, zaman ve son işlem denetlenebilir kayda girmeli. Akış yeniden başladığında aynı düğümün yan etkisini iki kez üretmemesi için e-posta gönderme veya kayıt açma adımlarına benzersiz işlem anahtarı ekleyin.

Arayüz ve erişilebilirlik notları

LangGraph kendi başına son kullanıcı arayüzü sunmaz. Komut satırı çıktısını etiketli ve satır bazlı vermek ekran okuyucuda anlaşılır; yalnız renk, hareketli ilerleme göstergesi veya ASCII diyagramına güvenmeyin. İnsan onayı arayüzünde açık bir başlık, talep özeti, “Onayla” ve “Reddet” adlı gerçek düğmeler, odak göstergesi ve karar sonrası canlı durum iletisi bulunmalı. Klavye odağı sayfa açılır açılmaz tehlikeli “Onayla” düğmesine taşınmamalı.

Hata ile onay bekleme durumu görsel olarak aynı görünmemeli. Ekran okuyucuya “İşlem duraklatıldı; insan kararı bekleniyor” metni sunun. Ham grafik durumu kişisel veri içerebileceği için indirilebilir günlükleri rol bazlı kısıtlayın ve saklama süresi belirleyin.

Alternatiflerle karşılaştırma

LangGraph, durum ve geçişleri ayrıntılı denetlemek isteyen geliştiriciye uygundur. CrewAI rol ve görev tabanlı çoklu ajan başlangıcını daha hızlı kurabilir; AutoGen konuşan ajanlar ve olay tabanlı çoklu ajan örüntülerine odaklanır. Basit, kısa ve yan etkisiz bir süreçte ise bu çerçevelerin hiçbiri gerekmeyebilir: düz Python işlevleri ve bir görev kuyruğu daha az bağımlılıkla yeterli olabilir. Görsel sürükle-bırak arayüzü arayanlar Flowise veya Dify’ı değerlendirebilir; buna karşılık kod incelemesi ve test edilebilir durum geçişleri LangGraph’ın güçlü tarafıdır.

Güvenlik, gizlilik ve maliyet

Depodaki gerçek LICENSE dosyası MIT metnidir: kullanım, değiştirme ve dağıtıma geniş izin verir; telif ve lisans bildiriminin korunmasını ister. Bu, bağlı modelin, veri kümesinin, LangSmith hizmetinin veya başka bir aracın da MIT olduğu anlamına gelmez. MIT lisansı ayrıca güvenlik veya bakım garantisi değildir.

GitHub güvenlik duyurularında eski sürümleri etkileyen ciddi sınıflar var: güvenilmeyen checkpoint verisinin güvensiz serileştirilmesi, SDK URL yolu oluşturma sorunları ve SQLite/Postgres ad alanı önek eşleşmesi. Test ortamımızdaki langgraph 1.2.10, langgraph-checkpoint 4.1.1, langgraph-sdk 0.4.2 ve langgraph-checkpoint-sqlite 3.1.1 duyurulardaki etkilenen aralıkların üstünde. Yine de üretimde bağımlılık taraması, imzalı dağıtım süreci ve güvenilmeyen eski checkpoint’leri içe aktarmama kuralı gerekir.

Çekirdek açık kaynak olduğundan örneğimizin yazılım ve model çağrısı maliyeti sıfırdı. Gerçek maliyet; model tokenları, kalıcı veritabanı, izleme, çalışan süresi ve dış araçlardan gelir. Her düğüm için çağrı ve bütçe sınırı koymak, tek bir ajan döngüsünün faturayı büyütmesini engeller.

Sınırlamalar ve bakım durumu

GitHub deposu arşivlenmiş değil; 30 Temmuz’da checkpoint SQLite ve Postgres 3.1.1 sürümleri yayımlandı, son commitler güvenlik düzeltmesi ve bağımlılık bakımı içeriyor. Ancak açık issue sayısı yüksek ve güncel raporlar arasında ToolNode eşzamanlılık sınırının göz ardı edilmesi, iptal sırasında henüz checkpoint’e yazılmamış akış durumunun kaybı ve bazı paket sürümü çakışmaları bulunuyor. Bunlar projenin kullanılamaz olduğunu değil, yükseltme öncesi regresyon testi gerektiğini gösterir.

Örneğimiz RAM içi checkpointer ile tek süreçte test edildi. SQLite veya Postgres ile çökme sonrası yeniden başlatma, dağıtık çalışan, LangSmith arayüzü ve gerçek bir LLM çağrısı test edilmedi. Üretim kararı bu sınırlı testten çıkarılmamalı.

Sorun giderme

• “No matching distribution”: python --version çıktısı 3.10’dan düşükse yeni Python ile sanal ortamı yeniden oluşturun.
• Akış onaydan sonra başlamıyor: ilk çağrı ve Command(resume=...) için aynı thread_id ve aynı checkpointer kullanılmalı.
• Düğüm iki kez yan etki üretiyor: yeniden yürütme ihtimaline karşı işlem kimliği saklayın; dış yazmayı idempotent yapın.
• Gizli veri günlükte: maskelemeyi model, izleme ve araç düğümlerinden önce çalıştırın; ham state kaydını kapatın.
• Yükseltme bağımlılıkları bozuyor: sürümleri kilitleyin, pip check ve örnek grafik testini CI içinde çalıştırın.

Kaynaklar

• LangGraph GitHub deposu — README, commitler, issue’lar ve depo durumu; erişim: 3 Ağustos 2026.
• LangGraph 1.2.10 sürümü — 28 Temmuz 2026.
• PyPI: langgraph 1.2.10 — Python koşulu ve paket bağımlılıkları; erişim: 3 Ağustos 2026.
• 1.2.10 etiketindeki MIT LICENSE — lisans metni.
• Resmî LangGraph genel bakışı — dayanıklı yürütme, bellek ve insan denetimi.
• Resmî interrupt belgesi — duraklatma ve sürdürme.
• GHSA-47pj-3jcm-6whg — SQLite/Postgres ad alanı düzeltmesi, 30 Temmuz 2026.
• LangGraph güvenlik duyuruları — etkilenen paket ve sürüm aralıkları; erişim: 3 Ağustos 2026.