Diğer yapay zeka ajanlarıyla konuşan yapay zeka ajanları geliştiriyorsanız, siz de herkesin karşılaştığı aynı duvara çarpmışsınızdır: bir ajanın diğerine ne gönderdiğini incelemenin temiz bir yolu yoktur. Konsol günlükleri yanıltır, ağ sekmeleri yapılandırılmış alanları gizler ve özel test senaryoları hızla bozulur. Apidog'un A2A Hata Ayıklayıcısı, Agent2Agent (A2A) protokolü için bunu düzeltir. Bir Ajan Kartı URL'sini yapıştırın, Bağlan'a tıklayın, bir mesaj gönderin ve yanıtı üç görünümde okuyun.
Bu kılavuz, A2A Hata Ayıklayıcının ne işe yaradığını, ilk ajanınızı nasıl bağlayacağınızı, istek ve yanıtın arka planda nasıl göründüğünü ve Apidog'un mevcut MCP sunucu test araçlarının yanında nerede konumlandığını anlatmaktadır. Önceki protokol bağlamına ihtiyacınız varsa, Apidog'da MCP ile A2A karşılaştırmasına dair daha derin bir okuma bu yazı ile iyi eşleşmektedir.
A2A Nedir (tek paragrafta)
Agent2Agent'ın kısaltması olan A2A, ajanlar arası iletişim için açık bir protokoldür. Bir ajanın yeteneklerini nasıl duyurduğunu (Ajan Kartı), 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 rapor edildiğini tanımlar. Bunu ajanlar arası trafik için HTTP gibi düşünün: veri hattınızdaki bir LangGraph ajanın, başka bir ekibe ait bir CrewAI ajana, iki tarafın da birbirinin dahili yapısını bilmesine gerek kalmadan ping atmasını sağlayan ince, satıcıdan bağımsız bir spesifikasyon.
Tek bir ajana araçlara ve kaynaklara erişim sağlamakla ilgili olan MCP'den (Model Bağlam Protokolü) farklıdır. A2A, ajanların diğer ajanlarla konuşmasıyla ilgilidir. MCP ile A2A arasındaki farkın açıklaması bu farkı en net şekilde okumanızı sağlar.
A2A Hata Ayıklayıcının Size Sundukları
A2A Hata Ayıklayıcı, Apidog içinde yer alır. A2A uç noktalarını bir üretim iş akışına bağlamadan önce test etmek için görsel bir çalışma tezgahıdır. Temel özellikler:
- Ajan Kartı bağlantısı. Bir URL yapıştırın, Bağlan'a tıklayın, ajanın adını, açıklamasını, yeteneklerini, beyan edilen becerilerini ve protokol sürümünü görün. Kart hatalı biçimlendirilmişse, bağlantı yüksek sesle başarısız olur, böylece hayalet kovalamak yerine manifestoyu düzeltebilirsiniz.
- Mesaj gönderme. Düz metin oluşturun, dosya ekleyin (ajanın beyan edilen giriş türleri desteklediğinde) ve özel meta veri anahtar-değer çiftlerini ekleyin.
- Üç yanıt görünümü. Önizleme, yapılandırılmış çıktıyı işler, İçerik insan tarafından okunabilir yükü gösterir ve Ham Veri, alan adlarını veya kaçış karakterlerini doğrulamanız gerektiğinde tüm JSON'u döker.
- Kimlik doğrulama. Taşıyıcı Token, Temel Kimlik Doğrulama ve özel başlıklar aracılığıyla API Anahtarı, hepsi kullanıcı arayüzünde.
- Özel başlıklar. Ağ geçidi kimlik doğrulaması, iş parametreleri veya A2A uç noktanızın beklediği herhangi bir ara yazılımı ekleyin.
- Oturum geçmişi. Gönderdiğiniz her mesaj bir oturum günlüğünde kalır. Yeni bir teste başladığınızda ve eski bağlamın ajanı karıştırmasını istemediğinizde bunu temizleyin.
Sıfır curl komutu yazarsınız. Apidog, JSON-RPC zarfını, SSE akışını (ajanın desteklediği durumlarda) ve yanıt ayrıştırmayı halleder.
Adım 1: İlk A2A Ajana Bağlanma
Hata ayıklayıcıyı açmadan önce üç şeye ihtiyacınız var:
- Apidog yüklü ve güncel. En son istemci gereklidir; eski sürümler A2A Hata Ayıklayıcıyı içermez. Henüz yoksa Apidog'u indirin.
- Bir Ajan Kartı URL'si. Bu, A2A uyumlu herhangi bir ajanın temel giriş noktasıdır. Yerel geliştirme için genellikle
http://localhost:3000/.well-known/agent.jsongibi görünür; barındırılan ajanlar için, platform sağlayıcınız size yolu verecektir. - Kimlik bilgileri (ajan gerektiriyorsa). Taşıyıcı token, API anahtarı veya temel kimlik doğrulama.
Apidog'u açın, A2A Hata Ayıklayıcı sayfasına gidin ve Ajan Kartı URL'sini en üste yapıştırın. Bağlan'a tıklayın. Ajan geçerli bir Ajan Kartı ile yanıt verirse, durum Bağlandı olarak değişir ve panel ajanın meta verileriyle (ad, açıklama, yetenekler, beyan edilen beceriler, protokol sürümü) dolar.
Başarısız olursa, en yaygın nedenler şunlardır:
- URL yanlış veya ajan çalışmıyor. Bir JSON yükünün geri geldiğini doğrulamak için URL'yi bir tarayıcıda açın.
- Ajan Kartında gerekli alanlar eksik. GitHub'daki A2A protokol spesifikasyonu ile karşılaştırın.
- Ajan, keşif uç noktasında kimlik doğrulama bekliyor. Bağlan'a tıklamadan önce kimlik doğrulamayı Apidog'a ekleyin.
Adım 2: Bir Test Mesajı Gönderme
Bağlandıktan sonra Mesajlar sekmesini açın. Herhangi bir sohbet arayüzünde olduğu gibi bir istem yazın. Örneğin:
Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.
Gönder'e tıklamadan önceki isteğe bağlı eklemeler:
- Dosya eki. Ataç simgesine tıklayın ve bir dosya seçin. Hata ayıklayıcı, ajanın beyan edilen giriş türlerini kontrol eder ve desteklenmeyen dosya türlerini peşinen reddeder, böylece bir 415 hatası için gidiş-dönüş harcamazsınız.
- Özel meta veriler.
priority: highveyatenant: acme-corpgibi anahtar-değer çiftleri ekleyin. Bunlar A2A istek zarfına akar ve işleyicisi okuduğu takdirde ajan tarafından görülebilir.
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 Okuma
A2A yanıtları düz dizeler, yapılandırılmış JSON, dosya referansları veya bunların bir karışımı olabilir. Hata ayıklayıcı, aynı yük üzerinde size üç farklı bakış açısı sunar:
- Önizleme. Apidog, yapılandırılmış alanları bir ağaç olarak işler. Ajanın iç içe geçmiş nesneler (görev kimliği, durum, yapıtlar, geçmiş) döndürdüğü durumlarda kullanışlıdır.
- İçerik. İnsan tarafından okunabilir gövde. Ajan metin döndürdüyse, kullanıcılara göstereceğiniz şey budur.
text/plainbölümü olan yapılandırılmış bir yapıt döndürdüyse, bu çıkarılan metindir. - Ham Veri. Tüm JSON-RPC yükü. Bir şeyler yanlış gittiğinde bir hata raporuna kopyalanacak ve uyumluluğu doğrularken spesifikasyonla karşılaştırılacak olan budur.
Üçü arasında geçiş yapın. Önizleme iyi görünüyorsa ancak İçerik boşsa, ajan muhtemelen Apidog'un işleyebildiği ancak nasıl düzleştireceğini bilmediği tipte bir yapıt döndürüyor demektir. Ham Veri bir hata kodu gösteriyorsa, ajan isteği reddetmiştir ve error.message içindeki mesaj başlangıç noktanızdır.
Oturum geçmişi sol panelde bulunur. Her gönderim, geri dönebileceğiniz bir dönüş haline gelir. Yeni bir teste başladığınızda ve eski bağlamın ajanı karıştırmasını istemediğinizde Temizle'ye tıklayın.
Kimlik Doğrulama: Üç Yaygın Desen
Çoğu üretim A2A uç noktası bir tür kimlik doğrulamasının arkasında bulunur. Hata ayıklayıcı başlangıçta üç deseni ele alır:
Taşıyıcı Token
Barındırılan ajanlar için en yaygın desen. Kimlik doğrulama panelinde **Taşıyıcı Token**'ı seçin ve token'ı yapıştırın. Apidog her isteğe Authorization: Bearer <token> ekler.
Authorization: Bearer sk-agent-7f3e9a...
Temel Kimlik Doğrulama
Bir kullanıcı adı ve parola ile korunan ajanlar için (dahili/eski sistemlerde yaygındır). **Temel Kimlik Doğrulama**'yı seçin, her iki değeri de girin ve Apidog, base64 ile kodlanmış Authorization: Basic ... başlığını hesaplar.
Özel Başlık Aracılığıyla API Anahtarı
Ajan X-Agent-Key gibi standart olmayan bir başlık adı beklediğinde, **Başlıklar** bölümüne gidin ve manuel olarak ekleyin. Herhangi bir ağ geçidine özel başlık (CSRF token'ları, kiracı kimlikleri, istek imzaları) için aynı akış geçerlidir.
Ajan kimlik bilgisi hijyeni üzerine uzun vadeli düşünceler için, Apidog Yapay Zeka Ajanı Kimlik Bilgileri kılavuzu nelerin döndürüleceğini, nelerin kapsamlandırılacağını ve nelerin asla taahhüt edilmeyeceğini kapsar.
Özel başlıklar ve meta veriler: hangisini ne zaman kullanmalı
Bir A2A isteğinde "ekstra" veriyi tutan iki yer vardır. Benzer ses çıkarırlar 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 okuduğu mesaj başına bağlam (öncelik, kiracı, yerel ayar) |
Genel kural: ters proxy'niz veya API ağ geçidinizin görmesi gerekiyorsa, başlıkları kullanın. Ajanın görev işleyicisinin buna ihtiyacı varsa, meta verileri kullanın. Bunları karıştırmak, "ajan neden ipucumu görmezden geldi" hatalarının bir numaralı kaynağıdır.
Apidog'da A2A Hata Ayıklayıcı ve MCP sunucu testi karşılaştırması
Apidog hem bir A2A Hata Ayıklayıcısı hem de bir MCP test akışı sunar. Bunlar farklı protokoller için farklı araçlardır:
| Araç | Protokol | Testler | 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 sistemleri oluştururken |
| MCP sunucu testi | Model Bağlam Protokolü | Araç çağrıları, kaynak erişimi, istem şablonları | Bir ajana araçlar/kaynaklar sunan bir MCP sunucusu oluştururken |
Hangisine ihtiyacınız olduğundan emin değilseniz, MCP ile A2A karşılaştırması kılavuzu kararı açıklıyor. Kısa versiyonu: MCP, bir ajanın harici sistemlere ulaşmak için kullandığı şeydir. A2A ise bir ajanın başka bir ajanla konuşmak için kullandığı şeydir.
İş akışının MCP tarafı için, MCP sunucu test kılavuzu Apidog'daki manuel ve otomatik yolları kapsar. Birçok ekip, gerçek dünya ajan sistemleri A2A koordinasyonunu MCP araç erişimiyle birleştirdiği için her iki yüzeyi de kullanır.
Yaygın bir hata ayıklama deseni: bir görevi gidiş-dönüş test etme
"Ajan beklediğim gibi yanıt vermiyor" durumunda takıldığınızda, bu döngüyü izleyin:
- A2A Hata Ayıklayıcıyı açın.
- Ajana bağlanın. Ajan Kartının beklediğiniz beceriyi gösterdiğini doğrulayın.
- Bu beceriyi tetiklemesi gereken mümkün olan en küçük mesajı gönderin. Önce düz metin kullanın; dosyaları ve meta verileri ancak metin yolu çalıştığında ekleyin.
- İlk seferde Önizleme'yi değil, Ham Veri'yi okuyun. Ajanın tam olarak ne yaydığını görmek istersiniz.
- Yanıt beklediğiniz bir alanı eksikse, bu taşıma değil, ajan kodundaki bir sorundur.
- Yanıt iyi biçimlendirilmiş ancak yanlışsa, bu bir istem veya model sorunudur ve zaten taşımayı mantıktan izole etmişsinizdir.
Bu, API'lerinizi çağıran yapay zeka ajanlarını nasıl test edersiniz yazısının API tarafına uyguladığı, suçlamadan önce izolasyon döngüsüdür. Aynı prensip: önce bağlantıyı doğrulayın, sonra beyni ayıklayın.
Yapay Zeka İş Akışınızda Nereye Denk Geliyor
Çoklu ajan sistemleri, 2026'da birçok ciddi yapay zeka çalışmasının nasıl hayata geçirildiğidir. Yapay zeka ajanları yeni API tüketicileridir yazısı, ajan trafiğini birinci sınıf olarak ele almanın nedenlerini ortaya koymaktadır. Yapay zeka ajanları için API'ler tasarlama takip yazısı, tüketici bir insan geliştirici yerine LLM destekli bir ajan olduğunda API sözleşmenizde nelerin değiştiğini kapsar.
A2A Hata Ayıklayıcı, Apidog'un MCP İstemci görsel hata ayıklayıcısı ile aynı katmanda yer alır. Her ikisi de, ajan SDK'larının içinde gizli kalan trafiğe bir pencere açmakla ilgilidir. Ajanınızı bağlarsınız, ne yaptığını görebilirsiniz, ve hataları üretime ulaşmadan düzeltirsiniz.
Apidog ücretsiz olarak indirilebilir ve A2A Hata Ayıklayıcı standart istemci ile birlikte gelir; ayrı bir lisans veya ayrı bir plan gerekmez.
Sıkça Sorulan Sorular
A2A Hata Ayıklayıcı ücretsiz mi?
Evet. Standart Apidog istemcisiyle birlikte gelir. Apidog'u indirin ve yeterince güncel bir sürümde olduğunuzda 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, bu nedenle LangGraph, CrewAI, AutoGen ve özel Python veya Go ajanları, A2A spesifikasyonuna uydukları sürece hepsi çalışır.
Oturumları daha sonra oynatmak üzere kaydedebilir miyim?
Oturumlar, hata ayıklayıcı açıkken devam eder. Uzun süreli depolama için, Ham Veri çıktısını kopyalayın ve test yapıtlarınıza kaydedin; tam oturum dışa aktarımı yol haritasındadır.
Akış yanıtlarını nasıl ele alıyor?
Ajan SSE akışını desteklediğinde (A2A spesifikasyonuna göre), hata ayıklayıcı gelen parçaları okur ve Önizleme ile İçeriği gerçek zamanlı olarak 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ıdır; meta veriler A2A mesaj katmanıdır. Başlıklar ağ geçidine ve ters proxy'ye ulaşır; meta veriler ajanın görev işleyicisine ulaşır. Bu yazının önceki bölümündeki tabloya bakın.
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 bir 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ınız bir VPN'in arkasındaysa, o VPN'in aktif olması gerekir.
Hataları veya özellik isteklerini nereye bildirebilirim?
Apidog geri bildirim kanalı birincil yoldur; A2A protokol GitHub deposu yukarı akış spesifikasyonunun geliştiği yerdir, bu nedenle spesifikasyon seviyesindeki istekler oraya aittir.
Şimdi Deneyin
Erişebileceğiniz en basit A2A ajanını seçin. Henüz bir tane yoksa, A2A referans uygulamaları beş dakikadan kısa sürede yerel olarak çalıştırabileceğiniz örnek bir sunucu içerir. Ajan Kartı URL'sini Apidog'un A2A Hata Ayıklayıcısına yapıştırın, bir "merhaba" mesajı gönderin ve üç yanıt görünümünün dolduğunu izleyin. Bu en küçük uçtan uca döngüdür ve buradan gerçek istemlere, dosya eklerine ve çoklu ajan iş akışlarına ölçeklendirme yapabilirsiniz.
Hata ayıklayıcıyı API ve MCP çalışmalarınızın geri kalanı için Apidog ile eşleştirin, ve ajan sistemlerinin çalıştığı üç protokol (HTTP, MCP ve A2A) için tek bir arayüze sahip olursunuz.
button