مقدمة

K-Agent منصة وكلاء ذكاء اصطناعي من Kerneltics. تُعدّ الوكيل مرة واحدة — هويته ولهجته، وتعليماته، ومعرفته، وأدواته، وضوابطه، وساعات العمل، وقواعد التحويل لموظف — ثم تستخدم الوكيل نفسه في كل مكان: من الخادم الخاص بك، وفي جلسات المحادثة، وعبر حزم OpenAI، وفي ودجت دردشة على موقعك، مع فريقك جاهزًا لاستلام المحادثة عندما يلزم إنسان.

صُمّمت المنصة للعربية أولًا، للسعودية والخليج. كل إعداد ورسالة وخطأ متاح بالعربية والإنجليزية، والردود تتبع اللهجة التي تختارها.

طرق استخدام وكيلك

نقطة الدخول	الغرض	الطريقة
سؤال واحد	سؤال يدخل وجواب يخرج، بلا حالة محادثة.	POST /v1/agents/{agent}/ask
جلسات المحادثة	محادثات مستمرة بسجلّ كامل، بمعرّفنا sess_… أو بمعرّفك الخاص external_id.	POST /v1/sessions ثم POST /v1/sessions/{session}/messages
البث المباشر	عرض الرد أثناء كتابته عبر Server-Sent Events.	"stream": true في السؤال والجلسات والرسائل
واجهة متوافقة مع OpenAI	احتفظ بكود حزمة OpenAI، ووجّهه إلى K-Agent، واستخدم معرّف الوكيل النصي (slug) اسمًا للنموذج.	/openai/v1/chat/completions
ودجت الدردشة	فقاعة دردشة لموقعك، للزوار المجهولين والمستخدمين المسجّلين.	وسم <script> واحد
مكتب التحويل	صندوق وارد بسيط يستلم فيه فريقك المحادثات التي يحوّلها الوكيل.	لوحة التحكم أو واجهة التحويل البرمجية

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

المكوّنات الأساسية

المصطلح	المعنى
المنظمة (org_)	شركتك. تملك المشاريع والأعضاء والخطة.
المشروع (proj_)	وحدة العزل: المفاتيح والوكلاء والجلسات والبيانات. استخدم مشروعًا للتجربة وآخر للإنتاج.
الوكيل (agt_)	مساعد مُعدّ مسبقًا. له مسودة قابلة للتعديل وإصدارات مرقّمة لا تتغير. تخاطبه بمعرّفه أو بمعرّفه النصي مثل store-assistant.
الجلسة (sess_)	محادثة دائمة بين عميل واحد ووكيل واحد، ويمكن أن تحمل معرّفك الخاص external_id أيضًا.
التشغيل (run_)	دور واحد للوكيل: مدخل، ثم خطوات النموذج والأدوات، ثم مخرج. السؤال الواحد تشغيلٌ بلا جلسة.
الرسالة (msg_)	عنصر واحد في سجل المحادثة، بدور user أو assistant أو human_agent أو system.
العميل (eu_)	الشخص الذي يحادث الوكيل. يُعدّ موثّقًا فقط عندما يضمنه خادمك.
التحويل لموظف (ho_)	نقل محادثة إلى فريقك بسبب محدد النوع. ما دام مفتوحًا يتوقف الوكيل عن الرد.
الأداة	إجراء يستطيع النموذج استدعاءه: أداة مدمجة، أو أداة HTTP تستدعي واجهتك البرمجية، أو أداة من جهة العميل يشغّلها تطبيقك.
مصدر المعرفة (ks_)	نص أو كتالوج أو تغذية من واجهة برمجية يجيب الوكيل منها.
المحادثة الذكية	وحدة الفوترة. انظر الاستخدام والفوترة.

المعرّفات بادئة يتبعها 26 حرفًا صغيرًا (sess_01k6rz4p7h2c9m5x8w3t6v1qbg). لا يمكن تخمينها، وتُرتَّب حسب وقت الإنشاء.

ما الذي يحدث في الدور الواحد

عندما ترسل رسالة، يقوم K-Agent بما يلي:

1. يحدّد إصدار الوكيل والجلسة والعميل، ويتحقق من أن مفتاحك يملك صلاحية الوصول إليها.
2. يعيد النتيجة المحفوظة إذا كررت مفتاح Idempotency-Key نفسه.
3. يصمت في وضع الموظف: إذا كانت المحادثة بيد فريقك تُحفظ الرسالة ولا يعمل الذكاء الاصطناعي.
4. يقبل التشغيل وفق سياسة التزامن في الجلسة، فلا تتسابق رسالتان أبدًا.
5. يتحقق من الحصة والجاهزية — مثل وجود مفتاح نموذج مربوط.
6. يبني التعليمات من إعداداتك: الهوية، ثم التعليمات، ثم المعرفة، ثم الضوابط في الأخير؛ مع نافذة السجل، وكتلة حيّة قصيرة فيها الساعة وحالة ساعات العمل.
7. يشغّل النموذج والأدوات حتى max_tool_rounds جولة. كل استدعاء أداة يمرّ بفحص سياسات قبل تنفيذه.
8. ينتهي بنتيجة واحدة بالضبط — غالبًا answered أو handed_off — أو يتوقف مؤقتًا بحالة requires_action ريثما يشغّل تطبيقك أداة من جهة العميل. التشغيل لا يصمت أبدًا.

أمان يمكنك الاعتماد عليه

التصعيد مفروض في الكود، لا متروك للتعليمات:

• قائمة «لا تتعامل معها بنفسك». مواضيع لا يجيب عنها الوكيل بنفسه أبدًا (ادعاءات الأضرار، والتهديدات القانونية، ومبالغ الاسترداد، والشكاوى من الموظفين، وبيانات العملاء الآخرين). مفعّلة افتراضيًا وتوضع في آخر التعليمات.
• الرد الحرفي عند التصعيد. عندما يحوّل الوكيل حالة ذات مسؤولية قانونية، يرى العميل الرد الذي كتبته أنت بالحرف.
• لا صمت أبدًا. تُعاد محاولة أخطاء المزوّد، ثم تُجرَّب النماذج البديلة، ثم يُرسل رد الطوارئ الذي كتبته مع تحويل لموظف.
• تحويل صادق. لا يقول الوكيل إن موظفًا سيتابع إلا إذا سُجّل التحويل فعلًا.
• نفاد الحصة لا يظهر خطأً للعميل. عند نفاد الخطة المجانية تُحوَّل الجلسات لموظف مع إشعار مهذب بدل الخطأ.

اقرأ المزيد في التحويل لموظف والأمان.

العناوين والتحقق من الهوية

ماذا	العنوان
الواجهة البرمجية	https://api.k-agent.kerneltics.com/v1
الواجهة المتوافقة مع OpenAI	https://api.k-agent.kerneltics.com/openai/v1
لوحة التحكم	https://app.k-agent.kerneltics.com
سكربت الودجت	https://api.k-agent.kerneltics.com/widget/v1.js

يحمل كل طلب الترويسة Authorization: Bearer <credential>:

بيانات الاعتماد	البادئة	مكانها
المفتاح السري	kt_sk_live_… أو kt_sk_test_…	خوادمك فقط. وصول كامل للواجهة البرمجية، ويمكن تقييده بنطاقات أو بوكلاء محددين.
المفتاح القابل للنشر	kt_pk_live_…	صفحات موقعك. يبدأ جلسات الودجت فقط، ومن المصادر التي تسمح بها فقط.
رمز العميل	ct_…	متصفح أو تطبيق، لعميل واحد ووكيل واحد. يصدره خادمك، وصلاحيته حتى 60 دقيقة.

_live_ و_test_ تسميات تساعدك وتساعد أدوات كشف الأسرار على التمييز بين المفاتيح؛ أما الذي يعزل البيانات فهو المشروع.

أبقِ المفاتيح السرية على الخادم

لا تضع مفتاح kt_sk_ أبدًا في كود المتصفح أو تطبيق الجوال أو مستودع عام. الواجهة البرمجية لا ترسل ترويسات CORS للمفاتيح السرية، فلا تستطيع المتصفحات استخدامها أصلًا. استخدم في كود الواجهة الأمامية مفتاحًا قابلًا للنشر أو رمز عميل.

أعراف الواجهة البرمجية في دقيقة

• JSON في كل مكان. تحمل الكائنات id وobject وcreated_at (ثوانٍ بتوقيت يونكس).
• القوائم تستخدم مؤشرات التصفح: ?limit=20&after=<id> يعيد {object: "list", data, first_id, last_id, has_more} (100 عنصر كحد أقصى في الصفحة).
• الأخطاء في غلاف موحّد برمز code ثابت ورسالة بالعربية أو الإنجليزية حسب Accept-Language. انظر الأخطاء.
• إعادة المحاولة آمنة بترويسة Idempotency-Key في طلبات POST وDELETE. انظر عدم التكرار.
• معرّفات الطلبات: كل استجابة تحمل الترويسة Request-Id. اذكرها عند التواصل مع الدعم.
• الإصدارات: /v1 لا يتغير إلا بالإضافة. انظر سياسة الإصدارات.

الخطوات التالية

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