API

الأدوات المخصّصة

دع الذكاء الاصطناعي يستدعي الـ API الخاصة بك في منتصف المحادثة

نظرة عامة

الأداة المخصّصة نقطة نهاية لديك يستطيع الوكيل استدعاءها وهو يتحدث مع عميل: الاستعلام عن قرض برقم الهوية، أو مراجعة المخزون، أو فتح تذكرة. أنت تصف متى تنطبق وما المعاملات التي تحتاجها؛ والذكاء الاصطناعي يقرر متى يستدعيها، ويملأ المعاملات بما قاله العميل، ويرد بما أرجعته الـ API الخاصة بك. حتى 15 أداة لكل وكيل.

التعريف

كل أداة مدخل بهذه الحقول:

`name`	الاسم التقني الذي يستدعيها به الذكاء الاصطناعي: حروف وأرقام وشرطة سفلية (consultar_credito).
`description`	متى تُستخدم وماذا تُرجع. هذا ما يقرؤه الذكاء الاصطناعي ليقرر؛ اكتبه كتعليمة («استعلم عن قرض برقم الهوية؛ يُرجع الرصيد والأقساط»).
`parameters`	قائمة من {name, type (string \| number \| boolean \| enum), description, required, enum_values}. يملؤها الذكاء الاصطناعي بما قاله العميل.
`method + endpoint`	GET أو POST أو PUT أو DELETE وعنوان URL الكامل.
`auth`	NONE، أو BEARER (Authorization: Bearer <token>)، أو API_KEY (اسم الترويسة وقيمتها حسب اختيارك)، أو BASIC (اسم المستخدم وكلمة المرور).
`headers`	ترويسات إضافية تُرسل مع كل استدعاء.
`body_template`	قالب JSON اختياري يحتوي {{param}}. بدونه، يرسل POST/PUT المعاملات ككائن JSON.
`response_path`	مسار اختياري بالنقاط (data.results) إلى الجزء من الاستجابة الذي يجب أن يقرأه الذكاء الاصطناعي.

كيف يتم الاستدعاء

يضيف GET وDELETE المعاملات إلى عنوان URL كسلسلة استعلام (query string). ويرسلها POST وPUT كـ body بصيغة JSON، أو يرسلان body_template بعد تعبئته. ترويسات المصادقة والترويسات الإضافية تُرسل مع كل استدعاء. أجب بـ 2xx مع JSON: يستلم الذكاء الاصطناعي الـ body (أو الجزء المحدد في response_path) كنص ويستخدمه في الرد. أي رمز غير 2xx يصل إلى الذكاء الاصطناعي على شكل «API returned <status>» فيخبر العميل أنه تعذّر الاستعلام؛ ولا توجد إعادة محاولة.

كيف تنشئ أداة

Canvas (newui.tbit.app): اسأل «ما الأدوات المخصّصة التي لديّ؟» ← في القائمة خيار «أداة جديدة…»؛ وكل صف يفتح الأداة مع زر «تعديل». يطلب منك نموذج كل ما سبق؛ والأسرار التي تتركها فارغة عند التعديل تبقى كما هي.
MCP (Claude وChatGPT…): list_custom_tools لقراءتها، وmanage_custom_tool مع action=create | update | delete. يُقترح التغيير وأنت تؤكده.
تطبيق المنصة: التكاملات ← API مخصّصة.

مثال: الإنشاء من الـ MCP

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "يستعلم عن حالة قرض برقم الهوية؛ يُرجع الرصيد والأقساط المتبقية وموعد الدفعة التالية.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "رقم هوية العميل، أرقام فقط", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<الـ token الخاص بك>",
  "response_path": "data"
}

ما الذي تستلمه نقطة النهاية لديك

مع المثال أعلاه، عندما يسأل عميل عن قرضه يستدعي الذكاء الاصطناعي:

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <الـ token الخاص بك>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

أفضل الممارسات

اكتب الوصف للذكاء الاصطناعي لا لمطوّر: متى تُستخدم الأداة وماذا تُرجع.
اجعل إلزاميًا فقط ما يجب أن يطلبه الذكاء الاصطناعي من العميل؛ وأعطِ الباقي قيمة افتراضية من جهتك.
اجعل طلبات GET متساوية الأثر (idempotent): قد يستدعي الذكاء الاصطناعي الأداة نفسها مرتين في محادثة واحدة إذا فشلت المحاولة الأولى.
أرجِع JSON صغيرًا ومسطّحًا. استخدم response_path إذا كانت الـ API لديك تغلّف النتائج.