A2A Gateway
Genel Bakış
A2A (Agent2Agent), farklı sağlayıcılara ait AI ajanlarının birbirleriyle standart bir protokol üzerinden görev alışverişi yapmasını sağlayan açık bir protokoldür. Apinizer'da A2A, diğer proxy tipleriyle (REST, SOAP, AI, MCP) aynı seviyede birinci sınıf bir API Proxy tipidir — kendi başına ayrı bir yönetim ekranı veya kimlik doğrulama modeli taşımaz, mevcut API Proxy yaşam döngüsünün (deploy, redeploy, rollback, export/import) tamamını paylaşır.
Önceki sürümlerde bir ajan yayınlamak, kendi CRUD ekranına, tek bir hedef proxy'ye ve kendi kimlik doğrulama moduna (Yok / API Anahtarı) sahip ayrı bir "A2A Inbound Agent" kaydı gerektiriyordu. Bu model tamamen kaldırıldı. Artık ajan yayınlamak, A2A tipinde bir API Proxy oluşturup onun yönlendirme modunu seçmekten ibarettir; kimlik doğrulama da proxy'nin normal politika zincirinden gelir. Ayrıca yeni modelde dış bir A2A ajanına passthrough yapabilme ve birden çok dış ajanı tek proxy arkasında birleştirebilme gibi eski modelde bulunmayan yetenekler eklendi. Ayrıntı için bu sayfanın sonundaki Eski Sürümden Geçiş bölümüne bakın.
Bir A2A Gateway, Yönlendirme sekmesindeki Routing Modu ayarına göre iki yönlendirme modundan biriyle çalışır:
- Agent'ı Apinizer yayınlar (bu sayfada Agent Yayınla) — proxy, kendi LLM yapılandırmasıyla desteklenen bir A2A ajanı olarak kendini yayınlar
- Dış bir agent'a yönlendir (bu sayfada Passthrough) — proxy görevleri dış bir A2A ajanına iletir, yol boyunca skill filtresi ve agent card yeniden yazımı uygular
Menüdeki A2A Gateway girişi, A2A Gateway'lerinizin kart görünümlü listesini açar — LLM Gateway'lerle aynı düzen; bir kartı açtığınızda o proxy'nin yönlendirme, politika ve trace/trafik/analitik/görev sekmelerine ulaşırsınız.
Apinizer'ı bunun tersi yönde, yani dış A2A ajanlarına görev gönderen taraf olarak kullanmak için ayrı bir A2A Gateway'e gerek yoktur; bu, herhangi bir LLM Gateway'e eklenen A2A Çağrısı (LLM) / A2A Çağrısı (Sabit) politikasıyla yapılır, bkz. Giden Ajan Çağrısı.
A2A protokolü JSON-RPC 2.0 üzerine kuruludur. Apinizer, hem senkron görev gönderimini hem de Sunucu Tarafından Gönderilen Olaylar (SSE) ile akış (streaming) yanıtları destekler.
Hızlı Başlangıç
A2A tipinde bir API Proxy oluşturma akışını başlatın — proxy tipi zaten A2A olarak seçili gelir, bir tip seçim ekranı gösterilmez ve doğrudan minimal bir oluşturma formu açılır. Proxy'ye tek bir istemci relative path'i (örn. /a2a/asistan) atanır — bu tek yol, hem JSON-RPC trafiğini hem de discovery belgesini taşır.
Proxy'nin Yönlendirme sekmesinde Routing Modu'nu seçin: proxy'nin kendi ajanı olarak yayın yapması için Agent'ı Apinizer yayınlar, dış bir A2A ajanına geçiş yapması için Dış bir agent'a yönlendir. Aşağıdaki Modlar bölümüne bakın.
Agent Yayınla modunda aynı Yönlendirme sekmesinde bir LLM hedefi seçmeniz zorunludur — bu ayarlanmadan yönlendirme kaydedilemez. Passthrough modunda arka uç A2A ajanını/ajanlarını satır içi tanımlayın ve gerekiyorsa skill izin listesini daraltın.
Proxy'yi normal bir API Proxy gibi bir ortama deploy edin. Deploy geçmişi, redeploy ve rollback davranışı diğer proxy tipleriyle birebir aynıdır.
Bir A2A istemcisi önce {relativePath}/.well-known/agent-card.json üzerinden ajanı keşfeder, ardından proxy'nin relative path'ine JSON-RPC ile görev gönderir (SendMessage, ...). Discovery belgesi kimlik doğrulamadan muaftır; asıl erişim kontrolü, istek proxy'nin politika zincirinden geçerken uygulanır.
Modlar
Agent Yayınla (Agent Expose)
Agent'ı Apinizer yayınlar olarak seçilir. Proxy kendi Agent Card'ını yayınlar ve görevleri kendi LLM backend'i (Yönlendirme sekmesindeki LLM hedefleri) üzerinden işler — başka bir proxy'ye devir (loopback) yoktur. Agent Card ayarlarında açıklama override'ı, girdi/çıktı modaliteleri ve manuel bir skill listesi tanımlanabilir; skill listesi boş bırakılırsa proxy'nin adı ve açıklamasından tek bir varsayılan skill türetilir — kart hiçbir zaman boş/doğrulanmamış yayınlanmaz.
Push bildirimleri bu modda proxy bazında açılıp kapatılabilir; ayrıca cluster-içi (private network) hedeflere push gönderilmesine izin verecek ayrı bir anahtar vardır (bkz. Güvenlik ve Governance).
Passthrough
Dış bir agent'a yönlendir olarak seçilir. Proxy'ye gelen her A2A çağrısını, arka uç bir A2A ajanına iletir. Dış ajanın Agent Card'ı, bu proxy'nin kendi adresini ve gerçek kimlik doğrulama şemasını yansıtacak şekilde yeniden yazılarak (hostname + güvenlik şeması rewrite) yayınlanır — istemci hiçbir zaman dış ajanın gerçek adresini görmez. Bir skill izin listesi ile Agent Card'da hangi skill'lerin yayınlanacağı daraltılabilir.
Skill izin listesi (ve aşağıdaki kimlik bazlı erişim listesi) Passthrough modunda yalnızca Agent Card yayınında uygulanır — A2A'nın kablo protokolü, MCP'nin araç çağrısındaki gibi çağrı-anında hangi skill'in hedeflendiğini taşıyan bir alan içermez. Bu nedenle bir görev gönderme çağrısı (SendMessage) çağrı anında skill bazında filtrelenemez: izinsiz bir skill Agent Card'da hiç görünmez, ama o skill adını başka bir yoldan zaten bilen bir çağıran yine de bir görev gönderebilir. Gerçek yetkilendirme bu durumda dış ajanın kendi tarafına kalır.
Passthrough modundaki arka uç A2A ajanı/ajanları, proxy'nin Yönlendirme sekmesinde, ayrı bir bağlantı ekranına gitmeden doğrudan tanımlanır:
Yönlendirme sekmesinin Passthrough bölümünde Sunucu Ekle ile bir satır açın; ajanın uç nokta adresini, kimlik doğrulama bilgilerini ve gerekiyorsa mTLS ayarlarını aynı satırda girin.
Proxy ilk kez deploy edildiğinde Apinizer, tanımlı ajanın/ajanların Agent Card'ını otomatik getirir; yetenekler ve desteklenen modaliteler doğrulanır.
Gönderilen görevlerin durumunu proxy detayındaki Görevler sekmesinden canlı izleyin.
Arka uç ajan, hedefin gerektirdiği kimlik doğrulama şemasına göre yapılandırılır; OAuth2 client credentials akışı da dahil olmak üzere token gerektiren hedeflere bağlanabilirsiniz — token alımı çalışma zamanında otomatik yapılır. Kullanılabilir şemalar için Giden Kimlik Doğrulama bölümüne bakın.
Passthrough yapılandırması APIops REST API ile de yönetilebilir; bkz. API Referansı: API Proxies — Update A2A Routing.
Arka Uç Ajanı Uygulamak: Listeye Uygula → Kaydet → deploy
Arka uç ajanı, satırın sağından açılan çekmecede eklersiniz veya düzenlersiniz. Çekmecedeki Listeye Uygula düğmesi değişikliği yalnızca tabloya yazar — o adımda sunucuya hiçbir şey gitmez. Kalıcı olması için sekmenin altındaki Kaydet düğmesine basmanız gerekir; kaydedilmemiş değişiklik varken sekmenin üstünde bir uyarı durur ve bu uyarı yalnızca kayıt başarılı olduğunda kalkar. Sıra şudur: Listeye Uygula → Kaydet → deploy. Ortadaki adım atlanırsa tabloda yeni ajan görünür, gateway ise eski yapılandırmayı sunmaya devam eder.
Gateway her zaman en son deploy edilen yapılandırmayı sunar. Yönlendirme sekmesini kaydetmek tek başına çağıranların gördüğünü değiştirmez; arka uç ajanlar, yayınlanan skill kataloğu ve yönlendirme modu ancak proxy'yi o ortama yeniden deploy ettiğinizde istemcilere ulaşır. Kaydedilmiş ama deploy edilmemiş değişiklik varken, etkilenen ortamları adlarıyla listeleyen bir uyarı şeridi Yönlendirme sekmesinin üstünde görünür.
Giden Ajan Çağrısı
Apinizer üzerinden dış bir A2A ajanına görev göndermek istediğinizde, bu görevi fiilen ileten bileşen A2A Çağrısı (LLM) politikasıdır (bir LLM Gateway'inin yanıt akışına eklenir). Hedef ajan, Passthrough modundaki gibi politikanın kendi ekranında satır içi tanımlanır. Modelin kararından bağımsız, yönetici tarafından sabit bir skill çağrısı yapmak — istek akışında veya hata akışında — için A2A Çağrısı (Sabit) bölümüne bakın.
Bir LLM Gateway'inin yanıt akışına A2A Çağrısı (LLM) politikasını ekleyin.
A2A Ajanı (Satır İçi) bölümünde uç nokta adresini, kimlik doğrulama bilgilerini ve gerekiyorsa mTLS ayarlarını girin.
Skill'leri Keşfet / Yeniden Tara butonu ajana bağlanır, Agent Card'ı getirir ve skill listesini doğrular — kaydetmeden önce çalışır, ayrı bir "bağlantıyı test et" adımı yoktur.
Boş bırakılırsa keşfedilen tüm skill'lere izin verilir. Kısıtlamak için İzinli Skill'ler listesinden seçim yapın.
Bu ajan tanımı da Passthrough modundakiyle aynı SSRF korumasına tabidir (bkz. Güvenlik ve Governance). Politika ekranındaki A2A Bağlantısı alanı geriye dönük uyumluluk için korunur: satır içi ajan tanımlıyken devre dışı kalır, çalışma zamanında ikisinden yalnızca biri kullanılır.
Girdiğiniz uç nokta, görevlerin gönderildiği adrestir — ajanın görev temel adresini (base URL) girin, kart adresini değil. Ajanın Agent Card'ı önce aynı adreste aranır; kart orada yayınlanmıyorsa bu adresin altındaki standart keşif yolunda (.../.well-known/agent-card.json) aranır. Doğrudan kart adresini (.../.well-known/agent-card.json) girerseniz kart keşfi çalışır ancak görevler de aynı adrese gönderildiğinden görev gönderimi başarısız olur.
Bu politika da APIops REST API ile eklenip güncellenebilir; bkz. API Referansı: Policies.
A2A Çağrısı (Sabit)
A2A Çağrısı (Sabit) politikası, modelden bağımsız olarak yönetici tarafından önceden seçilmiş tek bir skill'i dış bir A2A ajanına gönderir. A2A Çağrısı (LLM)'den farklı olarak modelin bir araç çağrısı döndürmesini beklemez; herhangi bir proxy tipinin istek akışında veya hata akışında çalışabilir.
| Alan | Açıklama |
|---|---|
| Hedef Skill | Çağrılacak skill; ajanın keşfedilmiş skill listesinden seçilir. Katalogda bulunmayan skill fail-closed reddedilir. |
| Mesaj Şablonu | Ajana gönderilen mesaj gövdesi. ${DEGISKEN_ADI} ortam değişkenleri önce çözülür; #{...} bağlam değişkenleri sonra çözülür. |
| Bekleme Modu | Gönder ve Unut (varsayılan) — çağrıyı asenkron dağıtır, akışı bloklamaz. Değişkene Senkron — sonucu bekler ve belirtilen çıktı değişkenine yazar. |
| Çıktı Değişken Adı | Yalnızca Bekleme Modu Değişkene Senkron olduğunda zorunludur. |
| Çağrı Zaman Aşımı (ms) | Gönderme başına HTTP zaman aşımı. Varsayılan: 30 000 ms. |
| Görev Bekleme Zaman Aşımı (ms) | Asenkron görev bekleme döngüsü için toplam süre sınırı. Varsayılan: 60 000 ms. |
Hata davranışı. İki başarısızlık kategorisi vardır:
- Yapılandırma sorunları — satır içi ajan ayarlanmamış, hedef skill boş ya da ortam değişkeni çözülememiş, skill katalogda yok veya çağıranın kimliği erişim kurallarınca reddedilmiş — isteği HTTP 500 / ERR-286 ile bloklar.
- Dağıtım başarısızlıkları — zaman aşımı, uzak ajan hatası veya taşıma hatası — yalnız loglanır, istek veya hata akışını asla bloklamaz. Değişkene Senkron modunda çıktı değişkeni boş kalır; kullanmadan önce kontrol edin.
Ajan sonucu çıktı değişkenine kişisel veri maskeleme uygulanmadan yazılır.
Bu politika da APIops REST API ile eklenip güncellenebilir; bkz. API Referansı: Policies.
Yalnız Yanıt Akışı
A2A Çağrısı (LLM) politikası, modelin döndürdüğü araç çağrıları üzerinde çalışır. Bu çağrılar yalnız yanıtta bulunur. Bu yüzden proxy bu politikayı ve MCP Çağrısı (LLM) politikasını yalnız yanıt akışında kabul eder. Platform hatada bunları "A2A Agent Call" ve "MCP Tool Call" adlarıyla anar. Birini istek akışına veya hata akışına koyan kayıt şu mesajla reddedilir: "MCP Tool Call and A2A Agent Call policies can be placed only in the response flow". Denetim proxy düzeyini, metot düzeyini ve politika gruplarını kapsar. Her kayıt yolu için geçerlidir: APIops REST API ve içe aktarma dahil. Platform politikayı sizin yerinize başka bir akışa taşımaz. A2A Çağrısı (Sabit) ve MCP Çağrısı (Sabit) politikaları bu denetimin dışındadır.
Giden Kimlik Doğrulama
Passthrough proxy'nin A2A ajan satırı ve A2A Çağrısı politikalarının satır içi ajanı, MCP sunucusuyla aynı kimlik doğrulama şemalarını kullanır. Şemalar (Yok, Bearer Token, OAuth2 Client Credentials, mTLS, API Anahtarı (Başlık), Basic Kimlik Doğrulama ve OAuth2 Token Exchange), token exchange kuralları ve Auth Keşfet düğmesi için Arka Uç Kimlik Doğrulama bölümüne bakın.
A2A için farklar:
- Auth Keşfet, Agent Card'ı girdiğiniz adresten, sonra bu adresin
/.well-known/agent-card.jsonyolundan okur. Şemayı kartın güvenlik şemalarından önerir ve hem düz biçimi hem A2A 1.0 biçimini kabul eder. Kart okunamazsa bir not görünür. - Token exchange token'ıyla yapılan çağrı 401 veya 403 alırsa gateway yeniden denemez.
- Skill'leri Keşfet / Yeniden Tara ve sağlık denetimi exchange token'ı alamaz, çünkü çağıran token'ı taşımazlar. Bu şemada kart okuma reddedilir.
Agent Card, Görev Yaşam Döngüsü ve Streaming
Agent Card
Her ajan (Agent Yayınla modunda proxy'nin kendisi, Passthrough modunda yeniden yazılmış dış ajan) .well-known/agent-card.json üzerinden kendini tanıtan bir Agent Card yayınlar:
{
"name": "Asistan Proxy",
"description": "Müşteri destek ajanı",
"version": "1.0",
"capabilities": { "streaming": true, "pushNotifications": true },
"defaultInputModes": ["text", "image", "data"],
"defaultOutputModes": ["text"],
"skills": [
{ "id": "asistan-proxy", "name": "Asistan Proxy", "description": "Müşteri destek ajanı" }
],
"securitySchemes": {
"bearerAuth": { "type": "http", "scheme": "bearer" }
}
}
Kartın güvenlik bilgisi (securitySchemes) kart yalan söylemez ilkesiyle, sabit bir listeden değil, proxy'nin fiilen tanımlı olan auth politikalarından türetilir — hiç auth politikası yoksa alan boş kalır, asla yanlış bir şema ilan edilmez. Ayrıntı için Karttaki Güvenlik Şemaları bölümüne bakın. Agent Card bu sürümde imzasız yayınlanır ve insan-onaylı (human-in-the-loop) görev onayı desteklenmez.
Passthrough modunda yeniden yazılan kartın documentationUrl alanı, arka uç ajanın değil bu proxy'nin gateway üzerindeki tam adresini gösterir — ortamın erişim adresi, Apinizer kök bağlamı ve proxy'nin istemci yolu birlikte — böylece adresi izleyen istemci doğrudan gateway'e ulaşır. Ortamda erişim adresi tanımlı değilse alan kök-göreli olur — Apinizer kök bağlamı ve proxy yolu; ikisi de tanımlı değilse yalnızca proxy yoluna düşer.
Kimlik doğrulaması gerektiren bir kanaldan (istekte proxy'nin auth politika zinciri geçildikten sonra) aynı kart GetExtendedAgentCard JSON-RPC metoduyla da alınabilir — kimlik bazlı erişim listesi tanımlıysa bu çağrı, çağıranın kimliğine göre kişiselleştirilmiş bir skill kümesi döndürebilir; herkese açık discovery uç noktası ise her zaman kimliklenmemiş bir çağıranmış gibi değerlendirilir.
Karttaki Güvenlik Şemaları
Kart, proxy'nin kimlik doğrulama zincirini A2A 1.0 biçiminde tanımlar. Her şema, önceki kartlarda da bulunan düz alanları (type, scheme) korur. Eski biçimi okuyan istemci eskiden gördüğünü görür. 1.0 istemcisi yeni biçimi kullanır.
| Kimlik doğrulama politikası | Karttaki şema |
|---|---|
Apinizer Credential yetkilendirme sunucusunun (/credential/...) token'ını kullanan JWT veya OAuth2 politikası | Credential yetkilendirme sunucusunun token ucuna bir OAuth2 akışı. Her credential'ın kendi grant'ı olduğu için akış her zaman client credentials'tır. Token adresi https ise şema o sunucunun meta veri adresini (RFC 8414) de belirtir. |
Token'ı kendi ucundan veren JWT veya OAuth2 politikası (/auth/..., politika yönetimli) | O uca, politikanın grant'ıyla bir OAuth2 akışı (password olabilir). |
JWT token'ı veren politika (/jwt ucu) | Bir bearer (JWT) şeması. Meta veri bu token biçimine götürmediği için kart RFC 8414 meta veri adresi yazmaz. |
| https issuer'lı OpenID Connect politikası (provider modu dahil) | Issuer'ın keşif adresiyle bir OpenID Connect şeması. |
| https issuer'ı olmayan OpenID Connect politikası | Bir bearer (JWT) şeması. OAuth akışına geri dönülmez. |
| Bearer başlığını kabul etmeyen politika | Token şeması yok. |
| Başka bir issuer'ın token'ını yalnız doğrulayan JWT politikası | Bir bearer (JWT) şeması. |
| Basic veya Digest | Bir HTTP şeması (basic veya digest). |
| API anahtarı | Anahtarın yeri ve adıyla bir API anahtarı şeması. |
| Bearer API anahtarı | Bir HTTP bearer şeması. |
| mTLS | Bir karşılıklı TLS şeması. |
- Zincir toplamalıdır: her politika çalışır. Kart ve her skill, tüm şemaları adlandıran tek bir güvenlik gereksinimi taşır.
- Hiçbir A2A istemcisinin olduğu gibi karşılayamayacağı politika kartta görünmez.
- Passthrough modunda arka uç ajanın kartı yeniden yazılır. Skill'ler arka uç ajanın değil gateway'in gereksinimlerini taşır, çünkü istemci gateway'e kimlik doğrular.
Korunan Kaynak Meta Verisi
Her A2A Gateway ayrıca proxy'nin istemci yolu artı /.well-known/oauth-protected-resource adresindeki kimliksiz GET isteğine yanıt verir (RFC 9728). Belge kaynağı ve token'ları veren yetkilendirme sunucusunu adlandırır. İstemci token'ı nereden alacağını bulur.
Gateway belgeyi yalnız şu koşulların hepsi doğruysa yayınlar:
- Proxy'yi en az bir etkin kimlik doğrulama politikası korur ve hepsi tek bir yetkilendirme sunucusunun (Apinizer Credential yetkilendirme sunucusu ya da tek bir kimlik sağlayıcı) Bearer token'ını kabul eder.
- Ortamda erişim adresi tanımlıdır.
- Yetkilendirme sunucusunun issuer'ı https adresidir.
- Zincir Apinizer Credential yetkilendirme sunucusunun JWT token'larını kullanmaz. Bu sunucunun meta verisi opak token'lara götürür, bu yüzden gateway bu biçim için belgeyi yayınlamaz.
Diğer her durumda adres gövdesiz 404 döndürür. Örnekler: proxy anahtarı token'ı veren politika, birden fazla yetkilendirme sunucusunun token'ları, aynı zincirde JWT ve OAuth2 politikası, token olmayan bir kimlik bilgisi isteyen politika ya da JWT imzasını yerel olarak do ğrulamayan politika.
Bu yalnız keşif bilgisidir. A2A Gateway'in oturum açma profili yoktur. Token denetimi ve 401 yanıtı eskisi gibi çalışır. Belge, Yönlendirme sekmesindeki Keşif kartında gösterilir.
İstemci kimliği meta veri belgeleri (CIMD) ve açık istemci (public client) kaydı bu sürümde yoktur. Gateway bunları ilan etmez. İstemci, token'larını veren yetkilendirme sunucusuna kayıt olur: kimlik sağlayıcıya ya da Credential yetkilendirme sunucusuna gizli istemci olarak. https URL biçimindeki client_id kayıtsız istemci olarak reddedilir (invalid_client).
Keşif Kartı
Yönlendirme sekmesinde salt okunur bir Keşif kartı bulunur. Kart, proxy'nin bir ortamı için şunları gösterir:
- Agent card adresi,
- Korunan kaynak meta verisi adresi ya da gateway'in belgeyi neden yayınlamadığı,
- Yetkilendirme sunucusu (issuer ve bunun Apinizer Credential AS mi yoksa kimlik sağlayıcı mı olduğu).
Karttan hiçbir şeyi değiştiremezsiniz. Kart gateway ile aynı kuralları kullanır. Kartta "Yayınlanmıyor" görürseniz gateway 404 döndürür.
Protokol Sürümü
A2A protokolünün tek desteklenen sürümü 1.0'dır (alan gelecekteki bir sürüm genişlemesi için ayrı tutulmuştur) — MCP'nin aksine bir sürüm seçimi yapmanız gerekmez.
Görev Yaşam Döngüsü
İstemciler SendMessage metodu ile görev gönderir; görev durumu GetTask/ListTasks ile sorgulanabilir, CancelTask ile iptal edilebilir:
{
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {
"message": {
"role": "user",
"parts": [{ "type": "text", "text": "Siparişimin durumu nedir?" }]
}
}
}
Agent Yayınla modunda Apinizer'ın kendi ajanı bir görevi yalnızca şu durumlar arasında ilerletir: submitted → working → completed / failed / canceled / rejected. Diğer iki durum (input-required, auth-required) Apinizer'ın kendi ajanı tarafından hiç üretilmez; bunlar yalnızca Apinizer'ın giden istemci olarak konuştuğu dış ajanlarda gözlemlenebilecek durumlardır.
| Durum | Anlamı |
|---|---|
submitted | Görev alındı, işleme henüz başlamadı |
working | Görev işleniyor |
completed | Görev başarıyla tamamlandı |
failed | Görev hata ile sonuçlandı |
canceled | Görev iptal edildi |
Passthrough modunda görevlerin sahibi arka uç ajandır; bu yüzden GetTask ve CancelTask iki adımda çözülür: proxy önce kendi izlediği görevler arasında arar (akış/streaming relay'i gateway tarafından izlenir), gelen kimlik bunlardan biri değilse çağrı arka uç ajana iletilir ve ajanın yanıtı olduğu gibi döndürülür — görev orada da bilinmiyorsa ajanın kendi "görev bulunamadı" yanıtı dahil. İstemcinin, Passthrough SendMessage çağrısından aldığı görev kimliğini doğrudan sorgulayabilmesini sağlayan davranış budur. Bir görev kimliğinin okunup okunamayacağına/iptal edilip edilemeyeceğine, iletilen mesajın yetkilendirmesinde olduğu gibi arka uç ajan karar verir. ListTasks ve SubscribeToTask her zaman gateway'in kendi görev kayıtlarından yanıtlanır, arka uca iletilmez; birden fazla ajanı birleştiren bir proxy'de ise GetTask/CancelTask, görevin hangi ajana ait olduğunu tahmin etmek yerine hata döndürür.
Gateway CancelTask çağrısını kendi görev kayıtlarından yanıtladığında (Agent Yayınla modu ve Passthrough proxy'nin kendi izlediği görevler), terminal durumda olan bir görev (completed, failed, canceled veya rejected) JSON-RPC -32002 hatasını (TaskNotCancelableError) alır. Mesaj şudur: "Task cannot be canceled: it is already in a terminal state or not cancelable." Görev artık başarılı sonuç olarak dönmez. Zaten iptal edilmiş bir göreve ikinci CancelTask çağrısı aynı hatayı alır ve görev canceled kalır. Görev sizin çağrınızla aynı anda biterse ya da iptal edilirse de aynı hata döner. İptal başka bir nedenle tamamlanamazsa yanıt, "Task could not be canceled, try again." mesajlı bir JSON-RPC iç hatasıdır.
Gateway'in kendi tuttuğu görev kayıtları terminal durumlara (completed/failed/canceled) ulaştığında bir süre sonra otomatik temizlenir; aktif görevler süresiz saklanır. Passthrough modunda akış dışı bir çağrıyla oluşan görevin saklama süresine arka uç ajan karar verir.
Akış (Streaming) ve Yeniden Abone Olma
İstemciler SendStreamingMessage metoduyla görev güncellemelerini baştan itibaren SSE üzerinden chunk chunk alabilir. Bağlantı kesilirse istemci SubscribeToTask metoduyla, saklanan görev geçmişinden yeniden oynatma ile kaldığı yerden akışa yeniden abone olarak devam edebilir.
Push (Webhook) Tamamlanma Bildirimi
Uzun süren görevler için istemciler, CreateTaskPushNotificationConfig metoduyla görev başına bir webhook hedefi + kimlik doğrulama bilgisi kaydedebilir (yönetimi için ayrıca GetTaskPushNotificationConfig/ListTaskPushNotificationConfigs/DeleteTaskPushNotificationConfig metotları vardır). Görev tamamlandığında/başarısız olduğunda Apinizer bu webhook'a bir bildirim isteği gönderir. Bu, uzun süren ajan görevleri için sürekli sorgulamaya (polling) göre birincil tamamlanma bildirim kanalıdır.
Çok-Modaliteli Görev Parçaları
Bir görev, metin dışında görsel ve yapılandırılmış veri içeren parçalar (part) taşıyabilir.
Desteklenen görev parçası türleri metin, yapılandırılmış veri ve görseldir. Ses ve video türleri bu kapsamda değildir.
Çoklu Hedef (Aggregation)
Passthrough modunda, Yönlendirme sekmesindeki satır içi ajan listesine en fazla 10 arka uç A2A ajanı eklenebilir. Apinizer bu ajanların Agent Card skill kataloglarını tek bir kartta birleştirir; farklı ajanlarda aynı isme sahip skill'ler deterministik biçimde ajanAdı__skillAdı şeklinde isimlendirilerek çakışma önlenir.
Bu birleştirme yalnızca Agent Card/skill keşfi seviyesindedir. Birden fazla hedef yapılandırıldığında SendMessage dispatch'i desteklenmez — A2A'nın kablo protokolünde MCP'nin araç çağrısındaki gibi bir hedef-skill alanı olmadığından, isteği hangi ajana yönlendireceğini güvenle seçmek mümkün değildir; bu durumda çağrı sessizce ilk hedefe yönlendirilmek yerine açık bir hata döner. Tek bir ajan yeterliyse listeye tek satır eklemek yeterlidir; davranış önceki (tek-hedef) sürümle birebir aynı kalır.
Güvenlik ve Governance
Kimlik doğrulama artık proxy'nin normal politika zincirinden gelir — JWT, OIDC, API Anahtarı, Basic gibi mevcut tüm auth politikaları A2A Gateway'lerinde de kullanılabilir; eski modeldeki Yok/API Anahtarı ikilisiyle sınırlı değildir. Discovery belgesi (.well-known/agent-card.json) ve korunan kaynak meta verisi adresi bu zincirden muaftır ve her zaman açık erişimlidir.
Aynı politika zincirinden Kişisel Veri (PII) Maskeleme, İstem Koruması, Veri Sızıntısı Koruması (DLP), Konu Koruyucu ve Tekrar-Fırtınası (Loop) Koruması gibi gelişmiş korumalar da geçer — gönderilen görevin mesaj parçalarına (parts[], hem metin hem yapılandırılmış veri) uygulanır. Bir A2A Gateway'ine yalnızca bu beş koruma eklenebilir; bir LLM çağrısına doğrudan bağlı diğer AI politikaları (Semantik Önbellek, Token Rate Limit, Prompt Süsleyici, Prompt Şablonları, RAG, Bağlam Bütünlüğü Koruması) kaydetme adımında reddedilir. İstem Koruması ve Konu Koruyucu bir A2A Gateway'inde kullanıldığında, aynı politikaların taşıdığı dış sağlayıcı guardrail desteği de bu proxy'de aynen çalışır — görevin mesaj parçaları, tanımlıysa bir dış LLM hakemine de gönderilir.
Aşağıdaki governance özellikleri API proxy yapılandırmasının bir parçasıdır. Kimlik bazlı erişim listesini Yönlendirme sekmesindeki Passthrough ayarlarında Kimlik Erişim Kuralları bölümünden ayarlarsınız. Bu özelliklerin hepsi APIops ile de ayarlanabilir:
- Kimlik bazlı erişim listesi (identity-ACL) — yalnızca Passthrough modunda uygulanır ve yalnız Agent Card'daki skill listesini daraltır, çağrıyı engellemez; Agent Yayınla modunda bu liste hiç değerlendirilmez, proxy kendi Agent Card'ını her zaman herkese aynı şekilde yayınlar. Passthrough'ta opsiyoneldir: boş bırakılırsa mevcut skill izin listesi/keşif davranışı aynen sürer. Doldurulursa default-deny olur: tüketici / API istemcisi, rol veya organizasyon bazında tanımlanan kurallarla eşleşmeyen bir çağıran hiçbir skill'i Agent Card'da göremez. Yukarıdaki uyarıda belirtildiği gibi, bu yalnızca kart yayınını daraltır,
SendMessageçağrısını çağrı-anında gate'lemez. - Çağrı hacmini sınırlama — A2A routing'in kendine ait bir çağrı kotası yoktur. Kimlik bazlı
SendMessagelimitlerini (tüketici, API istemcisi, uygulama veya organizasyon başına) Limit Planı ile ayarlayın. Proxy'yi tüm çağıranların toplamına karşı Kota veya Throttling politikasıyla koruyun. Önceki sürümde kaydedilmiş bircallQuotadeğeri yok sayılır ve routing'in bir sonraki kaydında silinir. - Katalog sapması (catalog drift) koruması — bir A2A ajanının skill kataloğu ilk keşfedildiğinde (veya elle yeniden keşfedildiğinde) onaylanan katalog bir özet (hash) olarak sabitlenir; periyodik bir sağlık kontrolü canlı kataloğu bu özetle karşılaştırır. Varsayılan davranış (yalnızca uyar) sapmayı loglar ve uyarı üretir ama çağrıları engellemez; kapalı-güvenli davranış seçilirse, katalog yeniden onaylanana kadar sapma tespit edilen ajan üzerindeki çağrılar reddedilir. MCP ile aynı mekanizmayı paylaşır.
- Dağıtımda katalog keşfi — A2A Çağrısı (LLM) veya A2A Çağrısı (Sabit) politikasının satır içi ajanında skill kataloğu ve onaylı özet (hash) yoksa, ilk katalog proxy'yi dağıttığınızda alınır. Dağıtımda Manager, worker proxy'yi almadan önce ajanın Agent Card'ını bir kez okur. Bir dağıtımın tüm sorguları paralel çalışır; tüm dağıtım için toplam 30 saniyelik tek bir süre sınırı vardır. Başarılı ilk sonuç skill kataloğu olarak kaydedilir ve onaylı başlangıç noktası olur; sonraki değişiklikler buna karşı denetlenir. Kataloğu ya da onaylı özeti olan ajan yeniden sorgulanmaz. Tespit edilmiş bir sapmayı dağıtım onaylamaz. Skill döndürmeyen, erişilemeyen veya 30 saniye içinde yanıt vermeyen ajan dağıtımı durdurmaz. Dağıtım sonucunda o ajan için bir WARNING satırı görünür ve katalog keşfedilene kadar çağrıları reddedilmeye devam eder. Skill'leri Keşfet / Yeniden Tara'yı kullanın ve yeniden dağıtın. Kimlik doğrulama şeması OAuth2 token exchange olan ajan dağıtımda sorgulanmaz; dağıtım anında istemci token'ı yoktur ve zamanlanmış A2A sağlık denetimi de aynı nedenle onu atlar. Bu ajan için WARNING satırı yazılmaz. Skill kataloğunu Skill'leri Keşfet / Yeniden Tara ile alın. Passthrough proxy'nin Yönlendirme sekmesindeki ajanlar dağıtımda sorgulanmaz.
- Token passthrough (opt-in) — çağıranın kendi token'ının backend agent'a iletilmesi varsayılan olarak her yerde kapalıdır. Yönlendirme sekmesindeki "istemci token'ını ilet" seçeneği tek başına yeterli değildir; iletimin fiilen etkinleşmesi için ayrıca (APIops ile) açık bir onay + opsiyonel bir hedef-kitle (audience) izin listesi yapılandırılması gerekir. Bir iletim denemesi başarısız olursa (özellik kapalı, token bulunamadı veya hedef kitle eşleşmedi) ajanın kendi kimlik bilgisi kullanılmaya devam eder — kimliksiz bir çağrı asla arka uca sessizce geçmez.
Passthrough çağrıları (Agent Card getirme + görev gönderimi) SSRF (Server-Side Request Forgery) koruması altındadır:
Giden A2A çağrıları (Agent Card getirme, görev gönderimi, sağlık yoklaması, push bildirimi) varsayılan olarak yalnız https kabul eder. Tüm özel ve ayrılmış adresleri (loopback, link-local, bulut metadata, CGNAT, multicast, RFC1918, IPv6 ULA) reddeder.
Ajan tanımındaki Özel ağ (cluster-içi) egress'ine izin ver ayarı bu korumayı o ajan için kaldırır. Push bildirimlerinde aynı korumayı proxy'nin Yönlendirme sekmesindeki Cluster-içi push egress'ine izin ver ayarı kaldırır. İkisini de yalnız sistem yöneticisi açabilir. Ayar açıkken hiçbir adres sınıfı engellenmez: loopback, link-local, bulut metadata adresi 169.254.169.254, 100.64.0.0/10, 0.0.0.0/8, multicast, RFC1918 ve IPv6 ULA'ya erişilir; düz http de kabul edilir. Ayarı açmak bulut metadata adresini de açar. Yalnız güvendiğiniz ajanlar için açın.
Push webhook URL'lerini çağıran istemci gönderir. Push egress ayarı açıkken bir çağıran webhook'u loopback veya metadata adresine yöneltebilir. Ayarı yalnız ajanı çağırabilen tüm istemcilere güveniyorsanız açın.
Ayar açıkken de yalnız http ve https URL'leri kabul edilir, URL geçerli olmalıdır, ana makine adı çözülmelidir ve bağlantı çözülen adreslere sabitlenir (DNS rebinding savunması).
Push bildirimleri için de aynı mantık geçerlidir: webhook hedefleri varsayılan olarak özel IP aralıklarına gönderilemez; yalnızca güvenilir cluster-içi hedefler için ayrı bir anahtarla bu kısıtlama proxy bazında gevşetilebilir.
Bu koruma MCP Gateway giden sunucu tanımları tarafından da paylaşılır.
Yapılandırmada Ortam Değişkenleri
A2A Gateway yapılandırmasına yazdığınız metinlerin çoğu ${DEGISKEN_ADI} biçiminde ortam değişkeni referansı kabul eder; değer proxy'nin çalıştığı ortama göre çözülür ve aynı yapılandırma test ortamından canlıya elle düzenlenmeden taşınır.
Değişken kabul eden alanlar:
| Nerede | Alanlar |
|---|---|
| Giden ajan çağrısı | Yetenek adı, mesaj şablonu |
| Erişim kuralları | İzinli yetenek listesi, kimlik kuralındaki kullanıcı/rol/organizasyon adı, izin ve ret listeleri |
| Token aktarımı | Kabul edilen hedef kitle listesi |
Mesaj şablonu ayrıca #{...} biçimindeki bağlam değişkenlerini de kabul eder; bunlar ortam değişkenleri yerleştirildikten sonra her istek için değerlendirilir.
Çözümleme, MCP Gateway tarafındaki ile birebir aynı şekilde fail-closed çalışır: tanımsız bir değişkende metin yazıldığı gibi kalır, bu da gerçek hiçbir yetenek veya hedef kitle ile eşleşmez; çağrı yanlış bir eşleşmeye düşmek yerine reddedilir. Çağıran taraf da yetenek adı olarak birebir ${DEGISKEN_ADI} metnini gönderip erişim kuralını aşamaz.
Push bildirim ayarları bilinçli tek istisnadır: webhook adresi ve token'ı operatörden değil, çalışma anında çağıran istemciden gelir; bu nedenle her zaman düz metin kabul edilir. Bunların çözülmesi, çağıran tarafın gateway'e kendi ortam değerlerinden birini kendi kontrolündeki bir webhook'a yazdırabilmesi anlamına gelirdi.
Loglama ve Analytics
A2A tipindeki bir proxy'nin detay sayfasında da Trace, Trafik ve Analitik sekmeleri bulunur — REST/SOAP proxy'lerindeki eşdeğer sekmelerle aynı yapıdadır (sekme adı proxy tipini tekrarlamaz, zaten o proxy'nin içindesinizdir); ayrıca yalnızca A2A Gateway'lerinde görünen bir Görevler sekmesi, gateway'in kendi izlediği görevleri canlı listeler: Agent Yayınla modundaki tüm görevler ve Passthrough modunda akış (streaming) çağrısıyla oluşan görevler. Passthrough'ta akış dışı bir çağrıyla oluşan görevin sahibi arka uç ajandır; bu görev trafik logunda görünür ancak bu sekmede listelenmez — istemcinin GetTask sorgusu da o ajan tarafından yanıtlanır (bkz. Görev Yaşam Döngüsü). Her A2A çağrısı (gelen görev gönderimi/sorgulama/iptal, giden ajan çağrısı ve giden sağlık yoklaması), gecikme/boyut/istemci IP'si gibi standart alanların yanında A2A'ya özgü alanlarla birlikte trafik logunda görünür. Analitik sayfasının Trafik tab'ındaki "Flags" rozet kolonu bir isteğin önbellek/koruma/PII/streaming durumunu tek bakışta gösterir; ayrıntılı kullanım, maliyet ve koruma metrikleri aynı Analitik sayfasında izlenebilir — bkz. Raporlar ve Analitik.
Bir LLM Gateway'in dış ajanlara birden çok görev gönderdiği durumlarda, her görevin süresi ve sonuç durumu ayrı ayrı uçtan uca izleme kaydında (trace) görünür. Uçtan uca bir görev zincirini takip etmek için İzleme ve Tekrar Oynatma sayfasına bakın.
Giden Ajan Çağrıları: Trace'ten Bağımsız Denetim İzi
Hangi giden ajana/beceriye (skill) gidildiğinin kaydı trace açık/kapalı olmasından bağımsız olarak ana trafik satırında tutulur — trace kapalıyken (varsayılan kurulum) de kaybolmaz. Bu istek boyunca dispatch edilen tüm giden ajan çağrılarının adları iki alanla taşınır:
- Tekilleştirilmiş isim listesi — A2A'da beceri (skill) adı opsiyonel bir alan olduğu için, bir çağrıda skill adı yoksa bunun yerine ajan anahtarı (agent key) kaydedilir (boş bir liste + sıfır olmayan bir sayaç bozuk bir denetim izi olurdu). Aynı istekte tekrar eden adlar tek kez, ilk görülme sırasıyla, virgülle ayrılmış biçimde tutulur; 256 karakter tavanı vardır ve bir isim asla ortasından kesilmez — sığmayan isim(ler) bütün olarak düşer ve bu durum
,…işaretiyle belli edilir (sessiz kesme yoktur). - Ham çağrı sayacı — aynı istekte dispatch edilen tüm giden ajan çağrılarının (tekrarlar dahil) toplam sayısı; isim listesi 256 karakter sınırı nedeniyle kırpılsa bile bu sayaç gerçek toplamı taşır.
Bu denetim izi, bir guard veya kota tarafından reddedilen ajan çağrılarını da içerir — amacı yalnızca başarılı çağrıları değil, hangi ajana gidilmek istendiğini göstermektir; reddedilen bir çağrı güvenlik açısından başarılı olanı kadar (bazen daha fazla) ilgi çekicidir.
Elasticsearch ve MongoDB trafik-log connector'ları bu alanları otomatik olarak taşır. SQL/JDBC trafik-log connector'ı kullanan mevcut kurulumlar için bkz. 2026.09.0 — Log Tablosu ALTER Scriptleri.
Eski Sürümden Geçiş
Aşağıdaki ekranlar ve kavramlar kaldırıldı; otomatik bir geçiş yoktur — eşdeğerini A2A tipinde yeni bir API Proxy olarak yeniden oluşturmanız gerekir:
- Ayrı "A2A Inbound Agent" listeleme/oluşturma/düzenleme ekranı; bu kayıt tek bir hedef proxy'ye bağlıydı ve bu kayda özgü ajan bazlı kimlik doğrulama modları (Yok / API Anahtarı) taşıyordu.
- Eski istemci uç noktası
/a2a/{id}— yerini proxy'nin kendi relative path'i aldı. - A2A ajanına özgü ayrı bir deploy tipi — artık standart API Proxy deploy akışının bir parçası.
Passthrough modu, çoklu hedef birleştirme ve tam auth politika zinciri desteği, eski modelde bulunmayan yeni yeteneklerdir.
| Eski kavram | Yeni karşılığı |
|---|---|
| A2A Inbound Agent kaydı | A2A tipinde API Proxy |
| Ajan bazlı Yok/API Anahtarı modu | Proxy'nin normal auth politika zinciri |
/a2a/{id} | Proxy'nin relative path'i |
Giden Bağlantı Ekranının Kaldırılması
Ayrı bir giden A2A bağlantısı listeleme/oluşturma ekranı (ve buna karşılık gelen bağımsız APIops uç noktaları) da kaldırıldı; ajan tanımı artık yukarıda anlatıldığı gibi Passthrough modunda Yönlendirme sekmesinde, görev gönderiminde ise A2A Çağrısı (LLM) / A2A Çağrısı (Sabit) politikasının kendisinde satır içi tutulur. Ajan kartı (agent card) keşfi, sağlık yoklaması, katalog kayması (drift) koruması ve token passthrough aynı şekilde çalışmaya devam eder; artık paylaşılan bir kayda değil, ajanın kendi tanımına bağlıdır.
Bu değişiklik için otomatik bir geçiş vardır: bu eski ekrandan önceden oluşturulmuş bağlantılara sahip mevcut proxy ve politika yapılandırmaları, bir sonraki yükseltmede otomatik olarak satır içi ajan tanımına taşınır — yeniden oluşturmanız gerekmez. Aynı bağlantı birden fazla proxy/politika tarafından paylaşılıyorsa, yükseltme sonrasında her biri kendi bağımsız (kimlik bilgisi dahil) kopyasını taşır; kimlik bilgisini rotasyona sokarken bunu göz önünde bulundurun.
Sonraki Adımlar
API'lerinizi araç olarak sunun ya da dış araçlara bağlanın
DLP, döngü ve konu-dışı korumalarını yapılandırın
A2A görevlerini trace zinciriyle izleyin ve yeniden çalıştırın
Ajan protokolleri hakkında temel kavramları öğrenin