Schema संदर्भ · 14 fieldsA2A v1.0
Agent Card वह मानकीकृत JSON दस्तावेज़ है जो A2A क्लाइंट को बताता है कि एक एजेंट कौन है, उससे कहाँ संपर्क करें, वह क्या कर सकता है, और एक्सेस कैसे सुरक्षित है। यह संदर्भ हर v1.0 फील्ड को प्रकार, आवश्यकताओं, उदाहरणों, और उन गलतियों के साथ कवर करता है जिन्हें वैलिडेटर सबसे अधिक बार पकड़ते हैं।
डिस्कवरी कैसे काम करती है
एक A2A क्लाइंट well-known URI से Agent Card लाता है, अपने कार्य के विरुद्ध स्किल्स, क्षमताओं, और सुरक्षा आवश्यकताओं का मूल्यांकन करता है, फिर पसंदीदा इंटरफेस को कॉल करता है — supportedInterfaces में पहली प्रविष्टि। यदि capabilities.extendedAgentCard true है, तो प्रमाणित क्लाइंट GetExtendedAgentCard ऑपरेशन के माध्यम से अधिक समृद्ध Agent Card का अनुरोध कर सकते हैं।
विनिर्देश /.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" }
],
...
}फील्ड संदर्भ
आवश्यक फ्लैग आधिकारिक विनिर्देश में v1.0 protobuf परिभाषाओं का पालन करते हैं। एंकर लिंक हर फील्ड को इश्यू, समीक्षाओं, और CI आउटपुट से उद्धृत करने योग्य बनाते हैं।
एजेंट का मानव-पठनीय नाम।
मार्केटप्लेस लिस्टिंग और क्लाइंट UI में दिखाया जाता है। इसे छोटा और विशिष्ट रखें — क्लाइंट उम्मीदवार एजेंटों की तुलना करते समय इसे प्राथमिक लेबल के रूप में उपयोग करते हैं।
आम गलती: "AI Assistant" जैसे सामान्य नाम का उपयोग करना जो रूटिंग सिस्टम को अलग करने के लिए कुछ नहीं देता।
"name": "भू-स्थानिक मार्ग योजनाकार एजेंट"
एजेंट क्या करता है और दूसरे एजेंट को इसे कब कॉल करना चाहिए।
यह मानव इंटीग्रेटर्स और 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 से पहले) का उपयोग करना। v1.0 Agent Card पढ़ने वाले वैलिडेटर इसे पहचान नहीं पाएंगे।
"provider": {
"organization": "उदाहरण जियो सर्विसेज इंक.",
"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 GetExtendedAgentCard ऑपरेशन के माध्यम से एक समृद्ध प्रमाणित Agent Card का विज्ञापन करता है। 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) को लपेटती है। क्लाइंट यहाँ से प्रमाणित करने का तरीका खोजते हैं — क्रेडेंशियल स्वयं हमेशा आउट-ऑफ-बैंड प्राप्त किए जाते हैं।
आम गलती: Agent Card में एक वास्तविक API कुंजी या टोकन एम्बेड करना। 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": ["टोल से बचते हुए ए से बी तक मार्ग की योजना बनाएं।"]
}]JSON Web Signatures जो साबित करते हैं कि Agent Card प्रोवाइडर द्वारा जारी किया गया था।
हर हस्ताक्षर एक base64url संरक्षित JWS हेडर और हस्ताक्षर मान रखता है, जिसकी गणना RFC 8785 (JCS) मानकीकृत Agent Card पर की जाती है। सार्वजनिक वेब से लाए गए 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 का हिस्सा नहीं; यदि आवश्यक हो तो समकक्ष व्यवहार को एक्सटेंशन के रूप में मॉडल करें। |
बॉयलरप्लेट
टाइप सुरक्षा के साथ Agent Card को पार्स और उत्पन्न करने के लिए इन इंटरफेस को क्लाइंट, सर्वर, या CI जाँच में डालें। ये आधिकारिक विनिर्देश रिपॉजिटरी में protobuf परिभाषाओं को प्रतिबिंबित करते हैं, camelCase JSON रूप में जिसमें 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 Cards खुले वेब से लाए जाते हैं, v1.0 हस्ताक्षर को औपचारिक बनाता है: Agent Card (signatures फ़ील्ड और डिफ़ॉल्ट मानों को छोड़कर) RFC 8785 JSON Canonicalization के साथ मानकीकृत किया जाता है, फिर JWS के रूप में हस्ताक्षरित किया जाता है। Agent Card पर कार्रवाई करने से पहले क्लाइंट को kid/jku हेडर या एक विश्वसनीय कुंजी स्टोर के माध्यम से कम से कम एक हस्ताक्षर सत्यापित करना चाहिए। कई हस्ताक्षर कुंजी रोटेशन का समर्थन करते हैं।
HTTPS पर /.well-known/agent-card.json पर Agent Card सर्व करें।
हर supportedInterfaces प्रविष्टि पहुँच योग्य है और घोषित बाइंडिंग बोलती है।
स्किल्स में आवश्यक टैग के साथ स्पष्ट कार्य सीमाओं वाले विवरण हैं।
घोषित क्षमताएँ सर्वर से मेल खाती हैं — अघोषित सुविधाओं को त्रुटियाँ लौटानी चाहिए, घोषित सुविधाओं को काम करना चाहिए।
securitySchemes वर्णन करता है कि कैसे प्रमाणित करें; Agent Card में कहीं भी कोई क्रेडेंशियल नहीं दिखता।
जब भी Agent Card की सामग्री बदलती है, version को बढ़ाया जाता है।
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 बन गया, स्किल टैग आवश्यक हो गए, और JWS Agent Card हस्ताक्षर को RFC 8785 मानकीकरण के साथ औपचारिक बनाया गया।
नहीं। Agent Card एक एजेंट के लिए एक डिस्कवरी दस्तावेज़ है। यह पहचान, इंटरफेस, क्षमताओं, स्किल्स, मोड, प्रोवाइडर, और सुरक्षा मेटाडेटा को सारांशित करता है, जबकि एक पूर्ण API schema विस्तृत अनुरोध और प्रतिक्रिया आकार का वर्णन करता है। यह किसी सेवा के लिए वही भूमिका निभाता है जो एक README या OpenAPI अवलोकन निभाता है: यह तय करने के लिए पर्याप्त कि इसे कॉल करना है या नहीं और कैसे।
name, description, supportedInterfaces, skills (टैग के साथ), defaultInputModes, defaultOutputModes, capabilities, provider, और सुरक्षा मेटाडेटा। रूटिंग सिस्टम आपके description और स्किल टैग के विरुद्ध कार्यों का मिलान करते हैं, फिर वास्तविक कॉल की योजना बनाने के लिए इंटरफेस और क्षमताओं का उपयोग करते हैं।
केवल वे स्किल्स प्रकाशित करें जो अप्रमाणित डिस्कवरी के लिए सुरक्षित हैं। यदि अधिक समृद्ध निजी Agent Card की आवश्यकता है, तो capabilities.extendedAgentCard को true पर सेट करें और प्रमाणित GetExtendedAgentCard ऑपरेशन के माध्यम से संवेदनशील स्किल्स को उजागर करें।
well-known URI https://{your-domain}/.well-known/agent-card.json पर, कंटेंट टाइप application/a2a+json के साथ सर्व किया जाता है (व्यवहार में application/json भी काम करता है)। पुराने कार्यान्वयन /.well-known/agent.json का उपयोग करते थे, इसलिए संक्रमण के दौरान दोनों को प्रकाशित करना एक व्यावहारिक विकल्प है।
schema को काम में लाएँ
अपनी सेवा के विवरण से v1.0-आकार का Agent Card जनरेट करें, या किसी मौजूदा Agent Card को वैलिडेटर में पेस्ट करें यह देखने के लिए कि किन फ़ील्ड पर ध्यान देने की आवश्यकता है।