सगळ्यो पद्दती JSON-RPC 2.0 वापरून https://www.magisterium.com/api/v1/a2a-क POST वरवीं कॉल करतात. दरेक विनंतींत Authorization: Bearer $MAGISTERIUM_TOKEN (एक OAuth-न जारी केल्लो वापरकर्ता टोकन — प्रमाणीकरण पळयात) आनी Content-Type: application/json घालप गरजेचें.

पद्दती

message/send

एका कौशल्यांक संदेश धाडात आनी पुराय जाल्लें कार्य मेळयात. सगळीं Magisterium कौशल्यां synchronous आसात — प्रतिसादांत टर्मिनल कार्य स्थिती (completed वा failed) आसता, कोणतेच मदलें working status ना.

Params:

field	प्रकार	गरजेचें	वर्णन
message	Message	हय	भागांसयत आनी ऐच्छिक metadata सयत वापरकर्ता संदेश.
message.role	string	हय	"user" आसप गरजेचें.
message.messageId	string	हय	ह्या संदेशाखातीर वेगळो ID.
message.kind	string	हय	"message" आसप गरजेचें.
message.parts	Part[]	हय	किमान एक भाग (text वा data).
message.metadata.skillId	string	ना	आवाहन करूंक जाय तें कौशल्य. डीफॉल्ट catholic_qa.
message.contextId	string	ना	संबंधित कार्यां एकठांय करपाखातीर ऐच्छिक संदर्भ ID. जर सोडल्यार, सर्व्हर एक तयार करता.
configuration	object	ना	फुडल्या वापराखातीर राखीव.

परत करता: kind: "task" सयत एक Task ऑब्जेक्ट.

tasks/get

पयलीं तयार केल्लें कार्य त्याच्या ID वरवीं मेळयात.

Params:

field	प्रकार	गरजेचें	वर्णन
id	string	हय	message/send-थावन परत आयिल्लो कार्य ID.

परत करता: Task ऑब्जेक्ट, वा जर काळ संपिल्लो वा उण्णो आसल्यार TASK_NOT_FOUND त्रुटी. कार्यां 24 वरांखातीर सांठयतात.

tasks/cancel

कार्य रद्द करूं शकचें अशा स्थितींत आसल्यार तें रद्द करात. सगळीं कौशल्यां synchronous रितीन सोडयतात म्हणून, प्रतिसाद परत येवपाचो वेळ जाता म्हत्तर बरीच कार्यां पयलींच टर्मिनल स्थितींत (completed / failed) आसतात — टर्मिनल कार्य रद्द करपाचो प्रयत्न Invalid state transition संदेशासयत INVALID_PARAMS परत करता.

Params:

field	प्रकार	गरजेचें	वर्णन
id	string	हय	रद्द करपाखातीर कार्य ID.

परत करता: status.state: "canceled" सयत अद्ययावत Task ऑब्जेक्ट.

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

Magisterium-ची कौशल्यां synchronous रितीन चलतात, देखून कौशल्य सोपलें उपरांतच कार्य storage-त सांचयतात — सदांच एका terminal अवस्थेंत. submitted आनी working अवस्था व्हड्ल्या A2A specification-चो वांटो आसात, पूण Magisterium-च्या implementation-कडल्यान त्यो केन्नाच निर्माण जायनात; तुमी सकयल्या तीन terminal अवस्थांतल्यान फकत एकच पळयतले.

स्थिती	अर्थ
completed	टर्मिनल — निकाल artifacts-त आसतात. कौशल्य यशस्वीपणान सोपतकीच message/send हाणें परत दिता.
failed	टर्मिनल — status.message-त अपयशाचें कारण आसता. कौशल्यान exception उडयल्यार message/send हाणें परत दिता.
canceled	टर्मिनल — फकत terminal न्हय अशा कार्याचेर tasks/cancel आपोवन पावूं येता. message/send परतून येतकीच कार्यां पयलींच terminal अवस्थेंत आसतात देखून, प्रत्यक्षांत तुमचे कडेन हँडल आशिल्ल्या खंयच्याय कार्याखातीर रद्दकरण INVALID_PARAMS कडेन न्हयकारतात.

दरेक कार्य हें ही व्हरता:

• contextId — संबंधित कार्यां जोडूंक follow-up संदेशांनी परत वापरूंक शकचो एक गटीकरण ओळख-चिन्न.
• history — कार्याच्या artifacts तयार करूंक दिल्ल्या वापरकर्ता आनी एजंट संदेशांची क्रमवार वळेरी.

त्रुटी कोड

कोड	नांव	वर्णन
-32700	Parse error	अवैध JSON body.
-32600	Invalid request	jsonrpc, method, वा id fields उण्णे.
-32601	Method not found	अज्ञात JSON-RPC पद्दत.
-32602	Invalid params	उण्णे वा अवैध पॅरामीटर (अवैध tasks/cancel state transitions खातीर लेगित परत करता).
-32603	Internal error	अपेक्षित न्हय अशें सर्व्हर-साइड अपयश.
-32001	Task not found	कार्य ID आसना वा काळ संपिल्लो.
-32002	Skill not found	संदेश metadata-त अज्ञात skillId.
-32003	Rate limit exceeded	जास्त विनंत्यो. त्रुटीच्या data-त retryAfter (सेकंद) तपासात.
-32004	Unauthorized	उण्णो वा अवैध Bearer टोकन.
-32005	Paid plan required	A2A-क Pro, Organization, वा Enterprise प्लॅन गरजेचें.

HTTP status त्रुटी वर्गाचें प्रतिबिंब करता: UNAUTHORIZED-खातीर 401, PLAN_REQUIRED-खातीर 403, RATE_LIMITED-खातीर 429, आनी हेर सगळ्या JSON-RPC त्रुटींखातीर 200 (JSON-RPC परंपरे प्रमाण error body सयत 200 परत करप).

रेट सीमा

A2A MCP सयत तोच rate-limit pool वांट्टा — per-plan विनंती सीमांखातीर MCP किमती पळयात.

दोन variants अंमलांत हाडले:

• डीफॉल्ट — document_search, document_fetch, liturgical_readings, आनी saints_of_the_day-क लागू.
• खर्चिक — फकत catholic_qa-क लागू, कारण तें LLM-आदारित उत्तर pipeline चलयता. हो variant एक कडक, कमी सीमा वापरता.

जेन्ना तुमी एका सीमेच्यार पावता, त्रुटीच्या data ऑब्जेक्टांत सेकंदांत retryAfter आसता. कॉलरांनी परत प्रयत्न करच्यापयलीं त्या अंतराखातीर back off करूंक जाय.

CORS

एंडपॉइंट OPTIONS preflight विनंत्यांक प्रतिसाद दिता आनी अनुमतीचे CORS हेडर परत करता (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), म्हूण A2A एका proxy-शिवाय browser-आदारित orchestrators-थावन कॉल करूं शकता.