مكّن وكلاء الذكاء الاصطناعي الخاصين بك من اكتشاف الماجستير والتواصل معه وتفويض المهام إليه باستخدام بروتوكول A2A (Agent-to-Agent) المفتوح.

لماذا A2A؟

بينما يتيح MCP لأدوات الذكاء الاصطناعي الوصول إلى معرفة الماجستير، يتيح A2A لوكلاء الذكاء الاصطناعي التعاون مع الماجستير كنظير. يمكن لوكيل منسق اكتشاف قدرات الماجستير، وإرسال المهام إليه، وتلقي نتائج منظمة — كل ذلك عبر واجهة JSON-RPC قياسية.

مطلوبة خطة مدفوعة. نقطة نهاية A2A متاحة على خطط Pro وOrganization وEnterprise. تتلقى الحسابات المجانية خطأ PLAN_REQUIRED (-32005). راجع تسعير MCP للاطلاع على حدود الخطط الحالية — يشترك A2A في نفس مجموعة حدود المعدل.

اكتشاف الوكيل

ينشر الماجستير بطاقة وكيل عامة على:

https://www.magisterium.com/.well-known/agent.json

هكذا يكتشف الوكلاء الخارجيون المهارات المتاحة، ومتطلبات المصادقة، وعنوان نقطة نهاية A2A. تتبع البطاقة مواصفات A2A ولا تتطلب أي مصادقة لجلبها.

curl https://www.magisterium.com/.well-known/agent.json

نقطة نهاية A2A

نقطة نهاية JSON-RPC لجميع عمليات A2A هي:

https://www.magisterium.com/api/v1/a2a

جميع الطلبات تستخدم POST مع رأس Content-Type: application/json وغلاف JSON-RPC 2.0 القياسي.

القدرات

تعلن بطاقة الوكيل عن القدرات التالية:

المصادقة

يستخدم A2A نفس مصادقة رمز مستخدم OAuth 2.0 المستخدمة في خادم MCP للماجستير. يجب أن يكون لديك حساب على magisterium.com لاستدعاء نقطة نهاية A2A.

ينشر الماجستير بيانات OAuth 2.0 الوصفية على https://www.magisterium.com/.well-known/oauth-authorization-server، بما في ذلك نقطة نهاية التفويض، ونقطة نهاية الرمز المميز، ونقطة نهاية تسجيل العميل الديناميكي. يمكن للعملاء الذين يطبقون تدفق OAuth 2.0 Authorization Code (مع PKCE) الحصول على رمز وصول من هذه البيانات الوصفية؛ راجع مستندات مصادقة MCP للإعداد القياسي على جانب العميل.

بمجرد حصولك على رمز وصول، قم بتضمينه في رأس Authorization لكل طلب A2A:

Authorization: Bearer $MAGISTERIUM_TOKEN

مفاتيح API طويلة العمر التي يتم إنشاؤها في وحدة تحكم API مخصصة لنقاط نهاية Chat Completions وSearch وNews فقط — لن تصادق ضد A2A. استخدم رمز مستخدم صادر عن OAuth بدلاً من ذلك.

تُرجع الرموز المفقودة أو غير الصالحة خطأ UNAUTHORIZED (-32004).

مثال سريع

أرسل سؤالاً إلى مهارة catholic_qa:

curl -X POST https://www.magisterium.com/api/v1/a2a \
    -H "Authorization: Bearer $MAGISTERIUM_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "role": "user",
          "messageId": "msg-001",
          "kind": "message",
          "parts": [{ "kind": "text", "text": "What does the Church teach about the Real Presence?" }],
          "metadata": { "skillId": "catholic_qa" }
        }
      }
    }'

تكون الاستجابة مهمة Task مكتملة تحتوي على الإجابة والاقتباسات داخل result.artifacts:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task_abc123",
    "contextId": "ctx_def456",
    "kind": "task",
    "status": { "state": "completed", "timestamp": "2026-04-20T12:00:00.000Z" },
    "artifacts": [
      {
        "artifactId": "art_ghi789",
        "name": "catholic_qa_response",
        "parts": [
          { "kind": "text", "text": "The Catholic Church teaches..." },
          { "kind": "data", "data": { "citations": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

الخطوات التالية

• البدء — اطّلع على أول طلب A2A لك باستخدام curl وPython وTypeScript.
• المهارات — القائمة الكاملة للمهارات المعروضة عبر A2A، مع أشكال الإدخال والإخراج لكل مهارة.
• مرجع API — طرق JSON-RPC، ورموز الأخطاء، ودورة حياة المهام.