المعرفة

مصادر المعرفة (ks_…) تحفظ الحقائق التي يجيب منها وكيلك: الأسعار، ومواعيد العمل، والسياسات، وكتالوج المنتجات، وتغذية حيّة من أنظمتك. تنتمي المصادر إلى المشروع، فيمكن لعدة وكلاء مشاركتها، ويختار كل وكيل المصادر التي يستخدمها وطريقة استخدامها.

أنواع المصادر

النوع	المحتوى	يناسب
text	نص حر، حتى 200,000 حرف	السياسات، والأسئلة الشائعة، ووصف الخدمات
catalog	عنصر في كل سطر، أو CSV	قوائم الأسعار، والمنتجات، والفروع
api	يُجلب من رابطك بجدول زمني ويُحوَّل إلى أسطر	المخزون، والمواعيد، وكل ما يتغير يوميًا

curl https://api.kagent.72.62.2.247.sslip.io/v1/knowledge_sources \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "قائمة الأسعار",
    "kind": "catalog",
    "content": "دهن العود الملكي 12 مل — 450 ريال\nعطر المسك الأبيض 100 مل — 220 ريال\nصندوق بخور — 95 ريال\nطقم هدايا (عطر + بخور) — 280 ريال"
  }'

دائم أو قابل للبحث

يربط الوكيل المصادر في knowledge.sources، ولكلٍّ منها وضع:

{
  "knowledge": {
    "sources": [
      { "source_id": "ks_01k6rz2n5q8t1w4z7c0f3h6k9m", "mode": "always" },
      { "source_id": "ks_01k6rz2p9r3t5w7y1a3c5e7g9j", "mode": "searchable" }
    ]
  }
}

الوضع	كيف يستخدمه الوكيل	استخدمه لـ
always	المصدر كاملًا داخل التعليمات، تحت «Context Information»، بالترتيب الذي تحدده.	الحقائق القصيرة الأساسية التي يحتاجها الوكيل في كل محادثة.
searchable	يبحث الوكيل فيه بالأداة المدمجة search_knowledge عند الحاجة.	الكتالوجات والوثائق الطويلة.

يعرض كل مصدر تقديرًا لعدد الرموز. وحين يتجاوز مجموع مصادر always في الوكيل نحو 8,000 رمز تقترح لوحة التحكم جعل بعضها قابلًا للبحث: فالتعليمات الكبيرة تكلّف أكثر في كل دور وتشتّت الانتباه.

المعرفة حيّة لكل الإصدارات: تعديل مصدر يغيّر إجابات كل إصدارات كل وكيل يستخدمه، دون نشر. ويوسم المحرّر و«أشعة إكس» المصادر بعبارة «حيّ: يسري على كل الإصدارات»، وتسجّل كل خطوة تشغيل قيمة updated_at للمصادر التي استخدمتها.

بحث يفهم العربية

صُمّمت search_knowledge على الطريقة التي يكتب بها الناس العربية فعلًا. يُوحَّد شكل المحتوى والاستعلام كليهما قبل المطابقة:

• أ وإ وآ تصبح ا، وة تصبح ه، وى تصبح ي؛
• تُحذف الحركات والتطويل (ـ)؛
• الأرقام العربية (٠١٢٣٤٥٦٧٨٩) تصبح أرقامًا لاتينية؛
• تُتجاهل الكلمات الشائعة التي لا تحمل معنى للبحث.

المطابقة كلمة بكلمة مع تسامح مع الأخطاء الإملائية: تعديل واحد للكلمات من 3 إلى 5 أحرف، وتعديلان لما كان 6 أحرف فأكثر، ولا تسامح فيما دون 3. والسطر الذي يطابق كل كلمات الاستعلام يتقدم على المطابقات الجزئية، وعند التساوي يتقدم السطر الأقصر، وتُعاد 25 نتيجة كحد أقصى. فالاستعلام صندق بخور (خطأ إملائي شائع) يجد صندوق بخور — 95 ريال.

تُقسَّم مصادر الكتالوج والواجهات البرمجية إلى جزء لكل سطر، والمصادر النصية إلى فقرات حتى 800 حرف.

حين لا يطابق شيء

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

القيمة الافتراضية لـ complete هي true لمصادر catalog ومصادر api المحوَّلة، وfalse لمصادر text.

جرّب البحث

curl https://api.kagent.72.62.2.247.sslip.io/v1/knowledge/search \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "كم سعر صندق البخور", "source_ids": ["ks_01k6rz2n5q8t1w4z7c0f3h6k9m"]}'

مصادر الواجهات البرمجية

يجلب مصدر api بيانات JSON من رابطك بجدول زمني ويحوّلها إلى أسطر يستطيع الوكيل استخدامها:

{
  "name": "المنتجات والأسعار",
  "kind": "api",
  "config": {
    "url": "https://api.example.com/products?status=active",
    "headers": { "Authorization": "Bearer {{secret.CATALOG_TOKEN}}" },
    "refresh_minutes": 60,
    "transform": {
      "items_path": "data.products",
      "line": "- {name} — {price} ريال",
      "group_by": "category",
      "sort_by": "price",
      "skip_when_zero": "price",
      "max_items": 500,
      "header": "الأسعار الحالية"
    }
  }
}

• refresh_minutes بين 15 و1440 (الافتراضي 60). ويُزامَن المصدر فورًا أيضًا عند تغيير رابطه أو تحويله، وعند الطلب عبر POST /v1/knowledge_sources/{ks}/sync.
• transform يحوّل الاستجابة إلى أسطر: items_path يشير إلى القائمة؛ وline قالب بعناصر نائبة بقوس واحد {field}؛ وgroup_by يضيف عنوانًا ### <value> لكل مجموعة، والمجموعة الأكبر أولًا؛ وsort_by يرتّب تصاعديًا داخل كل مجموعة؛ وskip_when_zero يُسقط العناصر التي قيمة حقلها صفر أو مفقودة؛ وmax_items يحدّ القائمة؛ وheader يُوضع في الأعلى.
• تستخدم الترويسات الأسرار بأسمائها، لا بقيم صريحة، ويجب أن تتضمن allowed_hosts الخاصة بالسر مضيفَ الرابط.
• يمرّ الطلب عبر العميل المحمي نفسه الذي تستخدمه أدوات HTTP: روابط https:// عامة على المنفذ 443 أو 8443 فقط، ودون تحويلات (redirects)، وبحد 1 ميغابايت.
• عند الفشل تبقى آخر نسخة سليمة. الاستجابة بغير 2xx، أو JSON غير صالح، أو غياب items_path، أو نتيجة فارغة، كلها تُعدّ فشلًا: يبقى المحتوى السابق مستخدمًا، ويعرض المصدر الخطأ، ويُطلق الويب هوك knowledge_source.sync_failed، وتعرض جاهزية الوكيل العائق knowledge_sync_failing.

نقاط النهاية

الطريقة والمسار	الغرض
GET وPOST /v1/knowledge_sources	سرد المصادر وإنشاؤها
GET وPATCH وDELETE /v1/knowledge_sources/{ks}	القراءة والتحديث والحذف
POST /v1/knowledge_sources/{ks}/sync	جلب مصدر api الآن
POST /v1/knowledge/search	تشغيل بحث تجريبي

يمكن أن يصل حجم طلبات المعرفة إلى 5 ميغابايت.