Apidog A2A Debugger ile Agent-to-Agent (A2A) Protokolü Nasıl Debug Edilir

Diğer yapay zeka ajanlarıyla konuşan yapay zeka ajanları geliştiriyorsanız, en zor kısım genellikle “ajan diğer ajana tam olarak ne gönderdi?” sorusunu yanıtlamaktır. Konsol logları eksik kalır, ağ sekmeleri A2A alanlarını okumayı zorlaştırır, özel test script’leri ise hızla kırılır. Apidog’un A2A Hata Ayıklayıcısı, Agent2Agent (A2A) protokolü için bu akışı görsel ve tekrarlanabilir hale getirir: Ajan Kartı URL’sini yapıştırın, bağlanın, mesaj gönderin ve yanıtı Önizleme, İçerik ve Ham Veri olarak inceleyin.

Apidog'u bugün deneyin

Bu kılavuzda A2A Hata Ayıklayıcının ne işe yaradığını, ilk ajan bağlantısını nasıl kuracağınızı, test mesajı gönderirken nelere bakmanız gerektiğini ve Apidog’un mevcut MCP sunucu test araçlarının yanında nerede konumlandığını adım adım göreceksiniz. Protokol farklarını önce netleştirmek isterseniz, Apidog’da MCP ile A2A karşılaştırması iyi bir başlangıçtır.

A2A Nedir?

A2A, yani Agent2Agent, ajanlar arası iletişim için açık bir protokoldür. Bir ajanın yeteneklerini nasıl duyurduğunu, başka bir ajanın ona nasıl bağlandığını, mesajların ve dosya eklerinin nasıl değiş tokuş edildiğini ve görev durumunun nasıl raporlandığını tanımlar.

A2A’yı, ajanlar arası trafik için HTTP benzeri ince bir sözleşme olarak düşünebilirsiniz. Örneğin bir LangGraph ajanı, başka bir ekibin CrewAI ajanına, iki tarafın da birbirinin iç yapısını bilmesine gerek kalmadan mesaj gönderebilir.

A2A, MCP’den farklıdır:

• MCP, tek bir ajanın araçlara ve kaynaklara erişmesiyle ilgilidir.
• A2A, bir ajanın başka bir ajanla konuşmasıyla ilgilidir.

Detaylı farklar için MCP ile A2A karşılaştırması yazısına bakabilirsiniz.

A2A Hata Ayıklayıcı Ne Sağlar?

A2A Hata Ayıklayıcı, Apidog içinde yer alan görsel bir test çalışma alanıdır. A2A uç noktalarını üretim iş akışına bağlamadan önce doğrulamak için kullanılır.

Temel kullanım alanları:

• Ajan Kartı bağlantısını doğrulama
  
  Ajan Kartı URL’sini yapıştırın, Bağlan’a tıklayın ve ajanın adını, açıklamasını, yeteneklerini, beyan edilen becerilerini ve protokol sürümünü görün.

• Mesaj gönderme
  
  Düz metin istemleri gönderin, destekleniyorsa dosya ekleyin ve özel meta veri alanları ekleyin.

• Yanıtı üç görünümde inceleme

  • Önizleme: Yapılandırılmış çıktıyı ağaç görünümünde gösterir.
  • İçerik: İnsan tarafından okunabilir çıktıyı gösterir.
  • Ham Veri: JSON-RPC yükünü olduğu gibi gösterir.

• Kimlik doğrulama ekleme
  
  
  Taşıyıcı Token, Temel Kimlik Doğrulama ve özel başlık üzerinden API anahtarı desteklenir.

• Özel başlıklar gönderme
  
  
  Ağ geçidi kimlik doğrulaması, X-Request-Id, kiracı bilgisi veya ara katman başlıkları eklenebilir.

• Oturum geçmişini izleme
  
  
  Gönderilen mesajları oturum geçmişinde görebilir, yeni test için geçmişi temizleyebilirsiniz.

Curl komutu yazmanız gerekmez. Apidog, JSON-RPC zarfını, ajan destekliyorsa SSE akışını ve yanıt ayrıştırmayı kullanıcı arayüzünde yönetir.

Adım 1: İlk A2A Ajanına Bağlanın

Başlamadan önce üç şeye ihtiyacınız var:

1. Güncel Apidog istemcisi
   
   Eski sürümler A2A Hata Ayıklayıcıyı içermeyebilir. Henüz kurmadıysanız Apidog’u indirin.

2. Ajan Kartı URL’si
   
   Bu, A2A uyumlu ajanın keşif uç noktasıdır. Yerel geliştirme ortamında genellikle şöyle görünür:
   

   http://localhost:3000/.well-known/agent.json

1. Kimlik bilgileri Ajan kimlik doğrulama istiyorsa Bearer token, API anahtarı veya Basic Auth bilgilerini hazır bulundurun.

Apidog’da A2A Hata Ayıklayıcıyı açın, Ajan Kartı URL’sini üstteki alana yapıştırın ve Bağlan’a tıklayın.

Bağlantı başarılıysa durum Bağlandı olarak değişir ve panel şu bilgileri gösterir:

• Ajan adı
• Açıklama
• Yetenekler
• Beyan edilen beceriler
• Protokol sürümü

Bağlantı başarısızsa şu kontrolleri yapın:

• URL doğru mu?
• Ajan çalışıyor mu?
• URL tarayıcıda açıldığında JSON dönüyor mu?
• Ajan Kartında gerekli alanlar var mı?
• Keşif uç noktası kimlik doğrulama istiyor mu?

Ajan Kartı biçimini doğrulamak için GitHub’daki A2A protokol spesifikasyonu ile karşılaştırabilirsiniz.

Adım 2: Test Mesajı Gönderin

Bağlantı kurulduktan sonra Mesajlar sekmesini açın ve test isteminizi yazın.

Örnek:

Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.

Göndermeden önce isteğe bağlı olarak şunları ekleyebilirsiniz:

Dosya eki

Ataç simgesine tıklayıp dosya seçin. Hata ayıklayıcı, ajanın beyan ettiği giriş türlerini kontrol eder. Desteklenmeyen dosya türleri peşinen reddedilir; böylece 415 benzeri hatalar için gereksiz istek göndermezsiniz.

Meta veri

Mesaj zarfına anahtar-değer çiftleri ekleyebilirsiniz:

priority: high
tenant: acme-corp
locale: tr-TR

Bu alanlar A2A mesaj yüküne girer. Ajanın görev işleyicisi bu meta verileri okuyorsa davranışı etkileyebilir.

Hazır olduğunuzda Gönder’e tıklayın. Apidog isteminizi A2A mesaj yapısına sarar, ajana gönderir ve yanıtı bekler.

Adım 3: Yanıtı Üç Görünümle İnceleyin

A2A yanıtları farklı biçimlerde gelebilir:

• Düz metin
• Yapılandırılmış JSON
• Dosya referansları
• Görev durumu
• Birden fazla yapıtın kombinasyonu

Apidog aynı yanıtı üç görünümde sunar.

Önizleme

Yapılandırılmış alanları okunabilir bir ağaç olarak gösterir. Özellikle şu alanları incelerken kullanışlıdır:

• Görev kimliği
• Durum
• Yapıtlar
• Geçmiş
• İç içe geçmiş nesneler

İçerik

İnsan tarafından okunabilir çıktıdır. Ajan metin döndürdüyse, kullanıcıya göstereceğiniz ana içerik genellikle buradadır.

Ham Veri

Tüm JSON-RPC yükünü gösterir. Uyumluluk kontrolü, hata raporu veya alan adı doğrulaması yaparken en güvenilir görünümdür.

Önerilen hata ayıklama sırası:

1. Önce Ham Veri görünümünü açın.
2. Ajanın gerçekten ne döndürdüğünü doğrulayın.
3. Sonra Önizleme ile yapıyı kontrol edin.
4. En son İçerik görünümünde kullanıcıya gösterilecek çıktıyı kontrol edin.

Eğer Önizleme dolu ama İçerik boşsa, ajan Apidog’un okuyabildiği ancak düz metne çevirmediği bir yapıt tipi döndürüyor olabilir. Ham Veri’de error.message varsa, başlangıç noktanız burasıdır.

Oturum geçmişi sol panelde tutulur. Yeni bir test senaryosuna geçerken eski bağlamın sonucu etkilemesini istemiyorsanız Temizle’ye tıklayın.

Kimlik Doğrulama: Üç Yaygın Desen

Çoğu üretim A2A uç noktası kimlik doğrulama arkasındadır. Apidog’da üç yaygın yaklaşımı kullanabilirsiniz.

Taşıyıcı Token

Barındırılan ajanlarda en yaygın desendir. Kimlik doğrulama panelinde Taşıyıcı Token seçin ve token’ı yapıştırın.

Apidog her isteğe şu başlığı ekler:

Authorization: Bearer sk-agent-7f3e9a...

Temel Kimlik Doğrulama

Kullanıcı adı ve parola ile korunan ajanlar için kullanılır. Dahili veya eski sistemlerde yaygındır.

Temel Kimlik Doğrulama seçeneğini seçin, kullanıcı adı ve parolayı girin. Apidog Authorization: Basic ... başlığını sizin için oluşturur.

Özel Başlık Üzerinden API Anahtarı

Ajan standart olmayan bir başlık bekliyorsa Başlıklar bölümüne manuel ekleyin.

Örnek:

X-Agent-Key: agent-key-123

Aynı yöntem şu başlıklar için de geçerlidir:

• CSRF token’ları
• Kiracı kimlikleri
• İstek imzaları
• Ağ geçidine özel kimlik doğrulama başlıkları

Ajan kimlik bilgisi yönetimi için daha geniş bir rehbere ihtiyacınız varsa, Apidog Yapay Zeka Ajanı Kimlik Bilgileri kılavuzu kapsamlandırma, döndürme ve commit edilmemesi gereken sırlar gibi konuları ele alır.

Özel Başlıklar ve Meta Veriler: Hangisini Ne Zaman Kullanmalı?

A2A isteğinde ek veri göndermek için iki farklı yer vardır. Benzer görünürler, ancak farklı katmanlara giderler.

Kanal	Nerede bulunur	Ne için kullanılır
Özel Başlıklar	HTTP istek başlıkları	Ağ geçidi kimlik doğrulaması, gözlemlenebilirlik, X-Request-Id, özellik bayrakları
Meta Veriler	A2A mesaj yükü	Ajanın okuyacağı mesaj başına bağlam: öncelik, kiracı, yerel ayar

Kural basit:

• Ters proxy, API gateway veya ara katman görmeliyse başlık kullanın.
• Ajanın görev işleyicisi okumalıysa meta veri kullanın.

Bu ayrımı karıştırmak, “ajan gönderdiğim bağlamı neden görmedi?” hatalarının en yaygın nedenlerinden biridir.

Apidog’da A2A Hata Ayıklayıcı ve MCP Sunucu Testi

Apidog hem A2A Hata Ayıklayıcı hem de MCP test akışı sunar. Ancak bunlar farklı protokoller için farklı araçlardır.

Araç	Protokol	Test ettiği şey	Ne zaman kullanılır
A2A Hata Ayıklayıcı	Agent2Agent	Bağlantı, mesaj alışverişi, görev durumu	Ajanların diğer ajanları çağırdığı çoklu ajan sistemlerinde
MCP sunucu testi	Model Bağlam Protokolü	Araç çağrıları, kaynak erişimi, istem şablonları	Bir ajana araçlar veya kaynaklar sunan MCP sunucusu geliştirirken

Kısa karar ağacı:

• Ajanınız başka bir ajanla konuşuyorsa: A2A
• Ajanınız bir araç, API veya kaynağa erişiyorsa: MCP

Detaylı açıklama için MCP ile A2A karşılaştırması kılavuzuna bakabilirsiniz.

MCP tarafında test yapmak istiyorsanız, MCP sunucu test kılavuzu Apidog’daki manuel ve otomatik yolları kapsar. Gerçek dünya ajan sistemlerinde genellikle A2A koordinasyonu ve MCP araç erişimi birlikte kullanılır.

Yaygın Hata Ayıklama Döngüsü

“Ajan beklediğim gibi yanıt vermiyor” durumunda şu kısa döngüyü uygulayın:

1. A2A Hata Ayıklayıcıyı açın.
2. Ajan Kartı URL’si ile bağlanın.
3. Ajan Kartında beklediğiniz becerinin listelendiğini doğrulayın.
4. Beceriyi tetikleyecek en küçük düz metin mesajını gönderin.
5. İlk olarak Ham Veri görünümünü okuyun.
6. Yanıt eksik alan döndürüyorsa ajan kodunu kontrol edin.
7. Yanıt biçimsel olarak doğru ama içerik yanlışsa istem veya model mantığını inceleyin.
8. Düz metin akışı çalıştıktan sonra dosya eki ve meta veri ekleyin.

Bu yaklaşım, API’lerinizi çağıran yapay zeka ajanlarını nasıl test edersiniz yazısındaki izolasyon prensibiyle aynıdır: önce taşıma katmanını doğrulayın, sonra ajan mantığını ayıklayın.

Yapay Zeka İş Akışınızda Nereye Denk Geliyor?

Çoklu ajan sistemleri, modern yapay zeka iş akışlarında giderek daha sık kullanılıyor. Yapay zeka ajanları yeni API tüketicileridir yazısı, ajan trafiğini birinci sınıf API trafiği olarak ele almanın nedenlerini açıklar.

Bunun devamı olarak yapay zeka ajanları için API’ler tasarlama yazısı, tüketici insan geliştirici değil de LLM destekli ajan olduğunda API sözleşmesinde nelerin değiştiğini ele alır.

A2A Hata Ayıklayıcı, Apidog’un MCP İstemci görsel hata ayıklayıcısı ile aynı problem alanına odaklanır: ajan SDK’larının içinde gizli kalan trafiği görünür hale getirmek.

Akış şu hale gelir:

1. Ajanı bağlayın.
2. Ne gönderdiğini görün.
3. Ne aldığını inceleyin.
4. Yanlış alanları üretime çıkmadan düzeltin.

Apidog ücretsiz olarak indirilebilir ve A2A Hata Ayıklayıcı standart istemciyle birlikte gelir.

Sıkça Sorulan Sorular

A2A Hata Ayıklayıcı ücretsiz mi?

Evet. Standart Apidog istemcisiyle birlikte gelir. Apidog’u indirin ve güncel bir sürüm kullanıyorsanız A2A Hata Ayıklayıcı yan panelde görünür.

Herhangi bir çerçevede yazılmış ajanlarla çalışır mı?

Geçerli bir A2A Ajan Kartı sunan herhangi bir ajanla çalışır. Protokol çerçeveden bağımsızdır. LangGraph, CrewAI, AutoGen veya özel Python/Go ajanları, A2A spesifikasyonuna uydukları sürece kullanılabilir.

Oturumları daha sonra oynatmak üzere kaydedebilir miyim?

Oturumlar hata ayıklayıcı açıkken devam eder. Uzun süreli saklama için Ham Veri çıktısını kopyalayıp test yapıtlarınıza ekleyebilirsiniz. Tam oturum dışa aktarımı yol haritasındadır.

Akış yanıtlarını nasıl ele alıyor?

Ajan SSE akışını destekliyorsa, hata ayıklayıcı gelen parçaları okur ve Önizleme ile İçerik görünümlerini gerçek zamanlı günceller. Ham Veri, akış kapandığında birleştirilmiş yanıtı gösterir.

Meta veri alanı ile başlıklar bölümü arasındaki fark nedir?

Başlıklar HTTP katmanındadır; meta veriler A2A mesaj katmanındadır. Başlıklar ağ geçidine ve ters proxy’ye ulaşır. Meta veriler ajanın görev işleyicisine ulaşır.

Apidog, ajanın yanıtlarını kendi sunucularına kaydediyor mu?

Hayır. Apidog yerel bir istemci olarak çalışır. Makineniz ile ajan arasındaki trafik Apidog altyapısından geçmez.

A2A Hata Ayıklayıcıyı farklı bir ağdaki barındırılan ajanı test etmek için kullanabilir miyim?

Evet, ağ yolu açıksa. Hata ayıklayıcı, herhangi bir HTTP istemcisi gibi giden HTTPS istekleri yapar. Ajan VPN arkasındaysa, VPN bağlantısının aktif olması gerekir.

Hataları veya özellik isteklerini nereye bildirebilirim?

Apidog geri bildirim kanalı birincil yoldur. Spesifikasyon seviyesindeki konular için A2A protokol GitHub deposu kullanılmalıdır.

Şimdi Deneyin

Erişebileceğiniz en basit A2A ajanını seçin. Henüz bir ajanınız yoksa, A2A referans uygulamaları yerel olarak çalıştırabileceğiniz örnek bir sunucu içerir.

Minimum test döngüsü:

1. Ajanı yerelde veya erişilebilir bir ortamda çalıştırın.
2. Ajan Kartı URL’sini alın.
3. URL’yi Apidog A2A Hata Ayıklayıcıya yapıştırın.
4. Bağlan’a tıklayın.
5. Basit bir merhaba mesajı gönderin.
6. Önizleme, İçerik ve Ham Veri görünümlerini kontrol edin.

Bu küçük uçtan uca döngü çalıştıktan sonra gerçek istemlere, dosya eklerine, meta verilere ve çoklu ajan iş akışlarına geçebilirsiniz.

Hata ayıklayıcıyı API ve MCP çalışmalarınız için Apidog ile birlikte kullandığınızda, ajan sistemlerinin çalıştığı üç ana yüzey için tek bir arayüz elde edersiniz: HTTP, MCP ve A2A.