AI ajan protokolleri için geliştirici rehberi

• MCP, A2A, UCP, AP2, A2UI, AG-UI gibi 6 farklı AI ajan protokolünü tek bir restoran tedarik zinciri ajanı senaryosunda bir araya getirerek, her protokolün çözdüğü problemi gerçek kodlarla adım adım anlatan bir rehber
• Google'ın Agent Development Kit(ADK) aracını kullanarak boş bir LLM'den başlayıp protokolleri tek tek ekleyerek envanter kontrolü, teklif alma, sipariş, ödeme ve pano render etme akışını tamamlayan bir yapı
• MCP araç/veri bağlantısını, A2A ajanlar arası iletişimi, UCP ticaret standardizasyonunu, AP2 ödeme yetkilendirmesini, A2UI kullanıcı arayüzü kurulumunu, AG-UI ise akış iletimini üstleniyor
• Her protokol, iyi bilinen URL tabanlı keşif, tiplenmiş şemalar, standart olay akışları gibi ortak kalıpları paylaşarak ekosistem uyumluluğu sağlıyor
• İlk günden 6 protokolün tamamını benimsemek yerine, ihtiyaca göre kademeli ekleme yaklaşımı öneriliyor

---

MCP(Model Context Protocol) — araç ve veri bağlantısı

• Ajanı sistemlere ve verilere bağlarken ortaya çıkan ilk engeli çözen bir protokol; her API için özel entegrasyon kodu yazma zorunluluğunu ortadan kaldırıyor
• MCP sunucusu kendi araçlarını advertise ettiğinde ajan bunları otomatik olarak keşfediyor; böylece yüzlerce sunucu için tek bir standart bağlantı deseni sunuluyor
• MCP sunucusu ilgili sistemi geliştiren ekip tarafından bakım gördüğü için, ajan tarafında entegrasyon kodu yazmaya veya güncellemeye gerek kalmadan her zaman güncel araç tanımları elde ediliyor
• ADK içinde McpToolset ile birinci sınıf destek sunuluyor; örnekte PostgreSQL veritabanı sorgulama (MCP Toolbox for Databases), Notion MCP üzerinden tarif sorgulama, Mailgun MCP üzerinden tedarikçiye e-posta gönderme uygulanıyor
  • ToolboxToolset ile envanter veritabanına bağlantı
  • McpToolset ile Notion, Mailgun gibi harici servislere bağlantı
• Ayrı bir kod yazmadan npx komutuyla MCP sunucusunu çalıştırıp ajanla doğrudan bağlayan yalın bir desen

A2A(Agent2Agent Protocol) — ajanlar arası iletişim

• MCP veri erişimini çözdükten sonra geriye kalan uzmanlık(expertise) sorununu ele alan protokol; farklı ekiplerde, framework'lerde ve sunucularda çalışan uzak ajanlar arasında standart keşif ve iletişim yöntemi sağlıyor
• Her A2A ajanı /.well-known/agent-card.json konumunda bir Agent Card yayımlayarak adını, yeteneklerini ve endpoint'ini duyuruyor; mutfak yöneticisi ajanı bunu çekip çalışma anında sorguyu uygun ajana yönlendiriyor
• Yeni bir uzak ajan eklerken yalnızca URL eklemek yeterli olduğundan, elle kod değişikliği ya da yeniden dağıtım gerekmiyor
• ADK'deki RemoteA2aAgent her turda tek bir uzak ajana yönlendiriyor; birden çok uzak ajana eşzamanlı sorgu gerektiğinde ise doğrudan a2a-sdk kullanılıyor
• to_a2a() fonksiyonu ile tüm ADK ajanları A2A servisine dönüştürülebiliyor
• Fiyat kontrolü, kalite derecesi, teslimat penceresi gibi ham veriler API ile açılmamış olsa bile ajanik arayüz üzerinden erişilebiliyor

UCP(Universal Commerce Protocol) — ticaretin standardizasyonu

• Her tedarikçide farklı API'lere sahip sipariş süreçlerini birleştiren bir protokol; alışveriş yaşam döngüsünü modüler işlevlerle standartlaştırıyor
• Güçlü tipli istek/yanıt şemaları ile tutarlılığı koruyor; alttaki taşıma katmanı REST, MCP, A2A veya EP(tarayıcı tabanlı gömülü protokol) olsa da aynı desenle çalışıyor
• A2A ile aynı /.well-known/ucp URL deseni sayesinde tedarikçi kataloğu keşfi yapılabiliyor
• Özel SDK gerekmeden, mevcut HTTP istemcisiyle standart REST API'lere doğrudan bağlanılabiliyor
• Örnekte CheckoutCreateRequest ile 10 pound somon ve 3 şişe zeytinyağı sipariş ediliyor, PaymentCreateRequest ile ödeme isteği oluşturuluyor
• UCP örnek deposunda ADK ve A2A'yı birleştiren yapay zeka tabanlı alışveriş asistanı örneği de yer alıyor

AP2(Agent Payments Protocol) — ödeme yetkilendirmesi ve denetim izi

• UCP sipariş edilecek ürünü ve tedarikçiyi ele alırken, AP2 satın almayı kimin onayladığını ve denetim izini yönetiyor
• Tiplenmiş mandate ile inkar edilemez niyet kanıtı(non-repudiatable proof of intent) sağlıyor ve her işlem için yapılandırılabilir guardrail'ler uyguluyor
• Tam akış: IntentMandate → PaymentMandate(imzalı) → PaymentReceipt
  • IntentMandate: izin verilen satıcılar, harcama limiti, otomatik onay durumu, iade edilebilirlik gereksinimi, sona erme zamanı gibi guardrail ayarları
  • PaymentMandate: belirli bir sepet ve tutara bağlı ödeme yetki belgesi; limit aşıldığında yöneticinin açık onayı gelene kadar imzasız kalıyor
  • PaymentReceipt: denetim izini tamamlayan makbuz
• UCP'nin bir uzantısı(extension) olarak çalışıyor ve checkout akışına kriptografik yetkilendirme kanıtı ekliyor
• Şu anda v0.1 aşamasında; ADK çekirdeğine gömülü değil, tipler ayrı bir paketle sağlanıyor

A2UI(Agent-to-User Interface Protocol) — dinamik arayüz oluşturma

• Ajanın düz metin yerine pano, sipariş formu, tedarikçi karşılaştırma tablosu gibi yapıları dinamik olarak kurabilmesini sağlayan protokol
• 18 güvenli bileşen primitive'inden oluşan sabit katalog üzerinde satır, sütun, metin alanı vb. öğelerle bildirimsel JSON biçiminde yeni yerleşimler birleştiriliyor
• Arayüz yapısı ile veriyi ayırdığı için, bileşenleri yeniden göndermeden yalnızca veriyi güncellemek mümkün
  • Bileşenler, ID ile birbirine referans veren düz bir liste olarak gönderiliyor
  • Veri ayrı bir dataModelUpdate ile iletiliyor
• İstemci tarafındaki renderer, JSON'u Lit, Flutter, Angular gibi yerel arayüzlere dönüştürüyor
• Aynı ajan, aynı 18 primitive ile envanter kontrol listesi, sipariş formu, tedarikçi karşılaştırması gibi tamamen farklı arayüzler oluşturabiliyor
• ADK web arayüzünde(adk web) A2UI bileşenleri yerel olarak render edilebildiği için geliştirme sırasında ayrı bir renderer kurmak gerekmiyor
• A2UI Widget Builder ile yerleşimler etkileşimli biçimde birleştirilebiliyor

AG-UI(Agent-User Interaction Protocol) — akış iletimi

• Ajanlar, geleneksel REST API'lerden farklı olarak metni kademeli biçimde akıtabiliyor, yanıt sırasında araç çağırabiliyor ve insan girdisini bekleyerek duraklayabiliyor; yani karmaşık etkileşim kalıplarına sahip
• AG-UI, middleware olarak çalışıp framework'e özgü ham olayları standartlaştırılmış SSE akışına dönüştürüyor
• Frontend'in yalnızca TEXT_MESSAGE_CONTENT, TOOL_CALL_START gibi tiplenmiş olayları alması yeterli; bunların hangi ajan framework'ü tarafından üretildiğini bilmesine gerek yok
• ADK yerel bir /run_sse endpoint'i sunsa da, parse etme kodunun boilerplate olması ve olay formatı değiştiğinde kırılabilmesi sorununu AG-UI çözüyor
• ag_ui_adk paketiyle sarmalayıp FastAPI uygulamasına mount etmek AG-UI akış endpoint'i kurmak için yeterli

Uçtan uca birleşik çalışma akışı

• Kullanıcı "somon stokunu kontrol et, bugünkü toptan fiyatı ve kalite derecesini sorgula, stok yetersizse Example Wholesale'dan 10 pound sipariş ver ve ödemeyi yetkilendir" dediğinde 6 protokol sırayla devreye giriyor
• 1. aşama — bilgi toplama: MCP ile envanter veritabanı sorgusu(check_inventory) → A2A ile uzak fiyat/kalite ajanına sorgu(ask_agent)
• 2. aşama — işlemi tamamlama: UCP ile checkout isteği(place_order) → AP2 ile tanımlı guardrail'ler içinde ödeme mandate'inin alınması(authorize_payment)
• 3. aşama — sonucu gösterme: A2UI ile etkileşimli widget oluşturma → AG-UI ile araç çağrıları ve metin yanıtının gerçek zamanlı akıtılması

Protokolleri kullanma ipuçları

• Mimarinin temiz kalması için her protokolün çözdüğü problemi doğru anlamak gerekiyor
• İlk günden 6 protokolün hepsi gerekmiyor; çoğu durumda MCP ile başlayıp çoklu ajan iletişimi, ticaret, ödeme, zengin arayüz ve akış gibi ihtiyaçlar arttıkça kademeli ekleme yeterli
• Protokollerle inşa etmeye başlamadan önce ADK entegrasyonlarını, resmi SDK'ları ve örnek kodları kontrol ederek aynı şeyleri sıfırdan yeniden uygulamaktan kaçınmak önemli
• Protokoller hâlâ olgunlaşma aşamasında olsa da, iyi bilinen URL keşfi, tiplenmiş şemalar ve standart olay akışları gibi kalıpları erken benimsemek, araçlar, servisler ve ajan ekosistemiyle uyumluluk sağlıyor

[carnoxen]

Böyle toparlayınca yapay zeka ile ilgili protokollerin inanılmaz fazla olduğu görülüyor.