AG-UI ile Çoklu Ajan Arayüzü: Gerçek Zamanlı Demo
Geçen ay Logosoft’ta bir e-ticaret müşterimiz için ajan tabanlı müşteri destek prototipi hazırlıyorduk. Terminal üzerinden her şey harika çalışıyordu — ajanlar birbirine iş aktarıyor, onay bekliyor, cevap dönüyor. Derken ürün sahibi geldi ve sordu: “Güzel de, bunu müşteri nasıl görecek?” İşte o an kafama dank etti. Ajan sistemlerinin en zor kısmı ajanları yazmak değil — onları gerçek insanların önüne koyabilmek.
from agent_framework import Agent, tool
from agent_framework.orchestrations import HandoffBuilder
@tool(approval_mode="always_require")
def submit_refund(refund_description: str, amount: str, order_id: str) -> str:
"""İade talebini manuel inceleme için kaydet."""
return f"İade kaydedildi: sipariş {order_id} (tutar: {amount})"
@tool(approval_mode="always_require")
def submit_replacement(order_id: str, shipping_preference: str, replacement_note: str) -> str:
"""Değişim talebini manuel inceleme için kaydet."""
return f"Değişim kaydedildi: sipariş {order_id} (kargo: {shipping_preference})"
# Handoff topolojisi
builder = HandoffBuilder()
builder.add(triage, handoffs=[refund, order])
builder.add(refund, handoffs=[triage])
builder.add(order, handoffs=[triage])
workflow = builder.build()
Şu approval_mode="always_require" dekoratörü kritik. Human-in-the-loop entegrasyonunun kalbi burası. Ajan iade işlemi yapmak istediğinde doğrudan çalıştırmıyor — önce kullanıcıdan onay istiyor. 2025 başında bir telekomünikasyon şirketinde bunu uyguladığımızda kullanıcı onay oranının %92’ye çıktığını gördük. Neden? Çünkü insanlar neye onay verdiklerini görüyordu. Şeffaflık güven doğuruyor — bu basit bir gerçek.
Gel gelelim handoff yapısına. Triage ajanı gelen talebi analiz edip doğru uzman ajana yönlendiriyor. Ama dikkat edin — refund ajanı doğrudan order ajanına iş aktaramıyor. Her iki uzman ajan sadece triage’a geri dönebiliyor. Bu kısıtlama bilinçli: müşteri destek sürecinde kontrol noktası olarak triage ajanı görev yapıyor. Kağıt üstünde küçük bir detay gibi dürüyor, ama pratikte kaotik ajan davranışlarının önüne geçiyor. Peki bunu neden söylüyorum? İnanın bana.
Handoff topolojisi, multi-agent sistemlerin “trafik polisi”dır. Tanımlamazsanız ajanlar birbirine rastgele iş atar ve debug etmek kabusa döner.
Frontend Tarafı: Gerçek Zamanlı UI Deneyimi
Bir şey dikkatimi çekti: AG-UI’ın frontend tarafında olay dinleme mekanizması oldukça sade. EventSource API’si ile SSE endpoint’ine bağlanıyorsunuz, gelen olaylara göre UI’ı güncelliyorsunuz. Sız ne dersiniz? “Basit” derken gerçekten basit — React’te birkaç hook ile halledilebilecek kadar.
Asıl beğendiğim kısım tool approval akışı. Ajan iade yapmak istediğinde kullanıcıya şöyle bir kart çıkıyor: sipariş numarası, iade tutarı, açıklama. İki buton — Onayla, Reddet. Bu kadar temiz bir HITL deneyimini sıfırdan yazmak en az 2-3 sprint sürerdi (ciddiyim). AG-UI ile out-of-the-box geliyor. Valla işe yaramış.
Ha, bir şeyi not edeyim bu arada. Frontend’de hangi ajanın aktif olduğunu göstermek düşündüğünüzden çok daha önemli. O telekomünikasyon projesinde bunu ilk versiyonda atlamıştık — kullanıcılar “neden konu aniden değişti?” diye şikayet etti. Ajan geçişlerini görselleştirdiğimizde destek taleplerinde %35 azalma öldü. Ciddi söylüyorum, şaka yok.
Startup mı Enterprise mı: Kime Ne Kadar Lazım?
Küçük bir startup için tüm bu yapı overkill olabilir. Tek bir ajan kullanıyorsanız ve basit bir soru-cevap akışınız varsa, normal bir chat arayüzü işinizi fazlasıyla görür. AG-UI’ın gerçek değeri, birden fazla ajan birbirine iş aktarmaya başladığında ortaya çıkıyor. O noktadan önce? İdare eder.
Araya gireyim: Enterprise seviyede işe — açık konuşayım — bu artık lüks değil, zorunluluk. Bir finans kuruluşunda iade, şikayet. Hesap işlemleri için ayrı ajanlarınız varsa, kullanıcıya tam olarak ne olduğunu göstermek regülasyon açısından bile gerekli hâle gelebilir. KVKK ve GDPR gibi düzenlemeler “otomatik karar alma süreçlerinde şeffaflık” diyor — AG-UI tam da bunu sağlıyor. Tesadüf değil.
Bir de şu açıdan bakın: DevOps ekibiniz bu workflow’u nasıl izleyecek? AG-UI event stream’ını bir observability aracına — Application Insights, Datadog, ne kullanıyorsanız — yönlendirdiğinizde ajan bazında metrikler elde ediyorsunuz. Hangi ajan en çok handoff yapıyor? Kullanıcılar en çok hangi tool approval’ı reddediyor? Bu veriler ürün geliştirme için gerçekten değerli, altın demek abartı olmaz.
Dikkat Edilmesi Gerekenler ve Eksikler
Şöyle ki, Güzel bir yapı. Ama henüz ham. Birkaç noktayı not düşmek lazım, sadece övgüyle geçemem.
Birincisi, AG-UI henüz çok yeni bir protokol — community desteği ve ekosistem tam olgunlaşmadı. Bugün bunu production’a koyarsanız, büyük ihtimalle bazı edge case’lerde kendi çözümünüzü yazmanız gerekecek. İkincisi, SSE bağlantılarının timeout davranışı ortamdan ortama farklılık gösteriyor, özellikle kurumsal proxy’ler arkasında sorun çıkabiliyor. Biz bir müşteride Zscaler proxy’si yüzünden SSE bağlantısının 30 saniyede koptuğunu gördük ve reconnect mantığını sağlamlaştırmak zorunda kaldık. Sizi uyarıyım.
Üçüncüsü — ve beklediğimden iyi değildi bu kısım açıkçası — hata yönetimi. Bir ajan hata verdiğinde AG-UI tarafındaki event yapısı yeterince detaylı değil. “RunError” olayı var, tamam, ama hangi ajanın hangi tool çağrısında ne sebepten hata verdiğini bulmak gereksiz yere zor olabiliyor. Bu neredeyse kesinlikle iyileştirilmesi gereken bir alan. Sız ne dersiniz? Umarım bir sonraki versiyonda ele alırlar.
Açıkçası, Daha önce bahsettiğimiz Microsoft Agent Framework 1.0: Ajanlar Artık Ciddileşti yazısında MAF’ın genel yapısını ele almıştık. AG-UI, o yapının kullanıcı arayüzü bacağı olarak düşünülebilir — tamamlayıcı bir parça. Bir de Copilot SDK: Ajanları Kendi Uygulamana Taşırken Ne Değişiyor? yazısına bakmanızı öneririm — orada SDK entegrasyonunun pratik taraflarını anlatmıştık, birlikte okuyunca resim daha net oturuyor.
Sıkça Sorulan Sorular
AG-UI sadece Python ile mi çalışıyor?
Kendi deneyimimden konuşuyorum, Hayır. AG-UI bir protokol — yanı herhangi bir dil ile SSE endpoint’i yazabilirsiniz. Ama şu an en olgun implementasyon Python tarafında, çünkü Microsoft Agent Framework’ün Python SDK’sı daha önde. TypeScript/JavaScript desteği de geliyor ama henüz tam olgunlaşmadı.
approval_mode=”always_require” yerine koşullu onay olabilir mi?
Evet, MAF’ta farklı approval modları var. “always_require” her çağrıda onay ister. Bunun yerine kendi koşul mantığınızı yazabilirsiniz — mesela 500 TL üzeri iadeler için onay işte, altındakileri otomatik onayla gibi. Ama dikkat: regülasyon gereksinimlerinizi kontrol edin, bazı sektörlerde her işlem için onay zorunlu olabiliyor.
SSE bağlantısı koparsa ne olur?
AG-UI’da reconnect mekanizması var ama sağlam bir retry stratejisi eklemenizi şiddetle öneriyorum. Mesela kurumsal ortamlarda proxy ve firewall kuralları SSE’yi kesebiliyor. EventSource API’sının native reconnect’i çoğu durumda yeterli ama event ID’lerini takip edip kaçırılan olayları tekrar almanız gerekebilir.
Bu yapı mevcut bir chatbot framework’üne entegre edilebilir mi?
Edilebilir ama biraz emek ister. AG-UI’ın olay yapısı kendi formatında, mesela Botpress veya Rasa ile konuşturmanız için bir adapter katmanı yazmanız gerekiyor. Sıfırdan yapıyorsanız doğrudan AG-UI ile başlamak daha mantıklı.
Kaç ajana kadar ölçekleniyor?
HandoffBuilder’ın teknik bir ajan limiti yok ama pratik sınır genelde 8-10 ajan civarında. Bunun sebebi topoloji karmaşıklığı — 15 ajan arasındaki handoff kurallarını yönetmek ve debug etmek gerçekten zor. Daha fazla ajana ihtiyacınız varsa, ajan gruplarını alt-workflow’lara ayırmanızı öneriyorum.
Kaynaklar ve İleri Okuma
AG-UI Multi-Agent Workflow Demo – Microsoft Agent Framework Blog
AG-UI Protocol GitHub Repository
Azure AI Services Resmî Dokümantasyonu
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
3 comments