เอกสารอ้างอิง Schema · 14 fieldsA2A v1.0
Agent Card คือเอกสาร JSON มาตรฐานที่บอกไคลเอนต์ A2A ว่าเอเจนต์คือใคร ติดต่อได้ที่ไหน ทำอะไรได้บ้าง และการเข้าถึงได้รับการปกป้องอย่างไร เอกสารอ้างอิงนี้ครอบคลุมทุกฟิลด์ v1.0 พร้อมประเภท ข้อกำหนด ตัวอย่าง และข้อผิดพลาดที่เครื่องมือตรวจสอบมักตรวจพบบ่อยที่สุด
การค้นพบทำงานอย่างไร
ไคลเอนต์ A2A ดึง Agent Card จาก URI well-known ประเมินสกิล ความสามารถ และข้อกำหนดด้านความปลอดภัยตามงานของตน จากนั้นเรียกใช้อินเทอร์เฟซที่ต้องการ — รายการแรกใน supportedInterfaces หาก capabilities.extendedAgentCard เป็น true ไคลเอนต์ที่ยืนยันตัวตนแล้วสามารถขอ Agent Card ที่สมบูรณ์ยิ่งขึ้นผ่านการดำเนินการ GetExtendedAgentCard
ข้อกำหนดลงทะเบียน /.well-known/agent-card.json เป็นตำแหน่งมาตรฐาน การปรับใช้ v0.x รุ่นเก่าใช้ /.well-known/agent.json นี่คือเหตุผลที่เครื่องมือตรวจสอบของเราตรวจสอบทั้งสองอย่าง
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}เอกสารอ้างอิงฟิลด์
ธงบังคับเป็นไปตามคำจำกัดความ 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
}รูปแบบการยืนยันตัวตนที่มีชื่อ: คีย์ 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 เพื่อหลีกเลี่ยงค่าผ่านทาง"]
}]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 ของคุณยังมี url หรือ preferredTransport ระดับบนสุด แสดงว่ามันมีมาก่อน v1.0 เครื่องมือตรวจสอบจะตั้งค่าสถานะแต่ละรายการเหล่านี้โดยอัตโนมัติ
| ฟิลด์ v0.x | ตัวแทน v1.0 | เหตุใดจึงเปลี่ยน |
|---|---|---|
| url | supportedInterfaces[0].url | เอนด์พอยต์ที่ต้องการตอนนี้เป็นเพียงรายการอินเทอร์เฟซแรก |
| preferredTransport | supportedInterfaces[] ordering | ความชอบแสดงโดยลำดับอาร์เรย์แทนที่จะเป็นฟิลด์แยกต่างหาก |
| additionalInterfaces | supportedInterfaces[] | อินเทอร์เฟซทั้งหมดอยู่ในอาร์เรย์ที่เรียงลำดับเดียว |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | แต่ละอินเทอร์เฟซประกาศเวอร์ชันโปรโตคอลของตัวเอง ทำให้รองรับหลายเวอร์ชันได้ |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | ย้ายเข้าไปในอ็อบเจกต์ capabilities; RPC ถูกเปลี่ยนชื่อเป็น GetExtendedAgentCard |
| provider.name | provider.organization | เปลี่ยนชื่อเพื่อความชัดเจน |
| capabilities.stateTransitionHistory | — removed | ไม่ใช่ส่วนหนึ่งของ v1.0; จำลองพฤติกรรมที่เทียบเท่าเป็นส่วนขยายหากจำเป็น |
โค้ดต้นแบบ
วางอินเทอร์เฟซเหล่านี้ลงในไคลเอนต์ เซิร์ฟเวอร์ หรือการตรวจสอบ CI เพื่อแยกวิเคราะห์และสร้าง Agent Card ด้วยความปลอดภัยของประเภท พวกมันสะท้อนคำจำกัดความ protobuf ในที่เก็บข้อกำหนดอย่างเป็นทางการ ในรูปแบบ JSON camelCase ที่ Agent Card ถูกเผยแพร่
กำลังสร้าง Agent Card ด้วยตนเองแทนหรือไม่? เครื่องมือสร้างจะสร้างรูปแบบที่แน่นอนนี้
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }ความสมบูรณ์
เนื่องจาก 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 เปลี่ยนแปลง
เอเจนต์สนับสนุนลูกค้าที่มี OAuth 2.0, สตรีมมิ่ง, และการแจ้งเตือนแบบพุช — มีฟิลด์ที่จำเป็นทั้งหมด รูปแบบเพิ่มเติมอยู่ในไลบรารีตัวอย่าง
{
"name": "เอเจนต์สนับสนุนลูกค้า",
"description": "ตอบคำถามฝ่ายสนับสนุนลูกค้า ดึงข้อมูลบริบทของคำสั่งซื้อ และยกระดับปัญหาที่ยังไม่ได้รับการแก้ไขไปยังทีมงานที่เป็นมนุษย์",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "ตัวอย่างอิงค์",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "แก้ไขคำขอการสนับสนุนลูกค้า",
"description": "จำแนกคำขอการสนับสนุนลูกค้า รวบรวมบริบทที่จำเป็น เสนอวิธีแก้ปัญหา และเพิ่มระดับเมื่อความเชื่อมั่นต่ำ",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"ช่วยฉันคืนคำสั่งซื้อของฉันด้วย"
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}คำถามที่พบบ่อย
การเปลี่ยนแปลงเวอร์ชัน ฟิลด์การค้นพบ และรายละเอียดการเผยแพร่ที่ตัดสินว่า Agent Card จะผ่านการตรวจสอบหรือไม่
v1.0 รวม url, preferredTransport, และ additionalInterfaces เข้าเป็นอาร์เรย์ supportedInterfaces ที่เรียงลำดับเดียวซึ่งแต่ละรายการประกาศ url, protocolBinding, และ protocolVersion ของตัวเอง supportsAuthenticatedExtendedCard ย้ายไปยัง capabilities.extendedAgentCard, provider.name กลายเป็น provider.organization, แท็กสกิลกลายเป็นสิ่งจำเป็น และลายเซ็น Agent Card JWS ได้รับการทำให้เป็นทางการด้วยการได้มาตรฐาน RFC 8785
ไม่ Agent Card เป็นเอกสารการค้นพบสำหรับเอเจนต์ มันสรุปตัวตน อินเทอร์เฟซ ความสามารถ สกิล โหมด ผู้ให้บริการ และเมตาดาต้าความปลอดภัย ในขณะที่ schema ของ API แบบเต็มอธิบายรูปแบบคำขอและการตอบสนองโดยละเอียด มันมีบทบาทเช่นเดียวกับที่ README หรือภาพรวม OpenAPI มีสำหรับบริการ: เพียงพอที่จะตัดสินใจว่าจะเรียกใช้หรือไม่และอย่างไร
name, description, supportedInterfaces, skills (พร้อมแท็ก), defaultInputModes, defaultOutputModes, capabilities, provider, และเมตาดาต้าความปลอดภัย ระบบกำหนดเส้นทางจับคู่งานกับ description และแท็กสกิลของคุณ จากนั้นใช้อินเทอร์เฟซและความสามารถเพื่อวางแผนการเรียกใช้จริง
เผยแพร่เฉพาะสกิลที่ปลอดภัยสำหรับการค้นพบที่ไม่ได้ยืนยันตัวตน หากต้องการ Agent Card ส่วนตัวที่สมบูรณ์ยิ่งขึ้น ให้ตั้งค่า capabilities.extendedAgentCard เป็น true และเปิดเผยสกิลที่ละเอียดอ่อนผ่านการดำเนินการ GetExtendedAgentCard ที่ยืนยันตัวตนแล้ว
ที่ URI well-known https://{your-domain}/.well-known/agent-card.json ให้บริการด้วยประเภทเนื้อหา application/a2a+json (application/json ก็ใช้งานได้เช่นกันในทางปฏิบัติ) การใช้งานก่อนหน้านี้ใช้ /.well-known/agent.json ดังนั้นการเผยแพร่ทั้งสองอย่างในช่วงเปลี่ยนผ่านจึงเป็นทางเลือกที่ใช้ได้จริง
ใช้ schema ให้เกิดประโยชน์
สร้าง Agent Card ในรูปแบบ v1.0 จากรายละเอียดบริการของคุณ หรือวาง Agent Card ที่มีอยู่แล้วลงในเครื่องมือตรวจสอบเพื่อดูว่าฟิลด์ใดต้องการความสนใจอย่างแม่นยำ