เอกสารอ้างอิง Schema · 14 fieldsA2A v1.0
Schema ของ A2A Agent Card แบบทีละฟิลด์
Agent Card คือเอกสาร JSON มาตรฐานที่บอกไคลเอนต์ A2A ว่าเอเจนต์คือใคร ติดต่อได้ที่ไหน ทำอะไรได้บ้าง และการเข้าถึงได้รับการปกป้องอย่างไร เอกสารอ้างอิงนี้ครอบคลุมทุกฟิลด์ v1.0 พร้อมประเภท ข้อกำหนด ตัวอย่าง และข้อผิดพลาดที่เครื่องมือตรวจสอบมักตรวจพบบ่อยที่สุด
เอกสารอ้างอิงฟิลด์
ทุกฟิลด์ของ AgentCard พร้อมรายละเอียดที่ตัดสินว่าผ่านหรือไม่ผ่าน
ธงบังคับเป็นไปตามคำจำกัดความ protobuf v1.0 ในข้อกำหนดอย่างเป็นทางการ ลิงก์จุดยึดทำให้แต่ละฟิลด์สามารถอ้างอิงได้จากปัญหา การตรวจสอบ และผลลัพธ์ CI
ชื่อที่มนุษย์อ่านได้ของเอเจนต์
แสดงในรายการมาร์เก็ตเพลสและ UI ไคลเอนต์ ควรสั้นและเจาะจง — ไคลเอนต์ใช้เป็นป้ายกำกับหลักเมื่อเปรียบเทียบเอเจนต์ที่เป็นตัวเลือก
ข้อผิดพลาดทั่วไป: การใช้ชื่อทั่วไปเช่น "AI Assistant" ที่ไม่ให้ระบบกำหนดเส้นทางมีอะไรให้แยกแยะ
"name": "ตัวแทนวางแผนเส้นทาง GeoSpatial"
เอเจนต์ทำอะไร และเมื่อไรที่เอเจนต์อื่นควรเรียกใช้มัน
นี่คือสัญญาณข้อความอิสระหลักสำหรับทั้งผู้รวมระบบที่เป็นมนุษย์และเราเตอร์ที่ใช้ LLM ในการตัดสินใจว่าเอเจนต์ของคุณเหมาะกับงานหรือไม่ ระบุขอบเขตของงาน ความสามารถหลัก และขอบเขตจำกัด
ข้อผิดพลาดทั่วไป: คำอธิบายบรรทัดเดียวที่มีความยาวต่ำกว่า 20 ตัวอักษร เราเตอร์ไม่สามารถจับคู่สิ่งที่คุณไม่ได้อธิบายได้
"description": "ให้การวางแผนเส้นทางขั้นสูง การวิเคราะห์การจราจร และบริการสร้างแผนที่แบบกำหนดเอง"
รายการที่เรียงลำดับของเอนด์พอยต์และการเชื่อมโยงโปรโตคอล รายการแรกเป็นที่ต้องการ
ใหม่ใน v1.0: แทนที่ฟิลด์ระดับบนสุดเดิม url, preferredTransport, และ additionalInterfaces แต่ละรายการประกาศ url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, หรือ URI การเชื่อมโยงแบบกำหนดเอง), protocolVersion ของตัวเอง และคีย์การกำหนดเส้นทางผู้เช่าที่เป็นทางเลือก — ดังนั้นเอเจนต์เดียวจึงสามารถให้บริการหลายเวอร์ชันโปรโตคอลและการขนส่งพร้อมกันได้
ข้อผิดพลาดทั่วไป: การประกาศการเชื่อมโยงที่เซิร์ฟเวอร์ไม่ได้ให้บริการจริงที่ URL นั้น — ข้อกำหนดกำหนดให้แต่ละรายการต้องถูกต้อง
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]ใครเป็นผู้ดำเนินการเอเจนต์: องค์กรและเว็บไซต์
สัญญาณความเชื่อถือสำหรับมาร์เก็ตเพลสและการตรวจสอบขององค์กร v1.0 เปลี่ยนชื่อฟิลด์ name เป็น organization; url จำเป็นภายในอ็อบเจกต์เมื่อมีอยู่
ข้อผิดพลาดทั่วไป: ยังคงใช้ provider.name (ก่อน v1.0) เครื่องมือตรวจสอบที่อ่าน Agent Card v1.0 จะไม่รู้จักมัน
"provider": {
"organization": "ตัวอย่าง Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}เวอร์ชันของตัวเอเจนต์เอง ไม่ใช่ของโปรโตคอล
ช่วยให้ไคลเอนต์ตรวจจับได้ว่า Agent Card เปลี่ยนแปลงอย่างมีนัยสำคัญเมื่อใดและประเมินความเข้ากันได้ใหม่ ปฏิบัติตามรูปแบบการเผยแพร่ของคุณเอง โดยทั่วไปคือ semver
ข้อผิดพลาดทั่วไป: สับสนกับเวอร์ชันโปรโตคอล A2A — ซึ่งตอนนี้อยู่ในแต่ละรายการ supportedInterfaces
"version": "1.2.0"
ลิงก์ไปยังเอกสารที่มนุษย์อ่านได้สำหรับเอเจนต์
ให้ผู้รวมระบบมีที่ที่จะอ่านสัญญา API ฉบับเต็ม ขีดจำกัดอัตรา และข้อกำหนดที่ไม่ควรอยู่ในเอกสารการค้นพบ
ข้อผิดพลาดทั่วไป: ชี้ไปที่หน้าแรกทางการตลาดแทนที่จะเป็นเอกสารทางเทคนิค
"documentationUrl": "https://docs.example.com/agent"
แฟล็กคุณสมบัติโปรโตคอล: streaming, pushNotifications, extensions, extendedAgentCard
ไคลเอนต์ต้องไม่เรียกใช้คุณสมบัติที่คุณไม่ได้ประกาศ — การเรียกสตรีมมิ่งที่ไม่ได้ประกาศจะส่งคืนข้อผิดพลาด extendedAgentCard: true ประกาศ Agent Card ที่ยืนยันตัวตนที่สมบูรณ์ยิ่งขึ้นผ่านการดำเนินการ GetExtendedAgentCard v1.0 ได้ลบ stateTransitionHistory ออกไป
ข้อผิดพลาดทั่วไป: การประกาศ streaming: true เมื่อเซิร์ฟเวอร์ไม่มีเอนด์พอยต์สตรีมมิ่ง ไคลเอนต์จะเรียกใช้มันและล้มเหลว
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}map<string, SecurityScheme>ไม่บังคับ รูปแบบการยืนยันตัวตนที่มีชื่อ: คีย์ API, การยืนยันตัวตน HTTP, OAuth 2.0, OpenID Connect, หรือ TLS แบบสองทาง
แต่ละรูปแบบที่มีชื่อจะห่อหุ้มอ็อบเจกต์รูปแบบที่เป็นรูปธรรมหนึ่งรายการ (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme) ไคลเอนต์ค้นพบวิธีการยืนยันตัวตนจากที่นี่ — ข้อมูลรับรองเองจะได้รับจากนอกช่องทางเสมอ
ข้อผิดพลาดทั่วไป: การฝังคีย์ API หรือโทเค็นจริงใน Agent Card Agent Card เป็นเอกสารสาธารณะ
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}รูปแบบที่ประกาศ (และขอบเขต) ใดที่จำเป็นสำหรับการเรียกใช้เอเจนต์
แต่ละรายการแมปชื่อรูปแบบจาก securitySchemes ไปยังขอบเขตที่ต้องการ สะท้อนรูปแบบข้อกำหนดความปลอดภัยของ OpenAPI ละเว้นทั้งสองฟิลด์ทั้งหมดสำหรับเอเจนต์ที่ตั้งใจให้เป็นสาธารณะ
ข้อผิดพลาดทั่วไป: การประกาศ securitySchemes แต่ไม่มีข้อกำหนด security ทำให้ไคลเอนต์ต้องเดาว่าการยืนยันตัวตนถูกบังคับใช้หรือไม่
"security": [{ "google": ["openid", "profile", "email"] }]ประเภทสื่อที่เอเจนต์ยอมรับในทุกสกิล
ประเภท MIME มาตรฐาน เช่น text/plain, application/json, หรือ image/png สกิลแต่ละรายการสามารถแทนที่ด้วย inputModes ของตัวเองได้
ข้อผิดพลาดทั่วไป: การละเว้นฟิลด์ มันจำเป็นใน v1.0 — ไคลเอนต์ต้องการมันเพื่อกำหนดรูปแบบคำขอ
"defaultInputModes": ["application/json", "text/plain"]
ประเภทสื่อที่เอเจนต์ส่งคืนในทุกสกิล
บอกผู้เรียกว่าควรคาดหวังข้อความ, JSON ที่มีโครงสร้าง, รูปภาพ, หรือไฟล์ สกิลสามารถแทนที่ต่อสกิลด้วย outputModes
ข้อผิดพลาดทั่วไป: การแสดงรายการเฉพาะ text/plain ในขณะที่เอเจนต์ส่งคืนสิ่งประดิษฐ์ที่มีโครงสร้างจริง
"defaultOutputModes": ["application/json", "image/png"]
ความสามารถที่เป็นรูปธรรมที่เอเจนต์มีแนวโน้มที่จะประสบความสำเร็จ
แต่ละสกิลต้องมี id, name, description, และ tags; examples, โหมดต่อสกิล, และความปลอดภัยต่อสกิลเป็นทางเลือก สกิลเป็นหน่วยของการค้นพบ — เราเตอร์จับคู่งานกับสิ่งเหล่านี้ ดังนั้นให้จำกัดขอบเขตแต่ละอย่างไว้ที่ขอบเขตงานเดียว
ข้อผิดพลาดทั่วไป: สกิลที่ไม่มีแท็ก แท็กกลายเป็นสิ่งจำเป็นใน v1.0 และขับเคลื่อนการจับคู่ระดับสกิล
"skills": [{
"id": "route-optimizer-traffic",
"name": "เครื่องมือเพิ่มประสิทธิภาพเส้นทางการรับรู้การจราจร",
"description": "คำนวณเส้นทางการขับขี่ที่เหมาะสมที่สุดโดยใช้สภาพการจราจรแบบเรียลไทม์...",
"tags": ["maps", "routing", "traffic"],
"examples": ["วางแผนเส้นทางจาก A ไป B เพื่อหลีกเลี่ยงค่าผ่านทาง"]
}]AgentCardSignature[]ไม่บังคับ JSON Web Signature ที่พิสูจน์ว่า Agent Card ออกโดยผู้ให้บริการ
แต่ละลายเซ็นมีส่วนหัว JWS ที่ได้รับการป้องกันแบบ base64url และค่าลายเซ็น ซึ่งคำนวณจาก Agent Card ที่ได้มาตรฐานตาม RFC 8785 (JCS) ไคลเอนต์ควรตรวจสอบลายเซ็นอย่างน้อยหนึ่งรายการก่อนที่จะเชื่อถือ Agent Card ที่ดึงมาจากเว็บแบบเปิด
ข้อผิดพลาดทั่วไป: การลงนามการ์ดแล้วแก้ไขฟิลด์ใด ๆ — แม้แต่การเปลี่ยนแปลงค่าที่ไม่มีนัยสำคัญในช่องว่างก็ทำให้ JWS ไม่ถูกต้อง
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL ไปยังไอคอนที่แสดงถึงเอเจนต์
ใช้โดยแคตตาล็อกและ UI ไคลเอนต์ ให้บริการผ่าน HTTPS จากตำแหน่งที่มั่นคง
ข้อผิดพลาดทั่วไป: การเชื่อมโยงไอคอนบนโดเมนอื่นที่ไม่น่าเชื่อถือซึ่งอาจเปลี่ยนแปลงโดยที่คุณไม่รู้ตัวอยู่เบื้องหลังรายการของคุณ
"iconUrl": "https://agent.example.com/icon.png"
ความสมบูรณ์
ลายเซ็น Agent Card โดยสรุป
เนื่องจาก Agent Card ถูกดึงมาจากเว็บแบบเปิด v1.0 จึงทำให้การลงนามเป็นทางการ: Agent Card (ลบฟิลด์ signatures และค่าเริ่มต้น) จะได้มาตรฐานด้วย RFC 8785 JSON Canonicalization จากนั้นลงนามเป็น JWS ไคลเอนต์ควรตรวจสอบลายเซ็นอย่างน้อยหนึ่งรายการ — ผ่านส่วนหัว kid/jku หรือที่เก็บคีย์ที่เชื่อถือได้ — ก่อนดำเนินการกับ Agent Card ลายเซ็นหลายรายการรองรับการหมุนเวียนคีย์
รายการตรวจสอบก่อนเผยแพร่
ให้บริการ Agent Card ที่ /.well-known/agent-card.json ผ่าน HTTPS
ทุกรายการ supportedInterfaces เข้าถึงได้และใช้การเชื่อมโยงที่ประกาศไว้
สกิลมีแท็กที่จำเป็นพร้อมคำอธิบายที่มีขอบเขตงานที่ชัดเจน
ความสามารถที่ประกาศไว้ตรงกับเซิร์ฟเวอร์ — คุณสมบัติที่ไม่ได้ประกาศต้องส่งคืนข้อผิดพลาด คุณสมบัติที่ประกาศต้องทำงานได้
securitySchemes อธิบายวิธีการยืนยันตัวตน; ไม่มีข้อมูลรับรองปรากฏที่ใดใน Agent Card
version จะเพิ่มขึ้นทุกครั้งที่เนื้อหา Agent Card เปลี่ยนแปลง
ใช้ schema ให้เกิดประโยชน์
สร้าง Agent Card ที่ผ่านการตรวจสอบครั้งแรก
สร้าง Agent Card ในรูปแบบ v1.0 จากรายละเอียดบริการของคุณ หรือวาง Agent Card ที่มีอยู่แล้วลงในเครื่องมือตรวจสอบเพื่อดูว่าฟิลด์ใดต้องการความสนใจอย่างแม่นยำ
จากบล็อก
คู่มือภาคปฏิบัติสำหรับการค้นพบ A2A เขียนตามข้อกำหนดเวอร์ชัน 1.0
บทความทั้งหมดComparisonA2A vs MCP: two protocols solving two different problems
Compare A2A vs MCP: what each protocol connects, where they overlap, and why production AI agent systems often use both for tools and agent collaboration.
9 min readอ่านคู่มือHow-toHow to create an agent.json file for A2A v1.0
Learn how to create an agent.json file for A2A v1.0, including required Agent Card fields, the well-known URL, response headers, and common mistakes.
11 min readอ่านคู่มือIntegrationPublishing an Agent Card from ADK, LangGraph, CrewAI or Semantic Kernel
Learn how to publish an A2A Agent Card from Google ADK, LangGraph, CrewAI, or Semantic Kernel by mapping framework concepts to standard discovery fields.
10 min readอ่านคู่มือ บทความเผยแพร่เป็นภาษาอังกฤษ