Alat penemuan · A2A v1.0

Periksa URL penemuan A2A Agent Card

Klien A2A menemukan agent dengan mengambil Agent Card JSON dari URL well-known. Uji kedua konvensi penamaan pada domain langsung dan lihat persis apa yang diterima klien.

Membangun kedua kandidat URL penemuan dari domain dasar yang sama.

Mengambil JSON yang dikembalikan dan melaporkan kode status serta tipe konten.

Mengurai respons sebagai JSON Agent Card bila memungkinkan.

Menjalankan pemeriksaan kesiapan untuk interface, skill, provider, mode, kapabilitas, dan metadata keamanan.

Periksa domain agent publik

Masukkan domain dasar. Pemeriksa mengambil kedua jalur penemuan, mengurai JSON yang dikembalikan, dan menjalankan pemeriksaan kesiapan Agent Card.

Cara kerja penemuan

Satu URL well-known memulai setiap integrasi A2A.

Sebelum agent lain dapat memanggil layanan Anda, ia mengambil Agent Card dari URI well-known (RFC 8615) di domain Anda, mengevaluasi skill dan persyaratan keamanan, lalu memanggil interface pilihan. Jika Agent Card hilang, kedaluwarsa, atau tersembunyi di balik pengalihan, integrasi gagal sebelum dimulai.

Situs ini mempraktikkan apa yang diperiksanya: AgentCard.net menerbitkan Agent Card sendiri di kedua jalur, dan contoh di sebelah kanan adalah dokumen sebenarnya.

Lihat Agent Card langsung kami
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", ... }
  ]
}

Jalur penemuan

Dua konvensi, satu Agent Card.

Buka validator lengkap
Standar A2A v1.0

/.well-known/agent-card.json

URI well-known yang terdaftar oleh spesifikasi A2A v1.0. Klien baru mengambil jalur ini terlebih dahulu; sajikan dengan tipe konten application/a2a+json.

Lama (pra-v1.0)

/.well-known/agent.json

Digunakan oleh implementasi A2A awal dan contoh codelab. Banyak klien yang telah di-deploy masih hanya memeriksa jalur ini, jadi menyajikan Agent Card yang sama di sini adalah strategi transisi yang aman.

Pola penerbitan

Buat penemuan Agent Card lebih tangguh.

Kegagalan penemuan jarang rumit: pengalihan, halaman error yang di-cache, atau satu jalur di-deploy sementara yang lain terlupakan. Rutinitas penerbitan ini menjaga kedua konvensi tetap menyajikan Agent Card terbaru yang sama.

  1. 1

    Terbitkan di jalur standar

    Sajikan Agent Card yang telah ditinjau di /.well-known/agent-card.json melalui HTTPS pada domain yang sama dengan layanan A2A, dengan tipe konten application/a2a+json.

  2. 2

    Cerminkan jalur lama

    Kembalikan dokumen yang identik dari /.well-known/agent.json selama klien lama masih beredar — Agent Card yang berbeda di kedua jalur membingungkan perutean.

  3. 3

    Jaga Agent Card tetap sinkron

    Kapan pun endpoint, skill, kapabilitas, atau autentikasi berubah, perbarui Agent Card, naikkan bidang version-nya, dan deploy ulang kedua jalur bersamaan.

  4. 4

    Periksa ulang setelah setiap perubahan

    Jalankan pemeriksa ini setelah deployment, perubahan DNS, migrasi gateway, atau pengeditan marketplace. Kegagalan biasanya berasal dari pengalihan, halaman error HTML, atau satu jalur yang terlupakan.

Pertanyaan umum

Pertanyaan umum tentang Well-known Agent JSON

Apa yang harus diterbitkan, di mana menerbitkannya, dan cara menjaga klien kedua konvensi tetap berfungsi.

Jalur Agent Card well-known mana yang harus saya gunakan?

A2A v1.0 mendaftarkan /.well-known/agent-card.json sebagai jalur penemuan standar. Jalur lama /.well-known/agent.json mendahului v1.0 tetapi masih diperiksa oleh banyak klien yang di-deploy, jadi menerbitkan Agent Card yang sama di kedua jalur adalah pilihan pragmatis selama transisi.

Haruskah kedua jalur mengembalikan JSON yang identik?

Ya. Mengembalikan Agent Card publik yang sama dari kedua jalur menjaga konsistensi bagi klien yang hanya mendukung satu konvensi. Dokumen yang berbeda membuat agent tampak berbeda tergantung jalur mana yang diambil klien.

Dengan tipe konten apa Agent Card harus disajikan?

Spesifikasi mendaftarkan application/a2a+json untuk Agent Card. application/json biasa diterima secara luas dalam praktiknya, tetapi tipe konten HTML adalah tanda yang dapat diandalkan bahwa jalur tersebut mengembalikan halaman error, bukan Agent Card.

Bisakah Agent Card publik menyembunyikan kapabilitas privat?

Ya. Terbitkan hanya metadata yang aman untuk penemuan di Agent Card publik, atur capabilities.extendedAgentCard ke true, dan ekspos skill sensitif melalui operasi GetExtendedAgentCard yang terautentikasi.

Mengapa pemeriksaan penemuan gagal setelah deployment?

Penyebab umum adalah pengalihan ke halaman login atau pemasaran, halaman HTML 404 yang dikembalikan dengan status 200, JSON basi yang di-cache di CDN, atau hanya satu dari dua jalur well-known yang di-deploy. Pemeriksa melaporkan kode status dan tipe konten untuk setiap jalur, sehingga kegagalan langsung terlihat.

Sebelum menerbitkan

Validasi Agent Card, lalu periksa URL.

Jalankan JSON melalui validator lengkap terlebih dahulu, terbitkan di kedua jalur well-known, dan konfirmasi penemuan dengan pemeriksa ini.

Buka validatorBuat Agent Card