A2A एजेंट

जब एक एजेंट दूसरे को काम सौंपता है, तब A2A इस्तेमाल करें। MCP टूल और संसाधन उपलब्ध कराता है; A2A एजेंट संदेश, टास्क, स्थिति अपडेट और आउटपुट आर्टिफ़ैक्ट का वर्णन करता है। दोनों को एक स्थानीय विनिर्देश में रख सकते हैं, लेकिन उन्हें एक ही प्रोटोकॉल न मानें।

बनाना और डीबग करना

डीबग में नया अनुरोध → A2A चुनें। डिफ़ॉल्ट A2A 1.0 है, जिसमें HTTP पर JSON-RPC इस्तेमाल होता है।
URL बार में एजेंट का JSON-RPC एंडपॉइंट दें। पुराने एजेंट के लिए स्पष्ट रूप से संस्करण 0.3 चुनें; Powerduck संस्करणों के बीच चुपचाप रूपांतरण नहीं करता।
प्रोटोकॉल टैब में विधि चुनकर अनुरोध बॉडी बनाएँ पर क्लिक करें। पूर्वावलोकन जाँचें, फिर लागू करने के लिए अनुरोध बॉडी बदलें चुनें। रद्द करने या विधि बदलने पर मौजूदा ड्राफ़्ट सुरक्षित रहता है।
बॉडी टैब में params संपादित करें। क्रेडेंशियल के लिए प्रमाणीकरण और हेडर का उपयोग करें; भेजते समय चुना हुआ A2A-Version हेडर जुड़ता है।
अनुरोध भेजें। पूरे JSON-RPC एनवेलप की जाँच करें: HTTP 200 में भी error हो सकता है। सफल 1.0 प्रतिक्रियाओं में result के अंदर task या message होता है; 0.3 की प्रतिक्रिया संरचनाएँ अलग हैं।
त्वरित अनुरोध जोड़ने के लिए विनिर्देश में सहेजें इस्तेमाल करें। मौजूदा कार्रवाई में सहेजें स्थानीय डीबगिंग सेटिंग रखता है; विनिर्देश अपडेट करें उसकी परिभाषा स्पष्ट रूप से अपडेट करता है। संस्करण, एंडपॉइंट, विधि और दस्तावेज़ित स्कीमा x-a2a में रहते हैं; स्थानीय अनुरोध ड्राफ़्ट OAS में निर्यात नहीं होते। प्रोटोकॉल अनुबंध संपादित करने के लिए दस्तावेज़ संपादित करें इस्तेमाल करें।

संदेश ID और JSON-RPC अनुरोध ID अलग होते हैं। नया उदाहरण नए ID बनाता है। बातचीत जारी रखने के लिए लौटे हुए संदर्भ/टास्क पहचानकर्ता अगले संदेश में चुने हुए प्रोटोकॉल संस्करण के नियमों के अनुसार रखें।

Agent Card

स्पष्ट URL के साथ सार्वजनिक Agent Card प्राप्त करें इस्तेमाल करें; सामान्य URL /.well-known/agent-card.json है। एंडपॉइंट सेट करने से पहले घोषित इंटरफ़ेस, संस्करण, कौशल, प्रमाणीकरण और क्षमताएँ जाँचें। कार्ड प्राप्त करने से अनुरोध URL अपने आप नहीं बदलता और क्रेडेंशियल दूसरे ओरिजिन को नहीं भेजे जाते।

सार्वजनिक खोज अनुरोध के क्रेडेंशियल नहीं भेजती और रीडायरेक्ट अस्वीकार करती है। डेस्कटॉप नेटिव HTTP रनर इस्तेमाल करता है; ब्राउज़र में खोज के लिए CORS चाहिए। प्रतिक्रियाओं की सीमा 1 MiB है। A2A 1.0 के लिए JWS हस्ताक्षर सत्यापित करें खोलें और भरोसेमंद सार्वजनिक JWKS पेस्ट करें। सत्यापन स्थानीय है, असममित हस्ताक्षरों का समर्थन करता है और कार्ड में दिए कुंजी URL पर कभी नहीं जाता। अनिवार्य खाली मान प्रोजेक्ट में तय A2A proto के अनुसार सुरक्षित रहते हैं। मानक कार्ड स्कीमा से बाहर के कस्टम फ़ील्ड प्रमाणित नहीं होते। बिना हस्ताक्षर वाले और असत्यापित कार्ड स्पष्ट रूप से चिह्नित होते हैं; स्नैपशॉट सहेजना भरोसे का निर्णय सहेजना नहीं है। सुरक्षित मेटाडेटा के लिए अनुरोध के प्रमाणीकरण के साथ विस्तारित-कार्ड RPC इस्तेमाल करें। कार्ड को विनिर्देश में सहेजें केवल स्नैपशॉट रखता है; विनिर्देश साझा या होस्ट करने से पहले निजी मेटाडेटा हटा दें।

टास्क और स्ट्रीमिंग

1.0 के लिए SendStreamingMessage या SubscribeToTask इस्तेमाल करें; 0.3 के लिए message/stream या tasks/resubscribe। प्रतिक्रियाएँ मौजूदा SSE इवेंट व्यूअर में दिखाई देती हैं, जिसमें प्रतिक्रिया सीमाएँ और रद्द करने के नियंत्रण हैं। मूल स्थिति और आर्टिफ़ैक्ट अपडेट जाँचने के लिए उपलब्ध रहते हैं।

रोकें स्थानीय अनुरोध का कनेक्शन बंद करता है; दूर का काम रद्द नहीं करता। दूर का काम रद्द करने का अनुरोध करने के लिए लौटे हुए टास्क ID के साथ 1.0 में CancelTask या 0.3 में tasks/cancel भेजें। अंतिम स्थिति में पहुँचा टास्क सीधे फिर शुरू नहीं किया जा सकता।

टास्क प्राप्त करने, 1.0 में सूची देखने, विस्तारित कार्ड और पुश-नोटिफ़िकेशन कॉन्फ़िगरेशन की विधियाँ उपलब्ध हैं। A2A 1.0 इन्हें तीनों बाइंडिंग से उपलब्ध कराता है; 0.3 JSON-RPC इस्तेमाल करता है। वैकल्पिक कार्रवाइयाँ एजेंट की घोषित क्षमताओं पर निर्भर हैं। Powerduck पुश-नोटिफ़िकेशन रिसीवर होस्ट नहीं करता।

OpenAPI एक्सटेंशन

x-a2a Powerduck का OpenAPI एक्सटेंशन है, मानक A2A Agent Card या OpenAPI का मानक कीवर्ड नहीं। JSON-RPC कार्रवाइयाँ post इस्तेमाल करती हैं। OpenAPI पथ दस्तावेज़ित कार्रवाई की पहचान करता है; endpoint वास्तविक दूरस्थ JSON-RPC URL है।

openapi: 3.2.0
info:
  title: Research agent
  version: 1.0.0
paths:
  /agents/research/send:
    post:
      summary: Ask the research agent
      x-protocol: a2a
      x-a2a:
        version: '1.0'
        binding: JSONRPC
        endpoint: https://agent.example.com/rpc
        agentCardUrl: https://agent.example.com/.well-known/agent-card.json
        method: SendMessage
        requestSchema:
          type: object
          description: Application-specific message parameters
        responseSchema:
          type: object
          description: JSON-RPC response envelope
        example:
          jsonrpc: '2.0'
          id: request-1
          method: SendMessage
          params:
            message:
              messageId: message-1
              role: ROLE_USER
              parts:
                - text: Summarize the release notes
      responses:
        '200':
          description: A2A response; inspect result or error
          content:
            application/json:
              schema:
                type: object

स्ट्रीमिंग प्रतिक्रिया के लिए text/event-stream के साथ OAS 3.2 का itemSchema इस्तेमाल करें, जो एक JSON-RPC इवेंट बताता है। डिज़ाइन एडिटर अनुरोध और प्रतिक्रिया के स्वतंत्र स्कीमा का समर्थन करता है। प्रकाशित दस्तावेज़ और LLM के लिए कॉपी, A2A कॉन्फ़िगरेशन तथा दस्तावेज़ित अनुबंध सुरक्षित रखते हैं।

फ़ील्ड	अर्थ
`version`	समर्थित ट्रांसमिशन संस्करण: `1.0` या `0.3`
`binding`	`JSONRPC`; A2A 1.0 में `HTTP+JSON` और `GRPC` भी समर्थित हैं
`endpoint`	JSON-RPC एंडपॉइंट, REST बेस URL या HTTP(S) gRPC सर्वर पता
`method`	संस्करण-विशिष्ट विधि: REST/gRPC इस चयन का उपयोग करते हैं; JSON-RPC बॉडी में दी विधि का
`agentCardUrl`	सार्वजनिक खोज URL
`agentCard`	मेटाडेटा का वैकल्पिक सहेजा गया स्नैपशॉट
`requestSchema`, `responseSchema`	स्पष्ट दस्तावेज़ित अनुबंध, किसी एक दर्ज प्रतिक्रिया से निकाले गए अनुमान नहीं
`example`	JSON-RPC एनवेलप या सीधे REST/gRPC अनुरोध ऑब्जेक्ट

REST और gRPC

संस्करण और विधि से अलग ट्रांसपोर्ट बाइंडिंग चुनें। A2A 1.0 में JSON-RPC, REST और नेटिव gRPC समर्थित हैं। A2A 0.3 में JSON-RPC समर्थन बना रहता है; असमर्थित संयोजन चुपचाप बदलने के बजाय अस्वीकार होते हैं।

REST के लिए URL बार में बेस URL होता है, जैसे https://agent.example/rest। विधि HTTP क्रिया और पथ का प्रत्यय तय करती है। बॉडी में सीधे अनुरोध ऑब्जेक्ट संपादित करें, बिना jsonrpc, id और params एनवेलप फ़ील्ड के। टास्क पहचानकर्ता पथ खंडों के रूप में एनकोड होते हैं; फ़िल्टर और पेजिनेशन क्वेरी पैरामीटर बनते हैं। डीबगिंग और दस्तावेज़ के लिए कोड जनरेशन एक ही मैपिंग इस्तेमाल करते हैं।

नेटिव gRPC के लिए डेस्कटॉप ऐप्लिकेशन चाहिए। सिस्टम के भरोसेमंद प्रमाणपत्रों वाले TLS के लिए https://host:port, या स्थानीय बिना एन्क्रिप्शन परीक्षण के लिए http://localhost:port इस्तेमाल करें। इसमें पथ का हिस्सा नहीं होता। हेडर gRPC मेटाडेटा बनते हैं। कॉल आधिकारिक lf.a2a.v1.A2AService डिस्क्रिप्टर इस्तेमाल करती हैं, जिसमें नेस्टेड डेटा, enum और बाइनरी फ़ील्ड के लिए ProtoJSON रूपांतरण होता है। रोकें स्थानीय कॉल रद्द करता है, दूर का टास्क नहीं। इस बाइंडिंग के लिए HTTP स्क्रिप्ट, प्रॉक्सी और कस्टम TLS सेटिंग चुपचाप अनदेखी करने के बजाय अस्वीकार होती हैं।

संस्करण या बाइंडिंग बदलने पर ड्राफ़्ट सुरक्षित रहता है। अनुरोध बॉडी बनाएँ इस्तेमाल करें, टेम्पलेट जाँचें और सही संरचना लागू करने के लिए अनुरोध बॉडी बदलें की पुष्टि करें। बेमेल एनवेलप भेजने से पहले अस्वीकार होता है। खोजे गए इंटरफ़ेस स्पष्ट रूप से लागू किए जा सकते हैं; A2A अब किसी असंबंधित दस्तावेज़ सर्वर को अपने आप नहीं अपनाता।

सर्वर बनाएँ

सर्वर बनाएँ → सर्वर प्रोजेक्ट डाउनलोड करें खोलें। आर्काइव में Node 22+ प्रोजेक्ट होता है, जो एक HTTP बिज़नेस हैंडलर के ज़रिए JSON-RPC, REST और gRPC उपलब्ध कराता है, साथ में सार्वजनिक Agent Card भी। npm install चलाएँ, कम-से-कम 32 यादृच्छिक वर्णों वाला A2A_TOKEN और HANDLER_URL सेट करें, फिर npm start चलाएँ।

हैंडलर {message, contextId} प्राप्त करता है और ऐसा Message लौटाता है जिसका parts खाली न हो। डाउनलोड में कोई सीक्रेट या मौजूदा अनुरोध क्रेडेंशियल शामिल नहीं होता। बनाए गए सर्वर में पेलोड सीमा, हैंडलर की 60-सेकंड समय-सीमा, समवर्ती कॉल सीमा, बंद होते समय संसाधन सफ़ाई और SIGNING_JWK_FILE से वैकल्पिक JWS हस्ताक्षर शामिल हैं।

यह स्टेटलेस संदेश अडैप्टर है, स्वायत्त मॉडल या स्थायी टास्क इंजन नहीं। स्थायी टास्क, टास्क रद्द करना और पुश डिलीवरी के लिए कस्टम एक्ज़िक्यूटर तथा स्थायी स्टोरेज चाहिए। कार्ड पुश समर्थन घोषित नहीं करता। सार्वजनिक डिप्लॉयमेंट से पहले सार्वजनिक URL, TLS और HTTP रिवर्स प्रॉक्सी की अनुरोध-दर सीमाएँ सेट करें; कई उपयोगकर्ताओं को सेवा देने पर साझा टोकन वाली पहचान बदलें। ये आवश्यकताएँ बनाए गए README में दर्ज हैं।

हस्ताक्षर की पारस्परिक संगतता

सत्यापन A2A 1.0 के फ़ील्ड-उपस्थिति नियम और RFC 8785 कैननिकल JSON का पालन करता है, जिसमें अनिवार्य खाली स्ट्रिंग/ऐरे तथा स्पष्ट रूप से मौजूद वैकल्पिक बूलियन शामिल हैं। अनिवार्य फ़ील्ड हटाने वाले साइनर के हस्ताक्षर अस्वीकार होते हैं; नियमों के अनुरूप कैननिकलाइज़र से फिर हस्ताक्षर करें। सफल सत्यापन दिए गए सार्वजनिक कुंजी के विरुद्ध मानक फ़ील्ड प्रमाणित करता है, यह नहीं कि कोई अविश्वसनीय कुंजी घोषित संगठन की है।

संदर्भ: A2A 1.0 विनिर्देश और A2A 0.3 विनिर्देश।

चलने वाला स्थानीय उदाहरण

Powerduck React रिपॉज़िटरी में examples/a2a-demo है। Node.js 22+ के साथ उसी डायरेक्टरी में npm ci और npm start चलाएँ। एक ही स्थानीय कैलकुलेटर पर JSON-RPC, REST और डेस्कटॉप gRPC डीबग करने के लिए उसका openapi.json आयात करें। README में डेमो bearer token, Agent Card खोज, भरोसेमंद स्थानीय JWKS और स्ट्रीमिंग निर्देश हैं। npm test बाहरी सेवाओं के बिना वास्तविक ट्रांसपोर्ट और बदले हुए हस्ताक्षरों के अस्वीकार होने की जाँच करता है।

प्रोटोकॉल पैनल में अनुरोध बॉडी बनाएँ चुनी हुई विधि का टेम्पलेट दिखाता है। अनुरोध बॉडी बदलें उसे स्पष्ट रूप से लागू करता है; रद्द करने या विधि बदलने पर मौजूदा ड्राफ़्ट सुरक्षित रहता है।

cd powerduck-react/examples/a2a-demo
npm ci
npm start
# In another terminal, in the same directory:
npm test

स्थानीय एंडपॉइंट: JSON-RPC http://127.0.0.1:9999/rpc, REST http://127.0.0.1:9999/rest, gRPC http://127.0.0.1:9998। सार्वजनिक कार्ड http://127.0.0.1:9999/.well-known/agent-card.json पर है। डेमो bearer token powerduck-local-demo-token-0123456789 इस्तेमाल करें। [12,30] भेजने पर Sum: 42 और संरचित total: 42 लौटता है। भरोसेमंद सार्वजनिक कुंजी .runtime/trusted-jwks.json में है और रीस्टार्ट पर बदलती है। डेमो केवल स्थानीय कनेक्शन सुनता है, AI कुंजी नहीं माँगता, स्थायी टास्क इंजन या पुश डिलीवरी नहीं देता और डेमो टोकन के साथ सार्वजनिक रूप से डिप्लॉय नहीं किया जाना चाहिए। ब्राउज़र के डिफ़ॉल्ट ओरिजिन http://localhost:3000 और http://127.0.0.1:3000 हैं; अन्य ओरिजिन के लिए CORS_ORIGINS इस्तेमाल करें। बनाया गया सर्वर भी इसी स्पष्ट अनुमति-सूची का समर्थन करता है।

बनाना और डीबग करना​

Agent Card​

टास्क और स्ट्रीमिंग​

OpenAPI एक्सटेंशन​

REST और gRPC​

सर्वर बनाएँ​

हस्ताक्षर की पारस्परिक संगतता​

चलने वाला स्थानीय उदाहरण​