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.
📋 İçindekiler
Bak şimdi, multi-agent sistemler terminal demosunda muhteşem görünüyor. Gerçekten. Ama gerçek kullanıcıların karşısına çıkardığında, hani şu “hangi ajan aktif şu an?”, “neden bekliyor?”, “bir sonraki adımda ne olacak?” sorularına cevap veremediğinde — sistem güvenilir olmaktan çıkıp opak bir kutuya dönüşüyor. Tam da bu yüzden AG-UI protokolü ile Microsoft Agent Framework’ün (MAF) birlikteliği beni gerçekten heyecanlandırdı açıkçası.
Neden Klasik Chat Arayüzleri Yetmiyor?
Çoğumuz ajan deyince aklına tek bir chatbot geliyor. Kullanıcı yazar, bot cevap verir. Tamam, bitti. Ama birden fazla ajan devreye girdiğinde işler karışmaya başlıyor — hem de fena karışıyor. 2024 sonunda bir bankacılık projesinde tam olarak bunu yaşadım: müşteri şikayetlerini kategorize eden bir triage ajanı, iade sürecini yöneten bir refund ajanı ve kargo takibi yapan bir order ajanı vardı. Terminalde test ederken her şey pürüzsüzdü, neredeyse şiirsel bile. React tabanlı bir chat arayüzüne bağladığımızda işe kullanıcılar “sistem döndü mu?” diye soruyordu, çünkü ajanlar arası geçiş tamamen görünmezdi, sanki arka planda hiçbir şey olmuyormuş gibi.
Çok konuştum, örnekle göstereyim.
Açık konuşayım, Klasik chat arayüzünün temel sorunu şu: tek bir mesaj akışı var (bu beni çok şaşırttı). Multi-agent workflow’da işe aslında birden fazla “bilinç” çalışıyor aynı anda. Hangisi konuşuyor? Hangisi düşünüyor? Hangisi onay bekliyor? Bu bilgiler kullanıcıya ulaşmadığında güven kayboluyor. İnsanlar — özellikle hassas işlemlerde, mesela iade veya ödeme gibi konularda — kontrol hissini yitirince sistemi terk ediyor. Hep böyle olmuştur zaten.
Bir de işin performans boyutu var. WebSocket bağlantıları, polling mekanizmaları… Bunları kendimiz implement etmek hem zahmetli hem de hata eğilimli. Standart bir protokol şarttı.
AG-UI Nedir ve Neyi Çözüyor?
Ne yalan söyleyeyim, AG-UI (Agent-User Interaction), ajan çalışma olaylarını Server-Sent Events (SSE) üzerinden frontend’e stream eden açık bir protokol. Yanı ajanın yaptığı her şey — bir tool çağırması, başka bir ajana devretmesi ya da kullanıcıdan onay beklemesi — gerçek zamanlı olarak arayüze akıyor. Bu kadar.
SSE Neden WebSocket Değil?
Bu soruyu çok alıyorum. Kısa cevap: SSE tek yönlü ve çok daha basit. Ajan tarafından kullanıcıya doğru akan olaylar için birebir uygun. Kullanıcının cevabı işe normal HTTP POST ile geri dönüyor — iki yönlü sürekli bağlantıya gerek yok çoğu senaryoda. Tabiî, WebSocket gereken durumlar da var, inkâr etmiyorum. Ama müşteri destek workflow’u gibi senaryolarda SSE gayet yeterli, hatta daha az sorun çıkarıyor. En çok da de load balancer arkasında SSE’nın davranışı çok daha tahmin edilebilir — bu konuda acı tecrübem var.
Ve işler burada ilginçleşiyor.
Olay Türleri
AG-UI’ın güzel tarafı, ajan yaşam döngüsünün her aşamasını event olarak modellemesi. Şöyle bir tablo ile özetleyeyim:
| Olay Tipi | Ne Zaman Tetiklenir? | Frontend’de Ne Olur? |
|---|---|---|
| AgentHandoff | Bir ajan işi başka ajana devrederken | Aktif ajan göstergesi değişir |
| ToolCallStart | Ajan bir tool çağırmaya başladığında | Loading/spinner gösterilir |
| ToolApprovalRequired | HITL onayı gereken tool çağrısında | Onayla/Reddet butonu çıkar |
| TextDelta | Ajan cevap üretirken (streaming) | Metin karakter karakter akar |
| RunComplete | Workflow tamamlandığında | Tamamlandı durumu gösterilir |
Bu olay yapısı sayesinde frontend geliştiricisi ajan iç mekanizmasını bilmek zorunda kalmıyor. Sadece event’leri dinliyor, UI’ı güncelliyor. Dur bir saniye — aslında bu tam olarak separation of concerns’ün ajan dünyasındaki karşılığı. Bu ne anlama geliyor? Hmm, basit ama güçlü bir fikir.
HandoffBuilder ile Workflow Tasarımı
Şunu fark ettim: Microsoft Agent Framework’ün HandoffBuilder’ı bence bu işin en zarif parçası. Ajanları, tool’ları ve handoff topolojisini deklaratif olarak tanımlıyorsunuz — yanı “refund ajanı sadece triage’dan iş alabilir, order ajanına devredemez” gibi kuralları framework seviyesinde belirliyorsunuz (buna dikkat edin). Basit bir zincir değil bu, yönlendirilmiş bir grafik (bizzat test ettim). Tahmin eder mısınız? Fark önemli. Daha fazla bilgi için Azure SDK’da Node.js 20 Desteği Bitiyor: Hazır mısınız? yazımıza bakabilirsiniz.
Bunu biraz açayım. SQL Yazarken İki Dünyayı Birleştiren Küçük Ama Güçlü Hamle yazımızda bu konuya da değinmiştik.
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. Bu konuyla ilgili MCP Apps’i Kolaylaştıran Fluent API: Sahada Ne Değişiyor? yazımıza da göz atmanızı tavsiye ederim.
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. Bu konuyla ilgili GitHub Code Scanning’de Toplu Düzeltme: PR’lar Hızlandı yazımıza da göz atmanızı tavsiye ederim.
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. Bu konuyla ilgili GitHub Copilot for Eclipse Açık Kaynağa Dönüyor: Neden Önemli? yazımıza da göz atmanızı tavsiye ederim.
Üçü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.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
3 comments