تكامل Agent MCP الخارجي

استخدم Manager AGI Agents كأدوات MCP من تطبيق خادم موثوق. يشرح هذا الدليل الإعداد والمصادقة وتفويض الخدمات التابعة والاستدعاء والاستعادة وعقد الأخطاء المستقر.

البدء السريع

أنشئ تطبيق طرف ثالث نشطًا في Web Admin، واربطه بشركة، ثم انسخ App ID وApp Secret.
عيّن للشركة Agent مفعّلًا وله Skills منشورة وفعّالة.
صِل عميل MCP Streamable HTTP بالمسار POST|GET|DELETE /openapi/v1/agents/mcp على مضيف Engine عبر HTTPS.
هيّئ الجلسة، وأرسل notifications/initialized، ثم tools/list، وبعدها استدعِ agent_{id}.

لا يُنشر المساعد العام. احتفظ بالسر داخل الخادم فقط.

المصادقة ونطاق الصلاحية

بيئات API:

الاختبار: https://aim-api-test.proton-system.com
الإنتاج: https://aim-api.proton-system.com

يجب أن يحتوي كل طلب على الترويسات التالية:

Authorization: Basic Base64(KEY:SECRET)
Content-Type: application/json
Accept: application/json, text/event-stream

يمكن لعميل MCP بعيد يدعم ترويسات الطلب المخصصة استخدام الإعداد التالي:

{
  "mcpServers": {
    "manager-agi": {
      "url": "https://xxx.com/openapi/v1/agents/mcp",
      "headers": {
        "Authorization": "Basic <Base64(AppID:AppSecret)>"
      }
    }
  }
}

يحصل التطبيق النشط على موافقة دائمة ضمن نطاق الشركة. تصبح Agents المعيّنة حاليًا أو مستقبلًا وSkills المنشورة الجديدة متاحة دون موافقة بشرية، بما في ذلك الكتابة والعمليات عالية المخاطر. لا يقيّد CompanyRole هذه الصلاحية. يواصل Engine فحص الحالات والتعيين والنشر وتفويض الخدمات التابعة وانحراف المخطط/المخاطر والتحقق والحدود والتكرار الآمن والتدقيق.

التهيئة والجلسة

هيّئ العميل واحفظ ترويسة الاستجابة Mcp-Session-Id:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"partner-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized"}

أرسل Mcp-Session-Id مع طلبات POST وGET وDELETE اللاحقة. أعد التهيئة بعد INVALID_MCP_SESSION.

أدوات Agent والبيانات الوصفية

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

اسم الأداة هو agent_{id}، ويأتي بعد البادئة معرّف Agent الكامل. قيمة title العليا هي اسم Agent، ويستخدم الوصف وصف Agent أو الاسم عند فراغه. يعرض _meta.easyposAgent فقط الحقول العامة id وname وdescription وiconUrl. يحتوي authorizationRequirements على mcpHubId وmcpHubName وauthType وstatus وexpiresAt وauthorized، وعند الحاجة رابط authorizationUrl الذي ينشئه Engine. لا تُعرض prompts أو الأسئلة السريعة أو تعريفات Skills أو المخططات الداخلية أو بيانات الاعتماد.

تفويض الخدمات التابعة

عندما تكون status هي MISSING أو REAUTH_REQUIRED، افتح authorizationUrl الذي ينشئه Engine ويبدأ مساره بـ /openapi/v1/mcp/authorization/start. بعد إكمال المستخدم للتفويض، أعد محاولة tools/list أو استدعاء tools/call الأصلي؛ تعني ACTIVE أن Engine يستطيع التنفيذ بالتفويض المحفوظ للتطبيق. يتطلب انتهاء الصلاحية أو استجابة 401 تكرار المسار نفسه. لا تجدّد الرموز ولا ترسل ترويسات للخدمة التابعة ولا تعِد تنفيذ العملية الفاشلة تلقائيًا.

استدعاء Agent

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"لخّص الطلبات المفتوحة اليوم","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId مطلوب، تُزال مسافاته الطرفية، وحده 128 بايت UTF-8. message مطلوب وحده 16 KiB. conversationId اختياري ولا يعاد استخدامه إلا من التطبيق والشركة وAgent نفسها. يفعّل _meta.progressToken إشعارات تقدم MCP القياسية.

تتضمن النتيجة الناجحة "status":"COMPLETED" و"answer" وrequestId وconversationId والبيانات الوصفية وauthorizationRequirements. عند غياب بيانات التفويض التابعة تعود isError:true وstatus:"authorization_required" وerrorCode:"MCP_AUTHORIZATION_REQUIRED" دون إنشاء تنفيذ.

SSE والاستئناف والإلغاء والإغلاق

استقبل تقدم MCP ونتيجة نهائية واحدة. لاستعادة stream، نفّذ GET مصادقًا مع Mcp-Session-Id والمؤشر المعتم Last-Event-ID وEasyPOS-Agent-Request-Id وEasyPOS-Agent-Id وAccept: text/event-stream. لا تعيد الاستعادة تشغيل Agent؛ كرر GET بالمؤشر الجديد إذا بقيت أحداث.

لا يفعل إلغاء MCP الصريح أكثر من طلب الإلغاء، ولا يعكس الآثار التي أُرسلت. لا يؤدي transport disconnect إلى إلغاء عمل مقبول. أغلق الجلسة بطلب DELETE مصادق مع Mcp-Session-Id.

الحدود والتكرار الآمن

الحد	العقد
الإدخال	`requestId` ‏128 bytes؛ `message` ‏16 KiB؛ POST ‏256 KiB
الاستدعاءات	لا يفرض Agent MCP حدًا لمعدل الاستدعاء؛ وتظل قيود lease والتكرار الآمن وحجم الإدخال سارية
الاحتفاظ	التكرار والاستعادة لمدة 90 يومًا
الأحداث	تخزين 256 وإرجاع 64 في كل GET

يكون requestId آمن التكرار داخل التطبيق لمدة 90 يومًا. يعيد الإدخال نفسه النتيجة دون وحدة تنفيذ جديدة؛ يعطي الإدخال المختلف IDEMPOTENCY_CONFLICT وقد يعطي الطلب الجاري REQUEST_IN_PROGRESS.

عقد الأخطاء

تستخدم أخطاء النقل HTTP وJSON مثل {"code":"COMPANY_INACTIVE","description":"The company is inactive."}. تستخدم أخطاء MCP/المجال isError:true وerrorCode وerrorDescription. الوصف نص إنجليزي ثابت وغير حساس؛ ابنِ منطق البرنامج على الرمز.

الرمز	الوصف المُعاد
`INVALID_APP_CREDENTIALS`	The application credentials are missing or invalid.
`APPLICATION_INACTIVE`	The third-party application is inactive.
`COMPANY_INACTIVE`	The company is inactive.
`AGENT_NOT_FOUND`	The Agent does not exist.
`AGENT_NOT_ASSIGNED`	The Agent is not assigned to this company.
`AGENT_DISABLED`	The Agent is disabled.
`INVALID_AGENT_REQUEST`	The Agent request input is missing or exceeds the supported limits.
`CONVERSATION_BUSY`	The conversation already has an active execution.
`CONVERSATION_SCOPE_MISMATCH`	The conversation does not belong to this application, company, or Agent.
`MCP_AUTHORIZATION_REQUIRED`	Required downstream MCP authorization is missing.
`MCP_AUTHORIZATION_EXPIRED`	The downstream MCP authorization has expired.
`INVALID_MCP_SESSION`	The MCP session is missing, invalid, expired, or outside the application scope.
`EVENT_CURSOR_SCOPE_MISMATCH`	The event cursor does not belong to the requested application, Agent, or request scope.
`EVENT_REPLAY_UNAVAILABLE`	The requested event replay is no longer available.
`ORIGIN_NOT_ALLOWED`	The request origin is not allowed for this application.
`IDEMPOTENCY_CONFLICT`	The requestId was already used with different input.
`REQUEST_IN_PROGRESS`	The idempotent request is still in progress.
`SCHEMA_OR_RISK_DRIFT`	A Tool schema or execution-risk change requires refreshed metadata.
`REQUEST_CANCELLED`	The Agent request was cancelled or exceeded its deadline.
`AGENT_REQUEST_FAILED`	The previously recorded Agent request failed.
`AGENT_EXECUTION_FAILED`	The Agent execution failed without a safe public detail.

الأمان واستكشاف المشكلات

استخدم TLS ومدير أسرار واحذف ترويسات التفويض من السجلات. لا تضع App Secret في المتصفح أو الهاتف أو URL أو المستودع. ينبغي لعميل الخادم حذف Origin؛ وإن أرسله فيجب أن يكون ضمن أصول HTTPS المسموح بها. عند الاشتباه بتسريب عطّل التطبيق أو أعد ضبط Secret.

إذا كانت tools/list فارغة، فتحقق من الشركة وAgent والتعيين وSkills المنشورة. عند طلب التفويض افتح authorizationUrl ثم أعد محاولة الاكتشاف أو الاستدعاء بعد اكتماله، وأعد تهيئة الجلسة غير الصالحة. لا يُستخدم callbackUrl الخاص بالإشعارات لنتائج Agent؛ اقرأ النتائج من MCP/SSE.