يتم استدعاء جميع الطرق عبر POST إلى https://www.magisterium.com/api/v1/a2a باستخدام JSON-RPC 2.0. يجب أن يتضمن كل طلب Authorization: Bearer $MAGISTERIUM_TOKEN (رمز مستخدم صادر عن OAuth — راجع المصادقة) وContent-Type: application/json.

الطرق

message/send

أرسل رسالة إلى مهارة واستقبل مهمة مكتملة. جميع مهارات الماجستير متزامنة — تحتوي الاستجابة على حالة المهمة النهائية (completed أو failed)، وليس حالة working وسيطة أبداً.

المعلمات:

الحقل	النوع	مطلوب	الوصف
message	Message	نعم	رسالة المستخدم مع الأجزاء والبيانات الوصفية الاختيارية.
message.role	string	نعم	يجب أن يكون "user".
message.messageId	string	نعم	معرف فريد لهذه الرسالة.
message.kind	string	نعم	يجب أن يكون "message".
message.parts	Part[]	نعم	جزء واحد على الأقل (نص أو بيانات).
message.metadata.skillId	string	لا	المهارة المراد استدعاؤها. الافتراضي هو catholic_qa.
message.contextId	string	لا	معرف سياق اختياري لتجميع المهام ذات الصلة. إذا تم حذفه، يقوم الخادم بإنشاء واحد.
configuration	object	لا	محجوز للاستخدام المستقبلي.

يُرجع: كائن Task مع kind: "task".

tasks/get

استرداد مهمة تم إنشاؤها مسبقاً بواسطة معرفها.

المعلمات:

الحقل	النوع	مطلوب	الوصف
id	string	نعم	معرف المهمة الذي تم إرجاعه من message/send.

يُرجع: كائن Task، أو خطأ TASK_NOT_FOUND إذا انتهت صلاحيته أو كان مفقوداً. يتم تخزين المهام لمدة 24 ساعة.

tasks/cancel

إلغاء مهمة إذا كانت في حالة قابلة للإلغاء. لأن جميع المهارات تُحل بشكل متزامن، فإن معظم المهام تكون بالفعل في حالة نهائية (completed / failed) بحلول وقت إرجاع الاستجابة — محاولة إلغاء مهمة نهائية تُرجع INVALID_PARAMS برسالة Invalid state transition.

المعلمات:

الحقل	النوع	مطلوب	الوصف
id	string	نعم	معرف المهمة المراد إلغاؤها.

يُرجع: كائن Task المحدّث مع status.state: "canceled".

دورة حياة المهمة

تعمل مهارات 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	معرف المهمة غير موجود أو انتهت صلاحيته.
-32002	Skill not found	skillId غير معروف في بيانات تعريف الرسالة.
-32003	Rate limit exceeded	طلبات كثيرة جداً. تحقق من retryAfter (بالثواني) في data الخطأ.
-32004	Unauthorized	رمز Bearer مفقود أو غير صالح.
-32005	Paid plan required	يتطلب A2A خطة Pro أو Organization أو Enterprise.

تعكس حالة HTTP فئة الخطأ: 401 لـ UNAUTHORIZED، و403 لـ PLAN_REQUIRED، و429 لـ RATE_LIMITED، و200 لجميع أخطاء JSON-RPC الأخرى (وفقاً لاتفاقية JSON-RPC بإرجاع 200 مع متن error).

حدود المعدل

يشترك 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 من المنسقات المستندة إلى المتصفح دون وكيل.