Agent Card Doğrulayıcı, yapıştırılan JSON'ı, yüklenen Agent Card dosyalarını ve genel agent URL'lerini A2A v1.0 keşif gereksinimlerine göre kontrol eder.
JSON'u, bir genel aracı URL'sini yapıştırın veya bir JSON dosyasını düzenleyiciye sürükleyin.
Agent Card Doğrulayıcı kapsamı
Agent Card Doğrulayıcı, A2A agent'ları yayınlayan geliştiriciler, agent meta verilerini inceleyen dahili platform ekipleri, ve gönderilen bir Agent Card güvenilir bir çağrı için yeterli bilgi içerip içermediğini kontrol eden pazar yeri operatörleri için tasarlanmıştır.
Geliştirme sırasında yerel bir JSON belgesi yapıştırın, deponuzdan bir Agent Card yükleyin, veya genel keşif yollarını doğrulamak için dağıtılmış bir alan adına karşı canlı URL doğrulaması kullanın.
Zorunlu alanları v1.0 spesifikasyonuna göre kontrol eder: name, description, version, arayüz başına protocolBinding ve protocolVersion içeren supportedInterfaces, capabilities, içerik modları, ve zorunlu etiketlere sahip en az bir skill.
v1.0 öncesi yapıları — üst düzey url, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — tespit eder ve her alanın v1.0'da tam olarak nereye taşındığını size söyler.
securitySchemes ve güvenlik gereksinimlerinin herkese açık olmayan uç noktalar için beyan edildiğini doğrular, HTTPS olmayan URL'leri işaretler, ve gömülü API anahtarları, JWT'ler, veya bearer token'lar gibi görünen değerleri tarar.
Canlı bir alan adından /.well-known/agent-card.json ve eski /.well-known/agent.json'ı alır ve her ikisinin de ayrıştırılabilir Agent Card JSON döndürdüğünü doğrular.
Doğrulama nereye uyar
Geçen ay incelemeyi geçen bir Agent Card bugün hâlâ keşfi bozabilir — bir uç nokta değişir, bir skill değişir, yeniden dağıtım well-known rotayı düşürür. Platform ekipleri ve pazar yeri denetçileri doğrulamayı tek seferlik bir kontrol değil, tekrarlanabilir bir kapı olarak ele alır.
En basit CI koruması yalnızca curl gerektirir: trafik yeni bir dağıtıma geçmeden önce well-known yolunun ayrıştırılabilir JSON ile yanıt verdiğini onaylayın.
# deploy pipeline: fail if the published card breaks
curl -fsS https://your-domain/.well-known/agent-card.json \
| python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'Düzeltme kılavuzu
Önce zorunlu alanları ele almak için Agent Card Doğrulayıcı raporunu kullanın, ardından keşif, güven, ve geçiş ayrıntılarını iyileştirin.
Yer tutucu uç nokta URL'lerini dağıtılan HTTPS A2A hizmet URL'si ile değiştirin.
Üst düzey url ve preferredTransport'u sıralı bir supportedInterfaces dizisine taşıyın — ilk giriş tercih edilen arayüzdür.
Agent'ın kendisini açıklayan gerekli üst düzey version alanını ekleyin ve her skill'e etiket ekleyin.
provider.name'i provider.organization olarak yeniden adlandırın ve istemcilerin agent'ı ne zaman çağıracağını bilmesi için kısa açıklamaları genişletin.
Agent uç noktası tamamen genel olmadığında güvenlik meta verilerini beyan edin — ve kimlik bilgisini asla gömmeyin.
Aynı geçerli Agent Card'ı /.well-known/agent-card.json'da yayınlayın (ve istemciler hâlâ her ikisini de kontrol ederken eski agent.json yolunda da).
SSS
Agent'ınız bir A2A istemcisine ulaşmadan önce temel unsurları doğru yapın.
Geçerli örnekleri karşılaştırKontroller A2A v1.0 Agent Card yapısını izler — supportedInterfaces, arayüz başına protokol sürümleri, zorunlu skill etiketleri, provider.organization. v1.0 öncesi Agent Card doğrudan reddedilmez: eski alanlar tam v1.0 değişimiyle birlikte uyarı olarak görünür.
v1.0 spesifikasyonu /.well-known/agent-card.json'ı kaydeder, ancak önceki A2A uygulamaları /.well-known/agent.json kullanıyordu. Her ikisini de kontrol etmek, istemciler başarısız olmadan önce keşif boşluklarını yakalar.
Uyarılar JSON hataları gibi engellemez, ancak genellikle agent'ı keşfetmeyi, güvenmeyi, ve çağırmayı kolaylaştıran meta verilere — veya daha yeni istemcilerin artık okumayacağı v1.0 öncesi alanlara — işaret eder.
Üç an: geliştirme sırasında bir Agent Card düzenlerken, dağıtımdan önce bir CI kapısı olarak, ve yayınlandıktan sonra — istemcilerin her iki keşif yolundan gerçekte ne aldığını doğrulamak için canlı hizmet URL'sini yapıştırın.
Doğrulamaya hazır
Birleşik doğrulayıcı çalışma alanından JSON yapıştırın, bir Agent Card dosyası bırakın, veya genel bir URL'yi kontrol edin.