Alat penemuan · A2A v1.0

Semak URL penemuan A2A Agent Card

Klien A2A menemui agen dengan mengambil Agent Card JSON dari URL well-known. Uji kedua-dua konvensyen penamaan pada domain sebenar dan lihat dengan tepat apa yang diterima klien.

Membina kedua-dua URL penemuan calon daripada domain asas yang sama.

Mengambil JSON yang dikembalikan dan melaporkan kod status serta jenis kandungan.

Menghurai respons sebagai JSON Agent Card apabila boleh.

Menjalankan semakan kesediaan untuk antara muka, skill, penyedia, mod, keupayaan, dan metadata keselamatan.

Semak domain agen awam

Masukkan domain asas. Penyemak mengambil kedua-dua laluan penemuan, menghurai JSON yang dikembalikan, dan menjalankan semakan kesediaan Agent Card.

Cara penemuan berfungsi

Satu URL well-known memulakan setiap integrasi A2A.

Sebelum agen lain boleh memanggil perkhidmatan anda, ia mengambil Agent Card daripada URI well-known (RFC 8615) pada domain anda, menilai skill dan keperluan keselamatan, kemudian memanggil antara muka pilihan. Jika Agent Card hilang, lapuk, atau tersembunyi di sebalik pengalihan, integrasi gagal sebelum ia bermula.

Laman ini mengamalkan apa yang ia semak: AgentCard.net menerbitkan Agent Card sendiri pada kedua-dua laluan, dan contoh di sebelah kanan ialah dokumen sebenar.

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", ... }
  ]
}

Laluan penemuan

Dua konvensyen, satu Agent Card.

Buka pengesah penuh
Standard A2A v1.0

/.well-known/agent-card.json

URI well-known yang didaftarkan oleh spesifikasi A2A v1.0. Klien baharu mengambil laluan ini dahulu; sajikan dengan jenis kandungan application/a2a+json.

Lama (pra-v1.0)

/.well-known/agent.json

Digunakan oleh pelaksanaan A2A awal dan contoh codelab. Banyak klien yang telah digunakan masih hanya menyemak laluan ini, jadi menyajikan Agent Card yang sama di sini adalah strategi peralihan yang selamat.

Corak penerbitan

Jadikan penemuan Agent Card lebih teguh.

Kegagalan penemuan jarang rumit: pengalihan, halaman ralat yang dicache, atau satu laluan digunakan sementara yang lain dilupakan. Rutin penerbitan ini mengekalkan kedua-dua konvensyen sentiasa menyajikan Agent Card terkini yang sama.

  1. 1

    Terbitkan pada laluan standard

    Sajikan Agent Card yang telah disemak di /.well-known/agent-card.json melalui HTTPS pada domain yang sama dengan perkhidmatan A2A, dengan jenis kandungan application/a2a+json.

  2. 2

    Cerminkan laluan lama

    Kembalikan dokumen yang sama daripada /.well-known/agent.json selagi klien lama masih beredar — Agent Card yang berbeza pada kedua-dua laluan mengelirukan penghalaan.

  3. 3

    Kekalkan Agent Card segerak

    Apabila titik akhir, skill, keupayaan, atau pengesahan berubah, kemas kini Agent Card, naikkan medan version-nya, dan gunakan semula kedua-dua laluan bersama-sama.

  4. 4

    Semak semula selepas setiap perubahan

    Jalankan penyemak ini selepas penggunaan, perubahan DNS, migrasi get laluan, atau pengeditan pasaran. Kegagalan biasanya berpunca daripada pengalihan, halaman ralat HTML, atau satu laluan yang terlupa.

Soalan lazim

Soalan lazim tentang Well-known Agent JSON

Apa yang perlu diterbitkan, di mana menerbitkannya, dan cara mengekalkan klien kedua-dua konvensyen berfungsi.

Laluan Agent Card well-known manakah yang perlu saya gunakan?

A2A v1.0 mendaftarkan /.well-known/agent-card.json sebagai laluan penemuan standard. Laluan lama /.well-known/agent.json mendahului v1.0 tetapi masih disemak oleh banyak klien yang digunakan, jadi menerbitkan Agent Card yang sama pada kedua-dua laluan adalah pilihan pragmatik semasa peralihan.

Perlukah kedua-dua laluan mengembalikan JSON yang sama?

Ya. Mengembalikan Agent Card awam yang sama daripada kedua-dua laluan mengekalkan konsistensi untuk klien yang hanya menyokong satu konvensyen. Dokumen yang berbeza menyebabkan agen kelihatan berbeza bergantung kepada laluan mana yang diambil klien.

Dengan jenis kandungan apakah Agent Card perlu disajikan?

Spesifikasi mendaftarkan application/a2a+json untuk Agent Card. application/json biasa diterima secara meluas dalam praktik, tetapi jenis kandungan HTML adalah tanda yang boleh dipercayai bahawa laluan itu mengembalikan halaman ralat dan bukannya Agent Card.

Bolehkah Agent Card awam menyembunyikan keupayaan peribadi?

Ya. Terbitkan hanya metadata yang selamat untuk penemuan dalam Agent Card awam, tetapkan capabilities.extendedAgentCard kepada true, dan dedahkan skill sensitif melalui operasi GetExtendedAgentCard yang disahkan.

Mengapa semakan penemuan gagal selepas penggunaan?

Punca biasa ialah pengalihan ke halaman log masuk atau pemasaran, halaman HTML 404 yang dikembalikan dengan status 200, JSON lapuk yang dicache pada CDN, atau hanya satu daripada dua laluan well-known digunakan. Penyemak melaporkan kod status dan jenis kandungan untuk setiap laluan, jadi kegagalan kelihatan serta-merta.

Sebelum menerbitkan

Sahkan Agent Card, kemudian semak URL.

Laluan JSON melalui pengesah penuh dahulu, terbitkan pada kedua-dua laluan well-known, dan sahkan penemuan dengan penyemak ini.

Buka pengesahJana Agent Card