اربط وكيلًا ذكيًا مُدارًا بتطبيقك
استخدم مفتاح REST مخصصًا لوكيل واحد من خادم موثوق لاستدعاء وكيل IMFA المنشور نفسه بمعرفته وسلوكه ونماذجه وأدواته وجلساته وقنواته. أرسل الرسائل وتابع محادثات API واقرأ السجل واسترجع العملاء المحتملين دون إعادة بناء دورة حياة الوكيل.
ما هي واجهة API للوكيل الذكي؟
تسمح واجهة الوكيل الذكي لتطبيق موثوق بالتواصل مع وكيل يملك مسبقًا تعليمات ومعرفة وإعدادات نموذج وأدوات وسلوكًا للمحادثة. تتيح واجهة IMFA REST عرض الوكيل المتاح للمفتاح وإرسال رسالة ومتابعة جلسة API وقراءة الرسائل المحفوظة واسترجاع العملاء المحتملين.
هذه واجهة لوكيل مُدار وليست نقطة وصول مباشرة إلى نموذج. تضبط الوكيل وتنشره في IMFA، ثم يستدعيه خادمك بمفتاح خاص به. ويمكن للمعرفة نفسها عبر RAG والسلوك المعتمد خدمة تطبيقك والويب وWhatsApp وTelegram وDiscord والصوت المؤهل.
عقد إنتاج واضح لتكاملات الخادم الموثوقة
توفر الواجهة نطاق REST محدودًا وموثقًا حول وكيل منشور، بينما تواصل IMFA إدارة المعرفة والسلوك والنماذج والجلسات والأرصدة وحدود الحماية.
مصادقة مخصصة للوكيل
أنشئ مفتاح REST يدويًا من صفحة API الخاصة بالوكيل أو شاشة مفاتيح API، ثم أرسل Authorization: Bearer YOUR_API_KEY. يظهر المفتاح مرة واحدة ويُحفظ كتجزئة، وهو مختلف عن رمز MCP الخاص بالحساب.
دردشة آمنة من التكرار
يتطلب POST /v1/agents/{slug}/chat ترويسة Idempotency-Key من 8 إلى 128 محرفًا مسموحًا. استخدم قيمة جديدة لكل دور مختلف وأعد استخدامها فقط لتكرار الطلب نفسه تمامًا.
سياق محادثة API قابل للمتابعة
احذف sessionId لبدء محادثة API جديدة، ثم خزّن القيمة العائدة مع الرد وأعد استخدامها في الأدوار التالية. معرفات جلسات الموقع والباني والقنوات الظاهرة في السجل مخصصة للقراءة فقط.
الجلسات والرسائل والعملاء المحتملون
اعرض الجلسات المحفوظة واقرأ رسائل جلسة محددة واسترجع العملاء المحتملين. تعيد مسارات GET المقسمة 20 عنصرًا افتراضيًا وتقبل limit من 1 إلى 100 مع cursor اختياري.
حدود وحالات استجابة واضحة
تتطلب الدردشة message وتستخدم أول 4,000 محرف منه، وتقبل sessionId حتى 128 محرفًا، ويبلغ الحد الأقصى لجسم الطلب 64,000 بايت. تميز الحالات بين الإدخال والمصادقة والأرصدة والتوفر والإيقاف والحجم والمعدل وأخطاء الخادم.
نظام الوكيل المُدار نفسه
تستخدم الردود تعليمات الوكيل المنشور ونموذجه ومعرفة RAG ومهاراته وأدواته وحدود حمايته. تستهلك الطلبات أرصدة المالك وقد يعيد الرد الناجح usage.credits.
كيفية استدعاء وكيل IMFA من خادمك
انشر الوكيل أولًا، واحفظ مفتاحه في متغير بيئة على الخادم، وصمم إعادة المحاولة بما يحافظ على عدم التكرار واستمرار الجلسة.
-
أنشئ الوكيل المُدار وانشره
حدد التعليمات ومعرفة RAG والنموذج والمهارات والأدوات والحماية في IMFA. اختبر أسئلة واقعية وانشر الوكيل بقرار صريح قبل استخدام نقطة REST.
-
أنشئ المفتاح واحمه
افتح صفحة API أو https://www.imfa.app/app/api-keys، وأنشئ المفتاح يدويًا واحفظه في متغير خادم مثل IMFA_API_KEY. لا تضعه في كود المتصفح أو تطبيق الهاتف أو مستودع عام أو السجلات أو الرسائل.
-
أرسل طلبًا من الخادم دون تكرار
استدع fetch('https://site.imfa.app/v1/agents/{slug}/chat') بطريقة POST مع Authorization: Bearer ومفتاح الخادم وContent-Type: application/json وIdempotency-Key فريد وJSON يحوي message وsessionId اختياريًا. خزّن reply وsessionId وusage.credits.
واجهة IMFA مقارنة بواجهة نموذج خام أو بناء مخصص
يعتمد الاختيار على الطبقة التي يريد فريقك امتلاكها. تعرض IMFA وكيلًا مُدارًا جاهزًا لخدمة العملاء، بينما تقدم واجهة النموذج أدوات توليد أولية.
واجهة النموذج الخام تمنح تحكمًا هندسيًا كاملًا
اختر مزود النموذج مباشرة إذا أردت امتلاك التوجيهات وإدخال RAG واسترجاعه وتخزين الجلسات وسياسات الأدوات والمصادقة وحدود المعدل والقنوات والمراقبة والفوترة والنشر والأمان والصيانة.
وكلاء البرمجة يبنون البرامج المخصصة
يستطيع Codex وClaude Code بناء التطبيقات والتكاملات. ويمكنهما أيضًا إدارة وكلاء IMFA عبر MCP، بينما يستخدم خادم الإنتاج مفتاح REST منفصلًا ومخصصًا للوكيل لخدمة الطلبات.
IMFA تدير دورة حياة الوكيل
اختر IMFA عندما يحتاج تطبيقك إلى وكيل تُدار معرفته وسلوكه وقنواته وجلساته وعملاؤه ونماذجه وحدود حمايته وحالة نشره واستخدامه في واجهة واحدة.
خمس نقاط REST لوكيل واحد منشور
عنوان الأساس هو https://site.imfa.app/v1. يحتاج كل طلب إلى مفتاح Bearer الخاص بالوكيل، ويجب أن تأتي الدردشة من بنية خادم موثوقة.
عرض الوكيل المتاح
يعيد GET /v1/agents الوكيل المتاح للمفتاح حتى يتأكد الخادم من هدف التكامل المنشور.
الدردشة مع الوكيل
يرسل POST /v1/agents/{slug}/chat رسالة ويعيد reply وsessionId قابلًا لإعادة الاستخدام وusage.credits وحالة replay عند انطباقها.
قراءة المحادثات
يعرض GET /v1/agents/{slug}/sessions المحادثات، ويقرأ GET /v1/agents/{slug}/sessions/{sessionId}/messages رسائل جلسة واحدة.
استرجاع العملاء المحتملين
يعيد GET /v1/agents/{slug}/leads سجلات العملاء المحتملين عبر عقد التقسيم نفسه المعتمد على cursor.
أسئلة شائعة عن واجهة API للوكيل الذكي
إجابات دقيقة عن المصادقة والاستخدام من الخادم وعدم التكرار والجلسات وRAG والأرصدة وحدود المعدل.
هل يمكن استدعاء واجهة الوكيل مباشرة من المتصفح؟
لا. يستهلك مفتاح REST أرصدة المالك ويجب أن يبقى في بيئة خادم موثوقة. الواجهة غير مخصصة للمتصفح ولا تتيح CORS عامًا واسعًا. ينبغي للمتصفح استدعاء نقطة خادم محمية تملكها أنت.
كيف أوثق طلب API إلى وكيل IMFA؟
أنشئ مفتاح REST خاصًا بالوكيل يدويًا من صفحة API أو شاشة المفاتيح، ثم أرسل Authorization: Bearer YOUR_API_KEY من الخادم. رمز MCP اعتماد مختلف ولا يمكنه أن يحل محل مفتاح REST.
كيف أتابع محادثة API نفسها؟
احذف sessionId في الطلب الأول، ثم خزّن القيمة المعادة وضعها في جسم الطلب التالي. معرف جلسة أعادته دردشة API هو الوحيد الذي يتابع هذا السياق؛ معرفات الويب والقنوات للقراءة فقط.
لماذا ترويسة Idempotency-Key إلزامية؟
تسمح بتكرار الطلب نفسه بأمان دون تحويل إعادة محاولة الشبكة إلى دور محادثة جديد. استخدم قيمة جديدة من 8 إلى 128 محرفًا لكل رسالة مختلفة، وأعد استخدامها للطلب نفسه فقط.
هل تستخدم الواجهة معرفة RAG وأدوات الوكيل؟
نعم. تستدعي الوكيل المنشور بتعليماته ونموذجه ومعرفة RAG ومهاراته وأدواته وحدود حمايته. يبقى السلوك مرتبطًا بالإعداد المنشور والأرصدة وحدود الخدمة الحالية.
ماذا يحدث عند تجاوز المعدل أو نفاد الأرصدة؟
قد يعيد الطلب 402 عند نفاد أرصدة المالك أو 429 عند تقييد المعدل. انتظر مدة Retry-After عند 429، وتعامل مع كل الحالات الموثقة. قد يعيد فشل التوليد sessionId حتى مع خطأ داخلي.