เครื่องมือตรวจสอบ Agent Card ตรวจสอบ JSON ที่วาง ไฟล์ Agent Card ที่อัปโหลด และ URL เอเจนต์สาธารณะตามข้อกำหนดการค้นพบ A2A v1.0
วาง JSON, URL ตัวแทนสาธารณะ หรือลากไฟล์ JSON ลงในโปรแกรมแก้ไข
ขอบเขตของเครื่องมือตรวจสอบ Agent Card
เครื่องมือตรวจสอบ Agent Card ออกแบบมาสำหรับนักพัฒนาที่เผยแพร่เอเจนต์ A2A ทีมแพลตฟอร์มภายในที่ตรวจสอบเมตาดาต้าเอเจนต์ และผู้ดำเนินการมาร์เก็ตเพลสที่ตรวจสอบว่า Agent Card ที่ส่งมามีข้อมูลเพียงพอสำหรับการเรียกใช้ที่เชื่อถือได้หรือไม่
วางเอกสาร JSON ในเครื่องระหว่างการพัฒนา อัปโหลด Agent Card จากรีพอสิทอรีของคุณ หรือใช้การตรวจสอบ URL แบบสดกับโดเมนที่ปรับใช้เพื่อยืนยันเส้นทางการค้นพบสาธารณะ
ตรวจสอบฟิลด์ที่จำเป็นตามข้อกำหนด v1.0: name, description, version, supportedInterfaces พร้อม protocolBinding และ protocolVersion ต่ออินเทอร์เฟซ, capabilities, โหมดเนื้อหา, และสกิลอย่างน้อยหนึ่งรายการที่มีแท็กที่จำเป็น
ตรวจจับโครงสร้างก่อน v1.0 — url ระดับบนสุด, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — และบอกคุณอย่างชัดเจนว่าแต่ละฟิลด์ย้ายไปที่ใดใน v1.0
ตรวจสอบว่ามีการประกาศ securitySchemes และข้อกำหนดด้านความปลอดภัยสำหรับเอนด์พอยต์ที่ไม่เปิดเผยต่อสาธารณะ ทำเครื่องหมาย URL ที่ไม่ใช่ HTTPS และสแกนค่าที่ดูเหมือนคีย์ API, JWT หรือโทเค็น bearer ที่ฝังไว้
ดึง /.well-known/agent-card.json และ /.well-known/agent.json แบบเดิมจากโดเมนจริง และยืนยันว่าทั้งสองส่งกลับ Agent Card JSON ที่สามารถแยกวิเคราะห์ได้
การตรวจสอบเหมาะกับที่ใด
Agent Card ที่ผ่านการตรวจสอบเมื่อเดือนที่แล้วยังคงอาจทำให้การค้นพบล้มเหลวในวันนี้ — เอนด์พอยต์เปลี่ยน สกิลเปลี่ยน การปรับใช้ใหม่ทำให้เส้นทาง well-known หายไป ทีมแพลตฟอร์มและผู้ตรวจสอบมาร์เก็ตเพลสถือว่าการตรวจสอบเป็นด่านที่ทำซ้ำได้ ไม่ใช่การตรวจสอบครั้งเดียว
การป้องกัน CI ที่ง่ายที่สุดต้องการเพียง curl: ยืนยันว่าเส้นทาง well-known ตอบสนองด้วย JSON ที่สามารถแยกวิเคราะห์ได้ก่อนที่ทราฟฟิกจะเปลี่ยนไปยังการปรับใช้ใหม่
# 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"])'คู่มือการแก้ไข
ใช้รายงานของเครื่องมือตรวจสอบ Agent Card เพื่อจัดการฟิลด์ที่จำเป็นก่อน จากนั้นปรับปรุงรายละเอียดการค้นพบ ความน่าเชื่อถือ และการย้ายระบบ
แทนที่ URL เอนด์พอยต์ตัวยึดตำแหน่งด้วย URL บริการ A2A HTTPS ที่ปรับใช้แล้ว
ย้าย url และ preferredTransport ระดับบนสุดเข้าไปในอาร์เรย์ supportedInterfaces ที่เรียงลำดับ — รายการแรกคืออินเทอร์เฟซที่ต้องการ
เพิ่มฟิลด์ version ระดับบนสุดที่จำเป็นซึ่งอธิบายตัวเอเจนต์เอง และเพิ่มแท็กให้กับทุกสกิล
เปลี่ยนชื่อ provider.name เป็น provider.organization และขยายคำอธิบายสั้น ๆ เพื่อให้ไคลเอนต์รู้ว่าเมื่อใดควรเรียกใช้เอเจนต์
ประกาศเมตาดาต้าความปลอดภัยทุกครั้งที่เอนด์พอยต์เอเจนต์ไม่เปิดเผยต่อสาธารณะทั้งหมด — และอย่าฝังข้อมูลรับรองเอง
เผยแพร่ Agent Card ที่ถูกต้องเดียวกันที่ /.well-known/agent-card.json (และที่เส้นทาง agent.json แบบเดิมในขณะที่ไคลเอนต์ยังคงตรวจสอบทั้งสองเส้นทาง)
คำถามที่พบบ่อย
จัดการสิ่งจำเป็นให้ถูกต้องก่อนที่เอเจนต์ของคุณจะเข้าถึงไคลเอนต์ A2A
เปรียบเทียบตัวอย่างที่ถูกต้องการตรวจสอบเป็นไปตามโครงสร้าง Agent Card ของ A2A v1.0 — supportedInterfaces, เวอร์ชันโปรโตคอลต่ออินเทอร์เฟซ, แท็กสกิลที่จำเป็น, provider.organization Agent Card ก่อน v1.0 จะไม่ถูกปฏิเสธทันที: ฟิลด์เดิมจะแสดงเป็นคำเตือนพร้อมการแทนที่ v1.0 ที่ชัดเจน
ข้อกำหนด v1.0 ลงทะเบียน /.well-known/agent-card.json แต่การใช้งาน A2A ก่อนหน้านี้ใช้ /.well-known/agent.json การตรวจสอบทั้งสองจะจับช่องว่างการค้นพบก่อนที่ไคลเอนต์จะล้มเหลว
คำเตือนไม่ได้บล็อกเหมือนข้อผิดพลาด JSON แต่โดยปกติจะชี้ไปที่เมตาดาต้าที่ทำให้เอเจนต์ค้นพบ เชื่อถือ และเรียกใช้ได้ง่ายขึ้น — หรือชี้ไปที่ฟิลด์ก่อน v1.0 ที่ไคลเอนต์ใหม่กว่าจะหยุดอ่าน
สามช่วงเวลา: ขณะแก้ไข Agent Card ระหว่างการพัฒนา เป็นด่าน CI ก่อนการปรับใช้ และหลังจากเผยแพร่ — วาง URL บริการจริงเพื่อยืนยันสิ่งที่ไคลเอนต์ได้รับจริงจากทั้งสองเส้นทางการค้นพบ
พร้อมตรวจสอบ
วาง JSON วางไฟล์ Agent Card หรือตรวจสอบ URL สาธารณะจากพื้นที่ทำงานเครื่องมือตรวจสอบแบบรวม