Validator A2A Agent Card

Validator Agent Card memeriksa JSON yang ditempelkan, file Agent Card yang diunggah, dan URL agent publik terhadap persyaratan penemuan A2A v1.0.

Gunakan Validator Agent Card

Tempelkan JSON, URL agen publik, atau seret file JSON ke editor.

Cakupan Validator Agent Card

Apa yang diperiksa Validator Agent Card sebelum klien menemukan agent Anda.

Validator Agent Card dirancang untuk pengembang yang menerbitkan agent A2A, tim platform internal yang meninjau metadata agent, dan operator marketplace yang memeriksa apakah Agent Card yang dikirimkan berisi cukup informasi untuk pemanggilan yang andal.

Tempelkan dokumen JSON lokal selama pengembangan, unggah Agent Card dari repositori Anda, atau gunakan validasi URL langsung terhadap domain yang di-deploy untuk memverifikasi jalur penemuan publik.

Kesesuaian skema (A2A v1.0)

Memeriksa field wajib terhadap spesifikasi v1.0: name, description, version, supportedInterfaces dengan protocolBinding dan protocolVersion per interface, capabilities, mode konten, dan setidaknya satu skill dengan tag wajib.

Masalah semantik dan migrasi

Mendeteksi struktur pra-v1.0 — url tingkat atas, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — dan memberi tahu Anda persis ke mana setiap field berpindah di v1.0.

Keamanan dan pemindaian rahasia

Memverifikasi bahwa securitySchemes dan persyaratan keamanan dideklarasikan untuk endpoint non-publik, menandai URL non-HTTPS, dan memindai nilai yang terlihat seperti kunci API, JWT, atau token bearer yang tertanam.

Kesiapan penemuan

Mengambil /.well-known/agent-card.json dan /.well-known/agent.json lama dari domain langsung dan mengonfirmasi bahwa keduanya mengembalikan JSON Agent Card yang dapat diurai.

Di mana validasi berperan

Validasi di setiap tahap: editor, pipeline CI, domain langsung.

Agent Card yang lolos peninjauan bulan lalu masih bisa merusak penemuan hari ini — endpoint berpindah, skill berubah, deployment ulang menghilangkan rute well-known. Tim platform dan peninjau marketplace memperlakukan validasi sebagai gerbang yang dapat diulang, bukan pemeriksaan satu kali.

Penjaga CI paling sederhana tidak memerlukan apa pun selain curl: konfirmasikan bahwa jalur well-known merespons dengan JSON yang dapat diurai sebelum lalu lintas beralih ke deployment baru.

# 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 perbaikan

Perbaikan Agent Card yang umum

Gunakan laporan Validator Agent Card untuk mengatasi field wajib terlebih dahulu, lalu tingkatkan detail penemuan, kepercayaan, dan migrasi.

Ganti URL endpoint placeholder dengan URL layanan A2A HTTPS yang di-deploy.

Pindahkan url dan preferredTransport tingkat atas ke dalam array supportedInterfaces yang berurutan — entri pertama adalah interface pilihan.

Tambahkan field version tingkat atas wajib yang mendeskripsikan agent itu sendiri, dan tambahkan tag ke setiap skill.

Ganti nama provider.name menjadi provider.organization dan perluas deskripsi singkat sehingga klien tahu kapan harus memanggil agent.

Deklarasikan metadata keamanan setiap kali endpoint agent tidak sepenuhnya publik — dan jangan pernah menyematkan kredensial itu sendiri.

Terbitkan Agent Card valid yang sama di /.well-known/agent-card.json (dan di jalur agent.json lama selama klien masih memeriksa keduanya).

Pertanyaan umum

Pertanyaan tentang Validator Agent Card

Pastikan hal-hal esensial benar sebelum agent Anda mencapai klien A2A.

Bandingkan contoh yang valid

Versi A2A mana yang ditargetkan validator?

Pemeriksaan mengikuti struktur Agent Card A2A v1.0 — supportedInterfaces, versi protokol per interface, tag skill wajib, provider.organization. Agent Card pra-v1.0 tidak langsung ditolak: field lama muncul sebagai peringatan dengan pengganti v1.0 yang tepat.

Mengapa memeriksa kedua URL well-known?

Spesifikasi v1.0 mendaftarkan /.well-known/agent-card.json, tetapi implementasi A2A sebelumnya menggunakan /.well-known/agent.json. Memeriksa keduanya menangkap celah penemuan sebelum klien gagal.

Bisakah peringatan diabaikan?

Peringatan tidak memblokir seperti kesalahan JSON, tetapi biasanya menunjuk ke metadata yang membuat agent lebih mudah ditemukan, dipercaya, dan dipanggil — atau ke field pra-v1.0 yang akan berhenti dibaca oleh klien yang lebih baru.

Kapan validasi harus dijalankan?

Tiga momen: saat mengedit Agent Card selama pengembangan, sebagai gerbang CI sebelum deployment, dan setelah penerbitan — tempelkan URL layanan langsung untuk mengonfirmasi apa yang sebenarnya diterima klien dari kedua jalur penemuan.

Siap memvalidasi

Validasi Agent Card Anda sebelum klien menemukannya.

Tempelkan JSON, jatuhkan file Agent Card, atau periksa URL publik dari ruang kerja validator terpadu.

Buka Validator Agent Card Hasilkan Agent Card