เครื่องมือค้นพบ · A2A v1.0

ตรวจสอบ URL การค้นพบ A2A Agent Card

ไคลเอนต์ A2A ค้นพบเอเจนต์โดยการดึง Agent Card แบบ JSON จาก URL well-known ทดสอบรูปแบบการตั้งชื่อทั้งสองแบบบนโดเมนจริง และดูสิ่งที่ไคลเอนต์ได้รับจริง ๆ

สร้าง URL การค้นพบที่เป็นไปได้ทั้งสองแบบจากโดเมนฐานเดียวกัน

ดึง JSON ที่ส่งกลับมาและรายงานรหัสสถานะและประเภทเนื้อหา

แยกวิเคราะห์การตอบกลับเป็น Agent Card JSON เมื่อทำได้

รันการตรวจสอบความพร้อมสำหรับอินเทอร์เฟซ สกิล ผู้ให้บริการ โหมด ความสามารถ และข้อมูลเมตาด้านความปลอดภัย

ตรวจสอบโดเมนเอเจนต์สาธารณะ

ป้อนโดเมนฐาน เครื่องมือตรวจสอบจะดึงเส้นทางการค้นพบทั้งสอง แยกวิเคราะห์ JSON ที่ส่งกลับมา และรันการตรวจสอบความพร้อมของ Agent Card

การค้นพบทำงานอย่างไร

URL well-known เดียวเริ่มต้นทุกการเชื่อมต่อ A2A

ก่อนที่เอเจนต์อื่นจะเรียกใช้บริการของคุณได้ มันจะดึง Agent Card จาก URI well-known (RFC 8615) บนโดเมนของคุณก่อน ประเมินสกิลและข้อกำหนดด้านความปลอดภัย จากนั้นเรียกใช้อินเทอร์เฟซที่ต้องการ หาก Agent Card หายไป ล้าสมัย หรือถูกซ่อนอยู่หลังการเปลี่ยนเส้นทาง การเชื่อมต่อจะล้มเหลวก่อนที่จะเริ่มต้น

เว็บไซต์นี้ปฏิบัติตามสิ่งที่ตรวจสอบ: AgentCard.net เผยแพร่ Agent Card ของตัวเองในทั้งสองเส้นทาง และตัวอย่างทางด้านขวาคือเอกสารจริง

ดู Agent Card แบบสดของเรา
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", ... }
  ]
}

เส้นทางการค้นพบ

สองรูปแบบ Agent Card เดียว

เปิดตัวตรวจสอบแบบเต็ม
มาตรฐาน A2A v1.0

/.well-known/agent-card.json

URI well-known ที่ลงทะเบียนโดยข้อกำหนด A2A v1.0 ไคลเอนต์ใหม่จะดึงเส้นทางนี้ก่อน ให้บริการด้วยประเภทเนื้อหา application/a2a+json

แบบเดิม (ก่อน v1.0)

/.well-known/agent.json

ใช้โดยการใช้งาน A2A ยุคแรกและตัวอย่าง codelab ไคลเอนต์ที่ปรับใช้แล้วจำนวนมากยังคงตรวจสอบเฉพาะเส้นทางนี้ ดังนั้นการให้บริการ Agent Card เดียวกันที่นี่จึงเป็นกลยุทธ์การเปลี่ยนผ่านที่ปลอดภัย

รูปแบบการเผยแพร่

ทำให้การค้นพบ Agent Card มีความยืดหยุ่น

ความล้มเหลวในการค้นพบมักไม่ซับซ้อน: การเปลี่ยนเส้นทาง หน้าข้อผิดพลาดที่แคชไว้ หรือปรับใช้เส้นทางหนึ่งแล้วลืมอีกเส้นทางหนึ่ง ขั้นตอนการเผยแพร่นี้ช่วยให้ทั้งสองรูปแบบให้บริการ Agent Card ล่าสุดเดียวกันเสมอ

  1. 1

    เผยแพร่ที่เส้นทางมาตรฐาน

    ให้บริการ Agent Card ที่ตรวจทานแล้วที่ /.well-known/agent-card.json ผ่าน HTTPS บนโดเมนเดียวกับบริการ A2A ด้วยประเภทเนื้อหา application/a2a+json

  2. 2

    สะท้อนเส้นทางแบบเดิม

    ส่งกลับเอกสารเดียวกันจาก /.well-known/agent.json ในขณะที่ไคลเอนต์รุ่นเก่ายังคงใช้งานอยู่ — Agent Card ที่แตกต่างกันในสองเส้นทางจะทำให้การกำหนดเส้นทางสับสน

  3. 3

    รักษา Agent Card ให้ซิงค์กัน

    เมื่อใดก็ตามที่เอนด์พอยต์ สกิล ความสามารถ หรือการยืนยันตัวตนเปลี่ยนแปลง ให้อัปเดต Agent Card เพิ่มค่าฟิลด์ version และปรับใช้ทั้งสองเส้นทางพร้อมกันอีกครั้ง

  4. 4

    ตรวจสอบซ้ำหลังการเปลี่ยนแปลงทุกครั้ง

    รันเครื่องมือตรวจสอบนี้หลังการปรับใช้ การเปลี่ยนแปลง DNS การย้ายเกตเวย์ หรือการแก้ไขมาร์เก็ตเพลส ความล้มเหลวมักมาจากการเปลี่ยนเส้นทาง หน้าข้อผิดพลาด HTML หรือเส้นทางที่ถูกลืม

คำถามที่พบบ่อย

คำถามที่พบบ่อยเกี่ยวกับ Well-known Agent JSON

ควรเผยแพร่อะไร เผยแพร่ที่ไหน และวิธีทำให้ไคลเอนต์ของทั้งสองรูปแบบทำงานต่อไปได้

ควรใช้เส้นทาง Agent Card well-known แบบใด

A2A v1.0 ลงทะเบียน /.well-known/agent-card.json เป็นเส้นทางการค้นพบมาตรฐาน เส้นทางแบบเดิม /.well-known/agent.json มีมาก่อน v1.0 แต่ยังคงถูกตรวจสอบโดยไคลเอนต์ที่ปรับใช้แล้วจำนวนมาก ดังนั้นการเผยแพร่ Agent Card เดียวกันในทั้งสองเส้นทางจึงเป็นทางเลือกที่เหมาะสมในช่วงเปลี่ยนผ่าน

ทั้งสองเส้นทางควรส่งกลับ JSON ที่เหมือนกันหรือไม่

ใช่ การส่งกลับ Agent Card สาธารณะเดียวกันจากทั้งสองเส้นทางช่วยให้ไคลเอนต์ที่รองรับเพียงรูปแบบเดียวมีความสอดคล้องกัน เอกสารที่แตกต่างกันทำให้เอเจนต์ดูแตกต่างกันขึ้นอยู่กับเส้นทางที่ไคลเอนต์ดึงมา

ควรให้บริการ Agent Card ด้วยประเภทเนื้อหาใด

ข้อกำหนดลงทะเบียน application/a2a+json สำหรับ Agent Card application/json ธรรมดาได้รับการยอมรับอย่างกว้างขวางในทางปฏิบัติ แต่ประเภทเนื้อหา HTML เป็นสัญญาณที่เชื่อถือได้ว่าเส้นทางนั้นส่งกลับหน้าข้อผิดพลาดแทนที่จะเป็น Agent Card

Agent Card สาธารณะสามารถซ่อนความสามารถส่วนตัวได้หรือไม่

ได้ เผยแพร่เฉพาะข้อมูลเมตาที่ปลอดภัยสำหรับการค้นพบใน Agent Card สาธารณะ ตั้งค่า capabilities.extendedAgentCard เป็น true และเปิดเผยสกิลที่ละเอียดอ่อนผ่านการดำเนินการ GetExtendedAgentCard ที่ยืนยันตัวตนแล้ว

เหตุใดการตรวจสอบการค้นพบจึงล้มเหลวหลังการปรับใช้

สาเหตุทั่วไปคือการเปลี่ยนเส้นทางไปยังหน้าล็อกอินหรือหน้าการตลาด หน้า HTML 404 ที่ส่งกลับด้วยสถานะ 200 JSON ที่ล้าสมัยซึ่งแคชไว้ใน CDN หรือปรับใช้เพียงหนึ่งในสองเส้นทาง well-known เครื่องมือตรวจสอบจะรายงานรหัสสถานะและประเภทเนื้อหาสำหรับแต่ละเส้นทาง ดังนั้นความล้มเหลวจะปรากฏให้เห็นทันที

ก่อนเผยแพร่

ตรวจสอบ Agent Card แล้วจึงตรวจสอบ URL

ให้ JSON ผ่านตัวตรวจสอบแบบเต็มก่อน เผยแพร่ในทั้งสองเส้นทาง well-known แล้วยืนยันการค้นพบด้วยเครื่องมือตรวจสอบนี้

เปิดตัวตรวจสอบสร้าง Agent Card