Kling Digital
tr
İletişim
2026-11-19
8 dk okuma
Öne Çıkan Rehber

AG-UI Nedir? Yapay Zeka Ajanlarını Arayüze Bağlama Protokolü

AG-UI (Agent-User Interaction Protocol), yapay zeka ajanlarını web, mobil ve terminal arayüzlerine bağlamak için tasarlanmış açık kaynaklı ve olay tabanlı bir iletişim protokolüdür. Parça parça yanıt akışını, yanıt ortasındaki araç çağrılarını, RFC 6902 durum farklarını ve kullanıcı onayı için duraklamaları taşıma bağımsız tek bir standartta birleştirerek MCP ve A2A katmanlarını tamamlar.

AG-UI Nedir? Yapay Zeka Ajanlarını Arayüze Bağlama Protokolü

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_START ve STATE_DELTA gibi 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_FINISHED içinde interrupt çıktısıyla temiz biçimde durur ve onay sonrası resume yü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:

  1. 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.
  2. Uzun süren çok adımlı bir planda ara adımların ilerleme durumunu arayüzdeki görev listesine anlık yansıtması gerekir.
  3. Ü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.
  4. 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şımBağladığı KatmanÇözdüğü Temel SoruTaşıma ve Veri ModeliTemel Kullanım Alanı
AG-UIAjan <-> 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 PatchCanlı metin akışı, araç çağrısı arayüzleri, insan onayı ve ortak durum
MCPAjan <-> 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
A2AAjan <-> 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 SSETekil 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ı threadId ve runId kimlikleriyle bildirir.
  • STEP_STARTED ve STEP_FINISHED: Çok aşamalı ajan grafiğindeki ara düğümlerin ilerleyişini arayüze görünür kılar.
  • RUN_FINISHED ve RUN_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_END ve TEXT_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_RESULT ve TOOL_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/await destekli 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:

  1. Aynı yapay zeka ajanını hem web panelinde hem mobil uygulamada hem de kurum içi CLI araçlarında sunmayı planlıyorsanız.
  2. Ajan yanıt üretirken arayüzde canlı araç ilerlemesi, dinamik bileşenler veya onay düğmeleri göstermeniz gerekiyorsa.
  3. 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.

Sıkça Sorulan Sorular

Rehber ve entegrasyonla ilgili en sık sorulan sorular.

Tüm Yazılara Dön
Paylaş

Yorumlar (0)

Görüş ve deneyimlerinizi toplulukla paylaşın.

Henüz yorum yapılmamış. İlk yorumu siz yapın!

Yorum Bırak

Yorumunuz yönetici onayından sonra yayına alınacaktır.

Topical Authority & İç Bağlantı Ekosistemi

İlgili Mimari Kıyaslamalar, Rehberler & Dijital Araçlar

Projeniz için en doğru teknoloji kararını vermeniz adına hazırladığımız kıyaslama matrisleri, derinlemesine B2B rehberler ve canlı hesaplama araçları.

Teknik Kıyaslama

Next.js vs WordPress Kıyaslaması

1 saniyenin altında açılış hızı, eklenti risklerinden arındırılmış güvenlik ve 3 yıllık toplam maliyet karşılaştırması.

Kapsamlı Kıyaslamayı İnceleyin
Mimari Kıyaslama

Framer vs Next.js Karşılaştırması

Görsel tasarım araçları ile tam teşekküllü kurumsal web yazılımı farkları.

Kapsamlı Kıyaslamayı İnceleyin

Son Yazılar

En güncel teknoloji, tasarım ve yazılım rehberlerimiz.

Tümünü Gör