Keşif aracı · A2A v1.0

A2A Agent Card keşif URL'lerini kontrol edin

A2A istemcileri, well-known bir URL'den JSON Agent Card alarak bir agent'ı keşfeder. Her iki adlandırma kuralını gerçek bir alan adında test edin ve istemcilerin gerçekte ne aldığını görün.

Aynı temel alan adından her iki aday keşif URL'sini de oluşturur.

Döndürülen JSON'ı alır ve durum kodunu ile içerik türünü bildirir.

Mümkün olduğunda yanıtı Agent Card JSON olarak ayrıştırır.

Arayüzler, skill'ler, sağlayıcı, modlar, yetenekler ve güvenlik meta verileri için hazırlık kontrolleri çalıştırır.

Genel bir agent alan adını kontrol edin

Bir temel alan adı girin. Denetleyici her iki keşif yolunu alır, döndürülen JSON'ı ayrıştırır ve Agent Card hazırlık kontrollerini çalıştırır.

Keşif nasıl çalışır

Tek bir well-known URL, her A2A entegrasyonunu başlatır.

Başka bir agent sizinkini çağırmadan önce, alan adınızdaki well-known bir URI'den (RFC 8615) Agent Card'ı alır, skill'leri ve güvenlik gereksinimlerini değerlendirir, ardından tercih edilen arayüzü çağırır. Agent Card eksikse, güncel değilse veya bir yönlendirmenin arkasında gizliyse, entegrasyon başlamadan başarısız olur.

Bu site kontrol ettiğini kendisi de uygular: AgentCard.net kendi Agent Card her iki yolda da yayınlar ve sağdaki örnek gerçek belgedir.

Canlı Agent Card'ımızı görüntüleyin
agentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

Keşif yolları

İki kural, tek Agent Card.

Tam doğrulayıcıyı aç
A2A v1.0 standardı

/.well-known/agent-card.json

A2A v1.0 spesifikasyonu tarafından kaydedilen well-known URI. Yeni istemciler önce bu yolu alır; application/a2a+json içerik türüyle sunun.

Eski (v1.0 öncesi)

/.well-known/agent.json

Erken A2A uygulamaları ve codelab örneklerinde kullanılır. Dağıtılan birçok istemci hâlâ yalnızca bu yolu kontrol eder, bu nedenle burada aynı Agent Card sunmak güvenli bir geçiş stratejisidir.

Yayınlama modeli

Agent Card keşfini dayanıklı hale getirin.

Keşif başarısızlıkları nadiren sıra dışıdır: bir yönlendirme, önbelleğe alınmış bir hata sayfası veya bir yolun dağıtılıp diğerinin unutulması. Bu yayınlama rutini, her iki kuralın da her zaman aynı güncel Agent Card sunmasını sağlar.

  1. 1

    Standart yolda yayınlayın

    Gözden geçirilmiş Agent Card'ı, A2A hizmetiyle aynı alan adında HTTPS üzerinden /.well-known/agent-card.json adresinde, application/a2a+json içerik türüyle sunun.

  2. 2

    Eski yolu yansıtın

    Eski istemciler hâlâ dolaşımdayken /.well-known/agent.json adresinden aynı belgeyi döndürün — iki yoldaki farklı Agent Card yönlendirmeyi karıştırır.

  3. 3

    Agent Card senkronize tutun

    Uç noktalar, skill'ler, yetenekler veya kimlik doğrulama her değiştiğinde Agent Card güncelleyin, version alanını artırın ve her iki yolu birlikte yeniden dağıtın.

  4. 4

    Her değişiklikten sonra yeniden kontrol edin

    Bu denetleyiciyi dağıtımlardan, DNS değişikliklerinden, ağ geçidi geçişlerinden veya pazar yeri düzenlemelerinden sonra çalıştırın. Başarısızlıklar genellikle yönlendirmelerden, HTML hata sayfalarından veya unutulmuş bir yoldan kaynaklanır.

SSS

Well-known Agent JSON hakkında sıkça sorulan sorular

Ne yayınlanmalı, nerede yayınlanmalı ve her iki kuralın istemcilerini çalışır durumda nasıl tutulur.

Hangi well-known Agent Card yolunu kullanmalıyım?

A2A v1.0, /.well-known/agent-card.json'ı standart keşif yolu olarak kaydeder. Eski /.well-known/agent.json v1.0'dan öncedir ancak hâlâ dağıtılan birçok istemci tarafından kontrol edilir, bu nedenle geçiş sırasında aynı Agent Card her iki yolda da yayınlamak pragmatik bir seçimdir.

Her iki yol da aynı JSON'ı döndürmeli mi?

Evet. Her iki yoldan aynı genel Agent Card'ı döndürmek, yalnızca bir kuralı destekleyen istemcileri tutarlı tutar. Farklı belgeler, istemcinin hangi yolu aldığına bağlı olarak agent'ın farklı görünmesine neden olur.

Agent Card hangi içerik türüyle sunulmalı?

Spesifikasyon, Agent Card'lar için application/a2a+json'ı kaydeder. Sade application/json pratikte yaygın olarak kabul edilir, ancak HTML içerik türü, yolun Agent Card yerine bir hata sayfası döndürdüğüne dair güvenilir bir işarettir.

Genel Agent Card özel yetenekleri gizleyebilir mi?

Evet. Genel Agent Card yalnızca keşif için güvenli meta verileri yayınlayın, capabilities.extendedAgentCard'ı true olarak ayarlayın ve hassas skill'leri kimliği doğrulanmış GetExtendedAgentCard işlemi aracılığıyla açığa çıkarın.

Bir dağıtımdan sonra keşif kontrolleri neden başarısız olur?

Yaygın nedenler; bir giriş veya pazarlama sayfasına yönlendirmeler, 200 durumuyla döndürülen HTML 404 sayfaları, bir CDN'de önbelleğe alınmış eski JSON veya iki well-known yolundan yalnızca birinin dağıtılmasıdır. Denetleyici her yol için durum kodunu ve içerik türünü bildirir, böylece başarısızlık hemen görünür hale gelir.

Yayınlamadan önce

Önce Agent Card doğrulayın, sonra URL'leri kontrol edin.

Önce JSON'ı tam doğrulayıcıdan geçirin, her iki well-known yolda da yayınlayın ve bu denetleyiciyle keşfi doğrulayın.

Doğrulayıcıyı açAgent Card oluştur