لماذا تربط وكيل الذكاء الاصطناعي بتطبيقك عبر API

ما هي واجهة API لوكيل الذكاء الاصطناعي؟

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

هذا هو الفرق عن واجهة API لنموذج خام. واجهة النموذج تعطيك توليد النص وتترك لك الباقي: التعليمات، والبحث في المستندات، والذاكرة، وحدود الطلبات، والفوترة. أما واجهة REST API من IMFA فتعطيك وكيلا مدارا فيه كل ذلك مسبقا، خلف مفتاح واحد خاص بالوكيل.

تبني الوكيل باستخدام منشئ روبوتات الدردشة الذكية. وAPI مكان إضافي يستطيع الرد فيه، إلى جانب موقعك وWhatsApp وInstagram وFacebook وTelegram وDiscord والخط الصوتي.

متى يجب أن تربط وكيلك عبر API؟

استخدم API عندما تجري المحادثة داخل شيء تملكه أنت:

• تطبيقك أو بوابة عملائك تحتاج إلى مساعد يعرف سياساتك، دون روبوت دردشة ثان تديره.
• الخادم الخلفي لديك يجب أن يجيب عن أسئلة قادمة من نظام آخر، مثل صفحات الطلبات أو أداة حجز أو لوحة تحكم داخلية.
• تريد عملاءك المحتملين في نظام CRM. تعيد API العملاء المحتملين الذين جمعهم الوكيل على كل القنوات، فتستطيع مزامنتهم وفق جدول زمني.
• تحتاج إلى سجل المحادثات لإعداد التقارير أو مراجعة الجودة.

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

كيف تعمل واجهة API لوكيل IMFA

العنوان الأساسي هو https://site.imfa.app/v1. كل طلب يحتاج إلى مفتاح الوكيل، ويجب أن يأتي من كود خادم موثوق، لا من متصفح ولا من حزمة تطبيق جوال.

1. انشر الوكيل. اضبط تعليماته ومعرفته ونموذجه وأدواته في IMFA، واختبر أسئلة حقيقية، ثم انشره. تخدم API النسخة المنشورة.
2. أنشئ المفتاح. افتح عرض API الخاص بالوكيل أو شاشة API Keys وأنشئ مفتاحا. يظهر مرة واحدة فقط، ولا نحفظ منه إلا hash. احفظه في متغير بيئة على الخادم مثل IMFA_API_KEY.
3. أرسل طلب دردشة. POST /v1/agents/{slug}/chat مع Authorization: Bearer <key>، وIdempotency-Key فريد (من 8 إلى 128 حرفا)، وجسم JSON فيه message وsessionId اختياري. يعود الرد مع sessionId وusage.credits.
4. تابع المحادثة. لا ترسل sessionId في الدور الأول، ثم أعد إرسال المعرف الذي استلمته. يتذكر الوكيل السياق.
5. اقرأ ما حدث. GET /v1/agents/{slug}/sessions يعرض المحادثات، وGET /v1/agents/{slug}/sessions/{sessionId}/messages يقرأ محادثة واحدة، وGET /v1/agents/{slug}/leads يعيد العملاء المحتملين. تعيد القوائم 20 عنصرا افتراضيا، وحتى 100، مع مؤشر للصفحات (cursor). وGET /v1/agents يؤكد الوكيل الذي يخدمه المفتاح.

الحدود واضحة: يقرأ الوكيل أول 4,000 حرف فقط من الرسالة، وحجم الجسم محدود بـ 64,000 بايت، والأخطاء مصنفة (التحقق، والمصادقة، والرصيد، وحدود الطلبات، والخادم). رمز 429 يأتي مع Retry-After، ورمز 402 يعني أن رصيد المالك نفد.

لماذا تستخدم واجهة API للوكيل بدل بناء واجهتك الخاصة

توفر شهورا من البنية الأساسية. البحث في المستندات، والجلسات، وحدود الطلبات، وإعادة المحاولة، واحتساب الرصيد، وقواعد الحماية من حقن التعليمات، كلها تعمل بالفعل. وفريقك يكتب طلب HTTP واحدا.

وكيل واحد، سلوك واحد. الإجابة التي يعرضها تطبيقك هي نفسها التي يعطيها موقعك وWhatsApp، لأنه الوكيل نفسه. أجر التحديث مرة واحدة في IMFA فتتبعه كل الواجهات.

إعادة المحاولة آمنة. مفتاح Idempotency-Key يعني أن إعادة المحاولة بعد خلل في الشبكة تعيد الرد الأصلي بدل احتساب دور ثان.

العملاء المحتملون لا يبقون معزولين. اسحب كل عميل محتمل تم جمعه عبر نقطة نهاية واحدة، أيا كانت القناة التي جاء منها.

يبقى المسار المخصص بالكامل ممكنا. إذا احتجت إلى امتلاك كل طبقة، فواجهة API لنموذج خام تعطيك هذا التحكم، مقابل أن تبنيه وتشغله بنفسك. وتستطيع وكلاء البرمجة مثل Codex وClaude Code أيضا إدارة وكلاء IMFA عبر MCP، بينما يستخدم خادمك مفتاح REST لخدمة العملاء.

أسئلة شائعة عن واجهة API لوكيل الذكاء الاصطناعي

هل يمكنني استدعاء واجهة API للوكيل مباشرة من المتصفح؟

لا. المفتاح يستهلك رصيد المالك ويجب أن يبقى على خادم موثوق. ولا تفتح API وصولا واسعا من المتصفحات. اجعل المتصفح يستدعي نقطة نهاية محمية خاصة بك، وهي التي تستدعي IMFA.

كيف أصادق طلبات API لوكيل IMFA؟

أنشئ مفتاحا خاصا بالوكيل من عرض API الخاص به أو من شاشة API Keys، ثم أرسل Authorization: Bearer YOUR_API_KEY من كود الخادم. رمز MCP بيانات اعتماد مختلفة ولا يعمل هنا.

كيف أتابع محادثة API نفسها؟

لا ترسل sessionId في أول طلب دردشة، واحفظ sessionId الذي تعيده API، وأرسله مع الرسالة التالية. معرفات الجلسات القادمة من محادثات الموقع أو القنوات للقراءة فقط، ولا يمكنها متابعة محادثة API.

لماذا يلزم Idempotency-Key في طلبات الدردشة؟

لأنه يجعل إعادة المحاولة آمنة. إعادة الطلب نفسه بالمفتاح نفسه تعيد النتيجة نفسها بدل إنشاء دور جديد. استخدم مفتاحا جديدا لكل رسالة جديدة.

هل تستخدم واجهة API للوكيل معرفتي وأدواتي؟

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