Pengesah A2A Agent Card

Pengesah Agent Card menyemak JSON yang ditampal, fail Agent Card yang dimuat naik, dan URL agen awam berbanding keperluan penemuan A2A v1.0.

Gunakan Pengesah Agent Card

Tampalkan JSON, URL ejen awam atau seret fail JSON ke dalam editor.

Liputan Pengesah Agent Card

Apa yang disemak Pengesah Agent Card sebelum klien menemui agen anda.

Pengesah Agent Card direka untuk pembangun yang menerbitkan agen A2A, pasukan platform dalaman yang menyemak metadata agen, dan pengendali pasaran yang menyemak sama ada Agent Card yang dihantar mengandungi maklumat yang mencukupi untuk panggilan yang boleh dipercayai.

Tampal dokumen JSON tempatan semasa pembangunan, muat naik Agent Card dari repositori anda, atau gunakan pengesahan URL langsung berbanding domain yang digunakan untuk mengesahkan laluan penemuan awam.

Pematuhan skema (A2A v1.0)

Menyemak medan wajib berbanding spesifikasi v1.0: name, description, version, supportedInterfaces dengan protocolBinding dan protocolVersion bagi setiap antara muka, capabilities, mod kandungan, dan sekurang-kurangnya satu skill dengan tag wajib.

Isu semantik dan migrasi

Mengesan struktur pra-v1.0 — url peringkat atas, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — dan memberitahu anda dengan tepat di mana setiap medan berpindah dalam v1.0.

Imbasan keselamatan dan rahsia

Mengesahkan bahawa securitySchemes dan keperluan keselamatan diisytiharkan untuk titik akhir bukan awam, menanda URL bukan HTTPS, dan mengimbas nilai yang kelihatan seperti kunci API, JWT, atau token bearer yang tertanam.

Kesediaan penemuan

Mengambil /.well-known/agent-card.json dan /.well-known/agent.json lama daripada domain sebenar dan mengesahkan bahawa kedua-duanya mengembalikan JSON Agent Card yang boleh dihuraikan.

Di mana pengesahan sesuai

Sahkan pada setiap peringkat: editor, saluran paip CI, domain sebenar.

Agent Card yang lulus semakan bulan lepas masih boleh merosakkan penemuan hari ini — titik akhir berpindah, skill berubah, penggunaan semula menjatuhkan laluan well-known. Pasukan platform dan penyemak pasaran menganggap pengesahan sebagai get yang boleh diulang, bukan semakan sekali sahaja.

Perlindungan CI paling mudah hanya memerlukan curl: sahkan bahawa laluan well-known bertindak balas dengan JSON yang boleh dihuraikan sebelum trafik beralih kepada penggunaan baharu.

# 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"])'

Panduan pembaikan

Pembaikan Agent Card yang biasa

Gunakan laporan Pengesah Agent Card untuk menangani medan wajib dahulu, kemudian tingkatkan butiran penemuan, kepercayaan, dan migrasi.

Gantikan URL titik akhir ruang letak dengan URL perkhidmatan A2A HTTPS yang digunakan.

Alihkan url dan preferredTransport peringkat atas ke dalam array supportedInterfaces yang tersusun — entri pertama ialah antara muka pilihan.

Tambah medan version peringkat atas wajib yang menerangkan agen itu sendiri, dan tambah tag pada setiap skill.

Namakan semula provider.name kepada provider.organization dan kembangkan penerangan pendek supaya klien tahu bila hendak memanggil agen.

Isytiharkan metadata keselamatan apabila titik akhir agen tidak sepenuhnya awam — dan jangan sesekali tanamkan kelayakan itu sendiri.

Terbitkan Agent Card sah yang sama di /.well-known/agent-card.json (dan di laluan agent.json lama sementara klien masih menyemak kedua-duanya).

Soalan lazim

Soalan tentang Pengesah Agent Card

Betulkan perkara asas sebelum agen anda sampai ke klien A2A.

Bandingkan contoh yang sah

Versi A2A manakah yang disasarkan pengesah?

Semakan mengikut struktur Agent Card A2A v1.0 — supportedInterfaces, versi protokol bagi setiap antara muka, tag skill wajib, provider.organization. Agent Card pra-v1.0 tidak ditolak terus: medan lama muncul sebagai amaran dengan penggantian v1.0 yang tepat.

Mengapa ia menyemak kedua-dua URL well-known?

Spesifikasi v1.0 mendaftarkan /.well-known/agent-card.json, tetapi pelaksanaan A2A terdahulu menggunakan /.well-known/agent.json. Menyemak kedua-duanya menangkap jurang penemuan sebelum klien gagal.

Bolehkah amaran diabaikan?

Amaran tidak menyekat seperti ralat JSON, tetapi biasanya menunjukkan metadata yang menjadikan agen lebih mudah ditemui, dipercayai, dan dipanggil — atau medan pra-v1.0 yang akan berhenti dibaca oleh klien yang lebih baharu.

Bilakah pengesahan patut dijalankan?

Tiga saat: semasa menyunting Agent Card sepanjang pembangunan, sebagai get CI sebelum penggunaan, dan selepas penerbitan — tampal URL perkhidmatan sebenar untuk mengesahkan apa yang klien benar-benar terima daripada kedua-dua laluan penemuan.

Sedia untuk mengesahkan

Sahkan Agent Card anda sebelum klien menemuinya.

Tampal JSON, lepaskan fail Agent Card, atau semak URL awam daripada ruang kerja pengesah bersatu.

Buka Pengesah Agent Card Jana Agent Card