إنتقل إلى المحتوى الرئيسي

أدوات ربط نظامك

تتيح أداة ربط نظامك لذكاء الوكيل الاصطناعي أن يستدعي نظامك الخاص في منتصف المحادثة: ليتحقّق من طلب، أو يبحث عن المخزون، أو يؤكّد حجزاً. هي أداة ربط نظامك (Custom API) في لوحة التحكم، لكن عبر الواجهة البرمجية، فيستطيع تكامل أو مساعد ذكاء اصطناعي إعدادها لك. كل ذلك تحت /v1/agents/{agentId}/custom-api-tools. وربط نظامك متاح في الباقات المدفوعة؛ أما في الباقة المجانية فكل استدعاء هنا يُعيد 403 feature_not_available.

كيف تعمل الأداة؟​

الأداة طلب واحد يجيب عنه نظامك، يُكتب رابطاً فيه متغيّر {{name}} لكل ما يملؤه الذكاء الاصطناعي، ومعه when_to_use الذي يخبر الذكاء الاصطناعي متى يستدعيها. حين يسأل العميل عن شيء تجيب عنه الأداة، يملأ الذكاء الاصطناعي المدخلات من المحادثة، ويستدعي مجيب رابطك، ويرد الذكاء الاصطناعي من جواب نظامك. ولا يستخدم الذكاء الاصطناعي إلا أداة مفعّلة، ولا تُفعَّل الأداة إلا بعد اختبار ناجح.

كيف أضيف أداة؟​

أرسل الأداة بـ POST. تبدأ متوقفة.

curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/custom-api-tools \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order status",
    "when_to_use": "When the customer asks where their order is.",
    "method": "GET",
    "url": "https://api.yourshop.com/orders/{{order_id}}",
    "inputs": [{ "name": "order_id", "description": "The order number the customer gives", "required": true }],
    "login": { "type": "api_key", "location": "header", "name": "X-API-Key", "api_key": "YOUR_SHOP_KEY" }
  }'

كل الحقول وأنواع تسجيل الدخول والحدود في مرجع إضافة أداة ربط نظامك. اكتب when_to_use كما تشرح لزميل: فالذكاء الاصطناعي يقرؤه ليقرّر متى يستدعي الأداة. ويُتحقَّق من كل شيء قبل أن يُحفظ أي شيء: فالقاعدة المكسورة تُعيد 422 invalid_request، مع الحقل في param وجملة توضّح ما يجب تغييره، ولا تغيّر شيئاً.

كيف أختبرها وأشغّلها؟​

اختبرها بقيمة تجريبية لكل مُدخل:

curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/custom-api-tools/TOOL_ID/test \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "inputs": { "order_id": "1042" } }'

الاختبار استدعاء حقيقي واحد لنظامك، دون الذكاء الاصطناعي (واثنان لأداة كتابة على موقع يحتاج CSRF token). تقول passed كيف جرى، وتعرض response ما أجاب به نظامك مقتطَعاً عند الطول المذكور في مرجع اختبار أداة ربط نظامك (والذكاء الاصطناعي يقرأ منه أكثر)، لتتأكّد أنه يحمل ما يحتاجه الذكاء الاصطناعي. وبعد نجاح الاختبار، شغّل الأداة بطلب PATCH لا يحمل إلا "active": true. وأي تغيير لاحق في الطلب (الطريقة أو الرابط أو الترويسات أو صيغة الجسم أو الجسم أو المدخلات) يحتاج إلى اختبار ناجح جديد قبل أن تُشغَّل الأداة مرة أخرى؛ أما الأداة المفعّلة أصلاً فتبقى مفعّلة.

كيف يعمل تسجيل الدخول؟​

تسجيل الدخول للموقع، وتسمّيه لوحة التحكم الدومين: كل أداة يبدأ رابطها بعنوان تسجيل دخول، مثل https://api.yourshop.com، تستخدم ذلك التسجيل.

  • موقع جديد يأخذ login الذي ترسله مع أول أداة عليه، أو لا تسجيل دخول إن لم ترسله.
  • موقع لديك تسجيل دخول له يستخدمه: لا ترسل login.
  • تغيير تسجيل دخول تستخدمه أدوات أخرى يغيّره لها كلها، لذا يحتاج أيضاً إلى "change_shared_login": true، وإلا فالرد 409 login_shared؛ وإرسال سرّ يُعدّ تغييراً.
  • مفتاح مقيّد ببعض الوكلاء لا يستطيع أن يضيف أداة إلى تسجيل دخول أو يغيّره إلا إذا كان يستطيع العمل على كل وكيل تستخدمه أدواته، وإلا فالرد 403 shared_with_other_agents.

يحلّ login الذي ترسله محلّ إعدادات التسجيل المحفوظ كلها، لذا أرسل كل إعداد تريد إبقاءه. والمفتاح أو الرمز أو كلمة المرور أو سرّ العميل للكتابة فقط: إن تركته بقي المحفوظ، لكنه لا يذهب أبداً إلى مكان جديد. فنقل تسجيل الدخول إلى موقع آخر، أو نقل تسجيل OAuth إلى رابط رمز أو عميل أو client_auth آخر، يحتاج إلى إرسال السرّ مجدداً. قراءة الأداة تُظهر نوع تسجيل الدخول وإعداداته، وهل خُزّن سرّ (has_secret)، وكم أداة تستخدمه (used_by_tools)، ولا تُظهر السرّ أبداً. ضع المفاتيح في login، لا في headers أو الجسم، لتبقى مشفّرة ولا تعود أبداً.

كيف أعرف أداء الأداة؟​

اعرض سجل تشغيلها: المرات التي استخدمها فيها الذكاء الاصطناعي، الأحدث أولاً، مع كيف جرت كل مرة وكم استغرقت والمحادثة. ولا يظهر أبداً ما أُرسل أو استُقبل.

curl https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/custom-api-tools/TOOL_ID/runs \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

وتصبح login.status في الأداة requires_reauth حين يتعذّر على مجيب استخدام تسجيل الدخول (سرّ ناقص، أو رفض رابط الرمز لديك العميل)، وerror حين يتعذّر الوصول إلى نظامك. أما ردّ نظامك على استدعاء بخطأ، مثل 401، فيظهر في سجل التشغيل لا في الحالة. راجع مرجع عرض سجل تشغيل أداة ربط نظامك.

أسئلة شائعة​

هل يمكن وضع متغيّر في جزء الموقع من الرابط؟​

لا. الموقع يحدّد تسجيل الدخول، لذا لا يحمل المتغيّرات إلا المسار والاستعلام. وللسبب نفسه لا تنتقل الأداة إلى موقع آخر: أنشئ أداة جديدة له.

كم اختباراً أستطيع تشغيله؟​

تستطيع شركتك تشغيل 30 اختباراً في الدقيقة، عبر مفاتيحها ولوحة التحكم معاً. وبعد ذلك يكون الرد 429 test_rate_limited؛ أعد المحاولة بعد Retry-After الخاص به. ويُحتسب الاختبار أيضاً من حد طلبات مفتاحك؛ راجع حدود المعدّل.

هل يتحقّق مجيب ممن يسأل قبل أن يستدعي نظامي؟​

لا. يرسل مجيب الطلب بتسجيل دخولك كما هو، فنظامك هو من يقرّر من يرى ماذا. وإن كانت أداة تبحث برقم هاتف أو رقم طلب، فاجعل نظامك يتحقّق من أن الطلب منطقي بدل الاعتماد على الذكاء الاصطناعي.

أي روابط تستطيع الأداة استدعاءها؟​

روابط https لمواقع عامة فقط، ولا تستدعي أبداً عنواناً خاصاً أو داخلياً. ويتحقّق مجيب من العنوان مجدداً في كل استدعاء.

هل هي الأدوات نفسها التي في لوحة التحكم؟​

نعم. الأداة المضافة عبر الواجهة البرمجية تظهر في صفحة أدوات الوكيل في لوحة التحكم، والأداة المبنية في لوحة التحكم تُقرأ وتُغيَّر عبر الواجهة البرمجية. وقد ترسل أداة لوحة التحكم قيماً ثابتة أيضاً: لا تظهر في inputs، وإرسال inputs يبقيها كما هي.

هل يعمل مع نظام يحتاج إلى CSRF token، مثل SAP؟​

نعم، متى شُغّل لتسجيل دخول الموقع: شغّل السيرفر محتاج CSRF token قبل أي كتابة (SAP, OData) في لوحة التحكم، تحت الحماية ← إعدادات متقدمة في أي أداة على ذلك الموقع؛ راجع ربط نظامك. عندها تجلب كل أداة POST أو PUT أو PATCH أو DELETE على الموقع توكناً أولاً، ومنها الأدوات التي تضيفها عبر الواجهة البرمجية. ولا تستطيع الواجهة البرمجية تشغيله ولا عرضه بعد، وإرسال login يبقيه كما هو. ويحمل طلب التوكن قيم الهيدرز والاستعلام المكتوبة في الأداة كما هي، مثل sap-client=100، ولا يحمل أبداً ما يُكتب متغيّراً {{placeholder}}، ومن ذلك القيم الثابتة لأداة لوحة التحكم. وحين يتعذّر جلب التوكن يبدأ error في الاختبار بـ csrf:؛ راجع مرجع اختبار أداة ربط نظامك.

أي باقة أحتاج؟​

ربط نظامك ومفتاح API الذي تحتاجه هذه الاستدعاءات متاحان معًا في كل الباقات المدفوعة؛ راجع التوثيق. وفي باقة لا تشمل ربط نظامك يُعيد كل استدعاء هنا 403 feature_not_available. راجع الخطط والأسعار.

ما النطاقات التي تحتاجها هذه الاستدعاءات؟​

custom_api:read لعرض الأدوات وقراءتها وقراءة سجل تشغيلها، وcustom_api:write لإضافتها وتغييرها واختبارها وتشغيلها وحذفها. ويحمل كل مفتاح الاثنين اليوم؛ راجع التوثيق.