AG-UI: A Lightweight Protocol for Agent-User Interaction

Neden Ajansal Uygulamalar AG-UI’ye İhtiyaç Duyar

Koda bakmadan önce, neden en başta yeni bir protokole ihtiyaç duyduğumuzu açıklayayım. Bu, bir fonksiyon ile bir ajan arasındaki temel farka dayanır.

İstek/yanıt modelinin sınırı

Geleneksel web geliştirmede etkileşimler işlemseldir. Bir kullanıcı profili istersiniz, sunucu gönderir. Tek seferlik bir alışveriştir.

Ajanlar ise öngörülemezdir ve zaman alır. Bir ajandan "ekibinizden birinin birleşiminden sonra CI hattınızın neden aniden bozulduğunu ayıkla" dediğinizde, hemen bir JSON nesnesi döndürmez. Bunun yerine şunları yapabilir:

1. GitHub’dan son 50 commit kaydını çeker (Eylem).
2. Kilit dosyası güncellenmeden yeni bir bağımlılık eklendiğini fark eder (Gözlem).
3. Bu paket sürümünü bilinen CVE’lerle çapraz kontrol eder (Muhakeme).
4. Birleştirmeyi geri almak mı yoksa ileriye dönük yamalamak mı istediğinizi sorar (İnsan döngüde).

Bunu "Olay Türleri" bölümünde daha sonra açıklayacağım, ancak şimdilik, standart bir HTTP isteğinin tüm bunlar için beklerken zaman aşımına uğrayacağını bilin. Kullanıcının donmuş bir ekrana bakakalmaması için bu kısmi güncellemeleri akış halinde iletecek bir yola ihtiyacınız var.

Ajanların özgül ihtiyaçları

Ajanlar, metnin ötesine geçen çift yönlü bir bilgi akışı gerektirir. Durumu senkronize etmeleri gerekir.

Bir ajanın size rapor yazmada yardımcı olduğunu hayal edin. Sadece sohbet etmiyor; bir belgeyi düzenliyor. Hem siz hem de ajan aynı anda yazıyor olabilirsiniz. AG-UI bunu "belgeyi" paylaşılan bir durum olarak ele alarak, birbirinizin çalışmasını ezmeden ekranınız ile ajanın hafızasını senkron tutmak için verimli güncellemeler kullanarak çözer.

Ajanlar ve UI’lar Nasıl İletişim Kurar

AG-UI, eski Uzak Prosedür Çağrısı (RPC) modelinin yerini Olay Kaynaklı (Event-Sourcing) bir modelle değiştirir. Nihai yanıtı beklemek yerine, ajan ne yaptığını anlatan sürekli bir olay akışı gönderir.

Olay akışı

AG-UI akışını, ajanın beynine ait bir canlı haber şeridi olarak düşünün. İstemci uygulaması (ön yüzünüz) bu şeride abone olur ve gördüklerine göre UI’yı günceller. Bu yaklaşım mantığı ayrıştırır: React ön yüzünüz ajanın nasıl düşündüğünü bilmek zorunda değildir, sadece ne göstereceğini bilmesi yeterlidir.

AG-UI bekleme boşluğunu ortadan kaldırır. Görsel: Yazar.

Çekirdek olay türleri

Protokol, neredeyse her etkileşim senaryosunu kapsayan standart olay türlerini tanımlar. En çok görecekleriniz şunlardır:

1. TEXT_MESSAGE_*: Üretilen metni parça parça akışa veren olaylar. Bu genellikle _START, _CONTENT (token akışı) ve _END olaylarını içerir ve birlikte tanıdık "yazıyor" etkisini oluşturur.

2. TOOL_CALL: Ajanın bir şey yapmak istediğini, örneğin havayı kontrol etmek veya bir veritabanı sorgulamak istediğini bildirir. Önemli olarak, AG-UI araç çağrısının argümanlarını akışa verebilir; böylece UI’nız, ajan "konuşmasını" bitirmeden bile formları önceden doldurabilir.

3.  STATE_DELTA: İşbirliği için yükü çeken türdür. Her seferinde bir harf değiştiğinde tüm belgeyi yeniden göndermek yerine, ajan küçük bir "diff" gönderir (ör. "5. indekse 'hello' ekle").

4. INTERRUPT: Emniyet supabı. Bir ajan hassas bir eyleme (ör. "Veritabanını Sil") ulaştığında bir kesme olayı yayar. Akış, kullanıcı bir onay olayı gönderene kadar duraklar.

Çok kipli yetenek ve düşünme adımları

Protokol metinle sınırlı değildir. Görüşmeye görselleri, sesleri ve dosya eklerini eşzamanlı olarak akışa vererek çok kipli etkileşimi destekler. Ayrıca Düşünme Adımlarını standartlaştırır; ajanın içsel düşüncelerini (akılyürütme izleri) nihai herkese açık yanıttan ayırır. ChatGPT gibi araçları kullanırken, ilerleme göstergelerinin veya ara adımların nihai yanıttan ayrı şekilde gösterildiğini fark etmiş olabilirsiniz. Bu, yürütme ilerlemesini mi yoksa yalnızca nihai sonucu mu göstereceğinize karar vermenizi sağlar.

AG-UI’nin Yapı Taşları

Artık akışı anladığınıza göre, AG-UI’yi geliştiriciler için güçlü kılan belirli özelliklere bakalım.

Üretken UI

Metin harika olabilir, ama bazen bir grafik daha iyidir. Üretken UI, bir ajanın çalışma zamanında metin yerine bir UI bileşeni göstermesi gerektiğine karar vermesine olanak tanır.

AG-UI olayları akışa verir; A2UI bileşenleri tanımlar. Görsel: Yazar.

Burada insanları sık sık şaşırtan bir ayrım var (buna çerçeve bölümünde yeniden değineceğim): AG-UI iletim mekanizmasıdır (taşıma katmanı) ve A2UI (Agent-to-User Interface) ise UI tanımıdır (yük). Bir ajan, bir AG-UI TOOL_CALL olayı kullanarak bir A2UI yükünü, bir UI bileşenini (ör. "Hisse Fiyat Kartı") tanımlayan deklaratif bir JSON ağacını iletebilir. Ön yüzünüz bunu alır ve gerçek grafiği oluşturur.

JSON Patch ile paylaşılan durum

Paylaşılan durumu yönetmek zordur. Ajan her saniye 5 MB’lık devasa bir bağlam nesnesi gönderirse uygulamanız sürünür.

AG-UI bu sorunu JSON Patch (RFC 6902) ile çözer. Daha önce durum senkronizasyonuyla ilgili belirttiğim gibi, ajan hafızasında bir değeri değiştirdiğinde farkı hesaplar ve bir STATE_DELTA olayı gönderir.

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]Altyapı:

İstemci bu hafif talimatı alır ve yerel durumuna uygular. Bu verimlilik, ajanlarla gerçek zamanlı işbirliğini mümkün kılar.

Protokol Manzarasında AG-UI

MCP (Model Context Protocol) gibi diğer protokolleri duymuş olabilirsiniz. Yanlış aracı kullanmamak için AG-UI’nin yığında nereye oturduğunu bilmek önemlidir.

Ajansal yığın

Bunu bir iletişim üçgeni olarak düşünmeyi seviyorum:

1. MCP (Ajan ↔ Araçlar): Ajana veritabanları, GitHub depoları ve dahili API’ler gibi arka uç dünyasına bağlanır. Bilgi edinmeyle ilgilidir.
2. A2A (Ajan ↔ Ajan): Ajanların birbirleriyle konuşmasına, alt ajanlara görev vermesine olanak tanır.
3. AG-UI (Ajan ↔ Kullanıcı): Bu "Son Mil"dir. Ajanın zekasını insan kullanıcıya bağlar.

Ajanları bağlayan Protokol Üçlüsü. Görsel: Yazar.

AG-UI, ajanın veriyi nasıl edindiğiyle ilgilenmez (bunu yukarıda belirttiğim gibi MCP yapar); sadece bu veriyi size nasıl göstereceğiyle ilgilenir.

AG-UI’nin Uygulanması

Bunun pratikte nasıl göründüğüne bakalım. Geliştiriciler genellikle AG-UI ile üç şekilde etkileşir: 1) Ajansal Uygulamalar (bir ön yüzü bir ajana bağlamak), 2) Entegrasyonlar (bir çerçeveyi uyumlu kılmak) veya 3) İstemciler (yeni ön yüzler oluşturmak). Çoğunuz ilk kategoride olacaksınız.

Kodu birazdan açıklayacağım, ancak önce şunu anlayın: Ham protokol işleyicilerini genellikle kendiniz yazmazsınız. Kütüphaneler paketlemeyi halleder. Ama akışı anlamak hata ayıklama için gereklidir.

Olay kanalını kurma

Çoğu uygulama, basit, güvenlik duvarı dostu ve sunucudan istemciye tek yönlü akış için ideal olduğundan Server-Sent Events (SSE) kullanır. Bunu daha önce ima etmiştim; WebSocket’lere kıyasla bu protokolü bu kadar hafif yapan temel unsur SSE’dir.

Tipik bir kurulumda (Microsoft Agent Framework veya CopilotKit gibi), sunucunuz bağlantıyı bir akışa yükselten bir uç nokta sağlar.

Basit olay aboneliği

Bir ön yüz istemcisinin akışı nasıl dinlediğine dair kavramsal bir örnek aşağıda. UI’yı güncellemek için farklı olay türlerini nasıl ele aldığımıza dikkat edin.

// AG-UI akışına bağlanın
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Sohbet penceresine metin ekleyin
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Bir "İşleniyor..." göstergesi veya belirli araç UI'si gösterin
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // JSON yamasını yerel durum depomuza uygulayın
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Kullanıcıdan izin isteyin
      showApprovalModal(data.message);
      break;
  }
};Altyapı:

Bu kalıp, ajanın iç mantığının karmaşıklığını gizler. Ön yüzünüz, ajanın gönderdiği olaylar için sadece bir "oynatıcıdır".

Entegrasyonlar ve Ekosistem Desteği

Bunların hepsini sıfırdan inşa etmek zorunda değilsiniz. Ekosistem hızla olgunlaşıyor; büyük platformlar ve çerçeveler benzer olaya dayalı etkileşim kalıplarında birleşiyor.

Araçların "Altın Üçgeni"

Microsoft, ajan geliştirme için bir "Altın Üçgen" tanımlar:

1. DevUI: Ajanın düşünme sürecini görselleştirmek (hata ayıklama) için.
2. OpenTelemetry: Performans ve maliyeti ölçmek için.
3. AG-UI: Kullanıcıya bağlanmak için.

Desteklenen çerçeveler

Ekosistem hızla genişliyor. Büyük oyuncuların ötesinde, destek her yerde artıyor:

1. Microsoft Agent Framework: ASP.NET Core için yerel ara katman yazılımına sahiptir (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: AG-UI için bir "Tarayıcı" gibi davranır; bu olayları kutudan çıktığı gibi nasıl işleyeceğini bilen, eksiksiz bir React ön yüzü sunar.

3. Python Ekosistemi: LangGraph, CrewAI, Mastra, Pydantic AI, Agno ve LlamaIndex gibi çerçevelerin tümü AG-UI uç noktaları olarak expose edilebilir.

4. SDK’lar: TypeScript ve Python baskın olsa da, Kotlin, Go, Dart, Java ve Rust için etkin veya geliştirme aşamasında SDK’lar vardır.

Güvenilirlik, Hata Ayıklama ve Güvenlik

Bir yapay zekâ ile bir tarayıcı arasında doğrudan bir iletişim hattı açmak riskler doğurur. Uygulamanızı güvende tutmanın yolları şunlardır.

Güvenilir ön yüz sunucusu

İstemcinin ham ajan çalışma zamanınıza doğrudan bağlanmasına asla izin vermeyin. "Neden Ajansal Uygulamalar AG-UI’ye İhtiyaç Duyar" bölümünde vurguladığım gibi, her zaman Güvenilir Bir Ön Yüz Sunucusu (BFF deseni) kullanın. Bu sunucu bir arabulucu olarak hareket eder. Kullanıcının mesajını ajana iletmeden önce kimlik doğrulama, hız sınırlama ve girdi doğrulama ekler.

Güvenlik hususları

İstem kalıbı enjeksiyonu

Kötü niyetli kullanıcılar prompt injection saldırıları yoluyla ajanın talimatlarını geçersiz kılmaya çalışabilir. Daha önce de belirttiğim gibi, ara katmanınız girdileri temizlemelidir.

Yetkisiz araç çağrıları

Bir ajan bir dosyayı silebilir olsa da mevcut kullanıcının bunu yapmasına izin verilmesi gerektiği anlamına gelmez. Güvenilir sunucunuz, kullanıcı izinlerine göre ajana sunulan araçları filtrelemelidir.

Durum güvenliği

Durum JSON yamalarıyla paylaşıldığından, prototip kirlenmesine karşı dikkatli olun. Yama kütüphanenizin __proto__ gibi korunan özelliklerde değişikliği yasakladığından emin olun.

Dojo ile hata ayıklama

Ajanınız garip davranıyorsa, AG-UI Dojo’yu kullanın. Ham olay akışını görselleştirmenize olanak tanıyan bir test paketidir. Hatalı biçimlendirilmiş JSON yamaları veya tetiklenen ancak sonuç döndürmeyen araç çağrıları gibi sorunları yakalamanıza yardımcı olur.

Sonuç

AG-UI’nin mimarisini, olay türlerini ve uygulama kalıplarını ele aldık.

Şunu kabul ediyorum: Ortalama bir tek kişilik geliştirici ya da küçük bir şirkette çalışan biri, pratikte "AG-UI’yi benimseyip" bir anda "ön yüzünü arka yüzden ayrıştırmayacak." Tüm bunlar önemli mimari kararlar, birden fazla ekibin onayı ve çoğu kişinin sahip olmadığı kaynaklar gerektirir.

Ancak AG-UI’yi anlamak, onu uygulamıyor olsanız bile önemlidir. Ajan çerçevelerini değerlendirirken veya içerde mi inşa edeceğinize yoksa bir platform mu kullanacağınıza karar verirken, "iyi" bir ajan-UI iletişiminin nasıl göründüğünü bilmek size daha iyi muhakeme kazandırır. Bir aracın sizi kırılgan kalıplara zorladığını fark edersiniz.

Bu sistemleri daha derinlemesine inşa etmeye dalmak isterseniz, becerilerinizi bir üst seviyeye taşımak için Yapay Zeka Ajanlarına Giriş ve Ölçeklenebilir Ajansal Sistemler İnşa Etme kurslarımıza göz atın.