सभी विधियाँ JSON-RPC 2.0 का उपयोग करके https://www.magisterium.com/api/v1/a2a पर POST के माध्यम से कॉल की जाती हैं। हर अनुरोध में Authorization: Bearer $MAGISTERIUM_TOKEN (एक OAuth द्वारा जारी उपयोगकर्ता टोकन — प्रमाणीकरण देखें) और Content-Type: application/json शामिल होना चाहिए।

विधियाँ

message/send

एक कौशल को एक संदेश भेजें और एक पूर्ण कार्य प्राप्त करें। सभी Magisterium कौशल तुल्यकालिक हैं — प्रतिक्रिया में अंतिम कार्य स्थिति (completed या failed) होती है, कभी कोई मध्यवर्ती working स्थिति नहीं होती।

पैरामीटर:

फ़ील्ड	प्रकार	आवश्यक	विवरण
message	Message	हाँ	भागों और वैकल्पिक मेटाडेटा के साथ उपयोगकर्ता संदेश।
message.role	string	हाँ	"user" होना चाहिए।
message.messageId	string	हाँ	इस संदेश के लिए अद्वितीय ID।
message.kind	string	हाँ	"message" होना चाहिए।
message.parts	Part[]	हाँ	कम से कम एक भाग (टेक्स्ट या डेटा)।
message.metadata.skillId	string	नहीं	आमंत्रित करने के लिए कौशल। डिफ़ॉल्ट रूप से catholic_qa।
message.contextId	string	नहीं	संबंधित कार्यों को समूहित करने के लिए वैकल्पिक संदर्भ ID। यदि छोड़ दिया जाता है, तो सर्वर एक उत्पन्न करता है।
configuration	object	नहीं	भविष्य के उपयोग के लिए आरक्षित।

लौटाता है: kind: "task" के साथ एक Task ऑब्जेक्ट।

tasks/get

पहले बनाए गए किसी कार्य को उसकी ID द्वारा पुनः प्राप्त करें।

पैरामीटर:

फ़ील्ड	प्रकार	आवश्यक	विवरण
id	string	हाँ	message/send से लौटाया गया कार्य ID।

लौटाता है: Task ऑब्जेक्ट, या यदि समाप्त हो गया है या अनुपस्थित है तो TASK_NOT_FOUND त्रुटि। कार्य 24 घंटे के लिए संग्रहीत रहते हैं।

tasks/cancel

यदि यह रद्द करने योग्य स्थिति में है तो किसी कार्य को रद्द करें। चूँकि सभी कौशल तुल्यकालिक रूप से हल होते हैं, अधिकांश कार्य प्रतिक्रिया लौटने के समय पहले से ही अंतिम स्थिति (completed / failed) में होते हैं — किसी अंतिम कार्य को रद्द करने का प्रयास Invalid state transition संदेश के साथ INVALID_PARAMS लौटाता है।

पैरामीटर:

फ़ील्ड	प्रकार	आवश्यक	विवरण
id	string	हाँ	रद्द करने के लिए कार्य ID।

लौटाता है: status.state: "canceled" के साथ अद्यतन Task ऑब्जेक्ट।

कार्य जीवनचक्र

Magisterium के कौशल तुल्यकालिक रूप से चलते हैं, इसलिए कार्य कौशल समाप्त होने के बाद ही संग्रहण में सहेजा जाता है — हमेशा एक अंतिम स्थिति में। submitted और working स्थितियाँ व्यापक A2A विनिर्देश का हिस्सा हैं, लेकिन Magisterium के कार्यान्वयन द्वारा कभी उत्पन्न नहीं होतीं; आप नीचे दी गई तीन अंतिम स्थितियों में से केवल एक ही देखेंगे।

स्थिति	अर्थ
completed	अंतिम — परिणाम artifacts में हैं। कौशल के सफलतापूर्वक समाप्त होने पर message/send द्वारा लौटाया जाता है।
failed	अंतिम — status.message में विफलता का कारण होता है। कौशल द्वारा अपवाद फेंके जाने पर message/send द्वारा लौटाया जाता है।
canceled	अंतिम — केवल किसी गैर-अंतिम कार्य पर tasks/cancel कॉल करके पहुँचा जा सकता है। चूँकि message/send के लौटने तक कार्य पहले से ही अंतिम स्थिति में होते हैं, व्यवहार में आपके पास मौजूद किसी भी कार्य के लिए रद्दीकरण INVALID_PARAMS के साथ अस्वीकृत कर दिया जाता है।

प्रत्येक कार्य यह भी ले जाता है:

• contextId — एक समूहीकरण पहचानकर्ता जिसे आप संबंधित कार्यों को जोड़ने के लिए अनुवर्ती संदेशों में पुनः उपयोग कर सकते हैं।
• history — उपयोगकर्ता और एजेंट संदेशों की क्रमबद्ध सूची जिसने कार्य की कलाकृतियों का निर्माण किया।

त्रुटि कोड

कोड	नाम	विवरण
-32700	Parse error	अमान्य JSON बॉडी।
-32600	Invalid request	jsonrpc, method, या id फ़ील्ड गायब हैं।
-32601	Method not found	अज्ञात JSON-RPC विधि।
-32602	Invalid params	गायब या अमान्य पैरामीटर (अमान्य tasks/cancel स्थिति संक्रमणों के लिए भी लौटाया जाता है)।
-32603	Internal error	अप्रत्याशित सर्वर-साइड विफलता।
-32001	Task not found	कार्य ID मौजूद नहीं है या समाप्त हो गया है।
-32002	Skill not found	संदेश मेटाडेटा में अज्ञात skillId।
-32003	Rate limit exceeded	बहुत अधिक अनुरोध। त्रुटि के data में retryAfter (सेकंड) जाँचें।
-32004	Unauthorized	गायब या अमान्य Bearer टोकन।
-32005	Paid plan required	A2A के लिए Pro, Organization, या Enterprise योजना आवश्यक है।

HTTP स्थिति त्रुटि वर्ग को दर्शाती है: UNAUTHORIZED के लिए 401, PLAN_REQUIRED के लिए 403, RATE_LIMITED के लिए 429, और अन्य सभी JSON-RPC त्रुटियों के लिए 200 (JSON-RPC सम्मेलन के अनुसार error बॉडी के साथ 200 लौटाना)।

रेट सीमाएँ

A2A MCP के साथ समान रेट-लिमिट पूल साझा करता है — प्रति-योजना अनुरोध सीमाओं के लिए MCP मूल्य निर्धारण देखें।

दो वेरिएंट लागू किए जाते हैं:

• डिफ़ॉल्ट — document_search, document_fetch, liturgical_readings, और saints_of_the_day पर लागू होता है।
• महंगा — केवल catholic_qa पर लागू होता है, क्योंकि यह LLM-समर्थित उत्तर पाइपलाइन चलाता है। यह वेरिएंट एक सख्त, निम्न सीमा का उपयोग करता है।

जब आप किसी सीमा पर पहुँचते हैं, तो त्रुटि के data ऑब्जेक्ट में सेकंड में retryAfter होता है। कॉलरों को पुनः प्रयास करने से पहले उस अंतराल के लिए बैक ऑफ करना चाहिए।

CORS

एंडपॉइंट OPTIONS प्रीफ्लाइट अनुरोधों का जवाब देता है और अनुमेय CORS हेडर लौटाता है (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), ताकि A2A को एक प्रॉक्सी के बिना ब्राउज़र-आधारित ऑर्केस्ट्रेटर से कॉल किया जा सके।