Bir yapay zeka ajanını arka uçta başarıyla ayağa kaldırdıktan sonra onu gerçek bir web, mobil veya terminal arayüzüne bağlamaya çalıştığınızda karşınıza her defasında aynı karmaşa çıkar: metin akışı bir kanalda, yanıtın ortasında tetiklenen araç çağrıları başka bir özel JSON şemasında, kullanıcı onayı bekleyen kritik işlemler ise kopmaya açık geçici bağlantılarda yönetilir.
AG-UI (Agent-User Interaction Protocol), ag-ui-protocol/ag-ui altında MIT lisansıyla geliştirilen ve yapay zeka ajanlarını web, mobil ve terminal arayüzlerine bağlamak için ortak bir iletişim dili tanımlayan açık kaynaklı, olay tabanlı bir protokoldür. Yanıtların parça parça akmasını, yanıt ortasındaki araç çağrılarını, paylaşılan uygulama durumu senkronizasyonunu ve kullanıcı onayı için duraklamaları tek bir standart yapıda birleştirir.
Önemli
- Tekil Olay Akışı Standardı:
RUN_STARTED,TEXT_MESSAGE_CONTENT,TOOL_CALL_STARTveSTATE_DELTAgibi tipli olaylar sayesinde istemci arayüzleri arka uç ajan çerçevesinden bağımsız hale gelir. - Temiz İnsan Onayı (Human-in-the-Loop): Uzun süre askıda kalan kırılgan soketler yerine, kullanıcı onayı gerektiğinde çalışma
RUN_FINISHEDiçindeinterruptçıktısıyla temiz biçimde durur ve onay sonrasıresumeyüküyle devam eder. - MCP ve A2A ile Tamamlayıcı Konum: MCP ajanı araçlara, A2A ajanları birbirine bağlarken; AG-UI doğrudan ajan ile son kullanıcı arayüzü arasındaki iletişim katmanını standartlaştırır.
Kurumsal ölçekte kurumsal yapay zeka çözümleri ve çok platformlu özel yazılım geliştirme projeleri inşa eden mühendislik ekipleri için en pahalı teknik borçlardan biri, ön yüz kodunun tek bir arka uç ajan çatısına (LangChain, CrewAI, Google ADK veya özel Python servisi) sıkı sıkıya bağlanmasıdır. Arka uç motoru değiştiğinde tüm React, iOS, Android veya CLI akış ayrıştırıcılarını sıfırdan yazmak gerekir. AG-UI, tam da bu bağımlılığı ortadan kaldırarak ajan ile arayüz arasındaki iletişim için ortak bir standart adayı olarak öne çıkar.
Geleneksel İstek-Yanıt API'leri Neden Ajan Arayüzlerinde Yetersiz Kalır?
Klasik REST uç noktaları tek bir HTTP isteğine karşılık tek bir tamamlanmış yanıt döndürmek üzere tasarlanmıştır. Oysa modern bir yapay zeka ajanı doğrusal çalışmaz:
- Kullanıcıya parça parça açıklama metni akıtırken yarı yolda bir veritabanı sorgusu veya harici araç çağrısı başlatabilir.
- Uzun süren çok adımlı bir planda ara adımların ilerleme durumunu arayüzdeki görev listesine anlık yansıtması gerekir.
- Üretim veritabanında silme veya ödeme onayı gibi yüksek riskli bir işlem öncesi yürütmeyi duraklatıp insandan açık onay almak zorundadır.
- Dosya, görsel veya canlı medya gibi çok kipli (multimodal) ekleri çift yönlü paylaşması gerekebilir.
Kasım 2026 açık kaynak yapay zeka ajan ekosistemi içinde her framework kendi özel SSE şemasını ürettiği için ön yüz ekipleri her entegrasyonda özel yapıştırıcı kodlar yazmak zorunda kalıyordu. CopilotKit ekosistemiyle birlikte öncülük edilen ve açık yönetişimle genişleyen AG-UI, bu parçalanmayı ortak bir olay sözleşmesiyle kapatır.
Ajan Protokol Yığınında AG-UI, MCP ve A2A Farkı
Modern ajan mimarilerinde üç açık protokol birbiriyle rekabet etmez; yığının tamamen farklı üç katmanını standartlaştırır. Aşağıdaki karşılaştırma tablosu her protokolün sorumluluk sınırını netleştirir:
| Protokol / Yaklaşım | Bağladığı Katman | Çözdüğü Temel Soru | Taşıma ve Veri Modeli | Temel Kullanım Alanı |
|---|---|---|---|---|
| AG-UI | Ajan <-> Kullanıcı Arayüzü | "Ajan web, mobil veya terminal arayüzüyle nasıl konuşur?" | SSE veya WebSocket üzerinden tipli olay akışı + RFC 6902 JSON Patch | Canlı metin akışı, araç çağrısı arayüzleri, insan onayı ve ortak durum |
| MCP | Ajan <-> Araçlar ve Veri | "Ajan harici araçlara, dosyalara ve veritabanlarına nasıl erişir?" | JSON-RPC (stdio / Streamable HTTP) | Yerel kaynaklar, API bağlayıcıları, REA MCP gibi uzman araçlar |
| A2A | Ajan <-> Ajan | "Dağıtık ajanlar işi birbirine nasıl devreder?" | HTTP / JSON-RPC görev sözleşmeleri (Google / Linux Foundation) | Çoklu ajan orkestrasyonu ve kurumsal sınırlar arası görev aktarımı |
| Özel REST / Özel SSE | Tekil Arka Uç <-> Tekil Ön Yüz | "Bu tek ekranı en hızlı nasıl bağlarım?" | Projeye özgü belge dışı JSON akışları | Küçük prototipler; çoklu istemcide yüksek bakım borcu üretir |
Kısacası bir üretim uygulamasında arka uç ajanınız MCP ile araçlara erişir (örneğin claude-mem kalıcı hafıza katmanı üzerinden oturum geçmişini sorgular), gerektiğinde A2A ile başka bir uzman ajana görev devreder ve tüm kullanıcı deneyimini AG-UI üzerinden tek biçimli biçimde ön yüze aktarır.
AG-UI Olay Aileleri ve Taşıma Bağımsız Mimari
AG-UI, tek bir ağ teknolojisine kilitlenmeyen (transport-agnostic) hafif bir protokoldür. Tek yönlü hafif akışlar için Server-Sent Events (SSE), tam çift yönlü gerçek zamanlı etkileşim veya istemci taraflı araç dönüşleri için WebSocket üzerinden çalışabilir.
Protokolün kalbinde ajan yaşam döngüsünü ince taneli parçalara bölen dört ana olay ailesi bulunur:
1. Çalıştırma ve Adım Yaşam Döngüsü (Runs & Steps)
RUN_STARTED: Bir ajan çalıştırmasının başladığınıthreadIdverunIdkimlikleriyle bildirir.STEP_STARTEDveSTEP_FINISHED: Çok aşamalı ajan grafiğindeki ara düğümlerin ilerleyişini arayüze görünür kılar.RUN_FINISHEDveRUN_ERROR: Yürütmenin normal sonlandığını, bir kullanıcı onayı için durakladığını (interrupt) veya hata verdiğini raporlar.
2. Parça Parça Metin Akışı (Text Messages)
TEXT_MESSAGE_START,TEXT_MESSAGE_CONTENT,TEXT_MESSAGE_ENDveTEXT_MESSAGE_CHUNK: Asistan yanıtını mesaj kimliğine bağlı kalarak karakter veya parça (delta) bazında arayüze akıtır. Böylece arayüz aynı anda birden fazla paralel akışı karıştırmadan çizebilir.
3. Yanıt Ortasında Araç Çağrıları (Tool Calls)
TOOL_CALL_START,TOOL_CALL_ARGS,TOOL_CALL_END,TOOL_CALL_RESULTveTOOL_CALL_CHUNK: Ajan cevabın tam ortasında bir araç çağırmaya karar verdiğinde, argümanlar dahi parça parça akarken arayüz canlı bir "araç çalışıyor" kartı, onay formu veya dinamik bileşen (Generative UI) gösterebilir.
4. Paylaşılan Durum Senkronizasyonu (State Management)
STATE_SNAPSHOT: Bağlantı başında veya yeniden bağlanmada tüm paylaşılan uygulama durumunun tam anlık görüntüsünü iletir.STATE_DELTA: Tüm nesneyi baştan yollamak yerine RFC 6902 JSON Patch formatında yalnızca değişen alanları artımlı olarak gönderir. Bu yaklaşım hem bant genişliğini korur hem de karmaşık tablo, form veya alt ajan listelerinin titreşimsiz güncellenmesini sağlar.
İpucu
Arka uçta LangChain, CrewAI, Microsoft Agent Framework, Google ADK, LlamaIndex veya Pydantic AI kullanıyor olmanız fark etmez; resmi AG-UI bağdaştırıcıları bu çerçevelerin iç olaylarını standart AG-UI olaylarına çevirir, böylece ön yüzünüz arka uç göçlerinden sıfır etkilenir.
İnsan Onayı (Human-in-the-Loop) İçin Duraklama ve Devam Etme Akışı
Üretim ajanlarında en sık kırılan nokta, kullanıcı onayı gerektiren işlemlerdir. Geleneksel akışlarda HTTP bağlantısını dakikalarca açık tutmak ters vekil zaman aşımlarına ve durum kaybına yol açar.
AG-UI bunu sonlandırıcı kesme (terminal interrupt) deseniyle çözer: Ajan insan müdahalesine ihtiyaç duyduğunda RUN_FINISHED olayını interrupt sonucu ve benzersiz bir interruptId dizisiyle göndererek mevcut çalıştırmayı temiz biçimde kapatır. İstemci arayüzü kullanıcıya onay kartını gösterir; kullanıcı onayladığında veya reddettiğinde @ag-ui/client içindeki HttpAgent aynı threadId üzerinde resume yüküyle yeni bir çalıştırma başlatır:
import { HttpAgent } from "@ag-ui/client";
const agent = new HttpAgent({
url: "https://api.example.com/agent",
headers: {
Authorization: `Bearer ${process.env.AGUI_TOKEN}`,
},
threadId: "thread-ops-4821",
});
agent.messages.push({
id: "msg-user-1",
role: "user",
content: "Arşivlenmiş 90 günlük geçici fatura taslaklarını temizle.",
});
async function executeWithApproval() {
// 1. İlk çalıştırma: ajan hassas işlem için interrupt ile durur
await agent.runAgent();
// Olay dinleyicisinden yakalanan interruptId ve arayüz onay kararı:
const pendingInterruptId = "intr-clean-drafts-01";
const approvedByReviewer = true;
// 2. Temiz resume yüküyle aynı bağlamda yürütmeye devam et
const resumed = await agent.runAgent({
resume: [
{
interruptId: pendingInterruptId,
status: approvedByReviewer ? "resolved" : "cancelled",
payload: {
approved: approvedByReviewer,
comment: approvedByReviewer
? "Yönetici panelinden onaylandı."
: "Politika gereği iptal edildi.",
},
},
],
});
return resumed;
}
Bu tasarım sayesinde kullanıcı onayı 3 saniye de sürse 3 saat de sürse sunucu tarafında açık bırakılmış kırılgan bir akış soketi kalmaz; konuşma durumu threadId ve kalıcı kontrol noktaları üzerinden güvenle yeniden başlar.
Web, Mobil ve Terminal Arayüzleri İçin SDK Ekosistemi
AG-UI'nin olay sözleşmesi görsel katmandan tamamen ayrıldığı için aynı arka uç uç noktası farklı cihaz türlerine tek protokolle hizmet verebilir:
- Web ve Masaüstü (Birinci Taraf): TypeScript (
@ag-ui/core,@ag-ui/client), React (CopilotKit entegrasyonu), Angular ve Vue istemcileri durum yamalarını ve akış bileşenlerini doğrudan tüketir. - Mobil Platformlar: Android, iOS ve JVM hedefleri için Kotlin Multiplatform SDK'sı, yerel iOS geliştiricileri için modern Swift
async/awaitdestekli topluluk kütüphaneleri, ayrıca React Native ve Flutter (SSE akışı ve insan onayı formları destekli) paketleri mevcuttur. - Terminal ve CLI İstemcileri: Python, TypeScript veya .NET bağlamalarıyla ham AG-UI olay akışını tüketen etkileşimli komut satırı arayüzleri ve geliştirici izleme panoları kolayca inşa edilir.
- Çekirdek Şema Dilleri: 1.0 spesifikasyonu TypeScript, Python ve .NET için birinci taraf kod üretimi sunarken; Go, Rust, Java, Dart/Flutter, Ruby ve C++ ekosistemlerinde topluluk SDK'ları büyümeye devam etmektedir.
Uyarı
Güvenlik ve Yetkilendirme Hatırlatması: AG-UI bir iletişim protokolüdür; kimlik doğrulama ve yetkilendirme politikalarını sizin yerinize uygulamaz. Özellikle resume çağrılarında gelen approved: true bilgisini istemciden körü körüne güvenmek yerine sunucu tarafında aktif kullanıcı oturumu, rol tabanlı erişim kontrolü (RBAC) ve interruptId eşleşmesiyle mutlaka yeniden doğrulayın. Ayrıca yoğun akışlı ajanlarda girdi/çıktı maliyetlerini kontrol etmek için Caveman token sıkıştırma rehberindeki optimizasyon pratiklerini değerlendirebilirsiniz.
Kurumsal Mimari İçin Ne Zaman AG-UI Seçilmeli?
Tek seferlik statik bir metin üretimi için standart HTTP yeterlidir; ancak aşağıdaki gereksinimlerden ikisi bile ürününüzde varsa AG-UI uzun vadede ciddi mühendislik maliyeti kazandırır:
- Aynı yapay zeka ajanını hem web panelinde hem mobil uygulamada hem de kurum içi CLI araçlarında sunmayı planlıyorsanız.
- Ajan yanıt üretirken arayüzde canlı araç ilerlemesi, dinamik bileşenler veya onay düğmeleri göstermeniz gerekiyorsa.
- Arka uç ajan çerçevesini gelecekte değiştirme özgürlüğünü ön yüz kodunu kırmadan korumak istiyorsanız.
Çok platformlu ajan arayüzlerinin geliştirme ve entegrasyon bütçesini öngörmek için maliyet hesaplayıcı aracımızı kullanabilir; kurumunuza özel AG-UI, MCP ve kalıcı hafıza tabanlı üretim mimarileri tasarlamak için Kling Digital iletişim sayfasından ekibimizle doğrudan iletişime geçebilirsiniz.




