مرجع الإعدادات

إعدادات الوكيل وثيقة JSON واحدة. يعيدها GET /v1/agents/{agent} كاملة دائمًا، مع ملء كل قيمة افتراضية؛ وتُرفض الحقول غير المعروفة. عدّلها من محرّر الصفحة الواحدة في لوحة التحكم أو عبر رقعة دمج. ومخطط JSON بأوصاف عربية وإنجليزية متاح عبر GET /v1/agents/config_schema.

حدود النصوص تُحسب بالحروف (نقاط يونيكود)، فيحصل النص العربي والإنجليزي على المساحة نفسها.

الوثيقة كاملة

إعدادات وكيل جديد بقيمها الافتراضية:

{
  "locale": { "language": "ar", "timezone": "Asia/Riyadh" },
  "identity": { "enabled": false, "bot_name": "", "dialect": "match", "tone": "friendly", "persona_notes": "" },
  "instructions": { "enabled": true, "text": "" },
  "knowledge": { "sources": [] },
  "tools": {
    "enabled": true,
    "builtin": {
      "transfer_to_human": { "enabled": true, "rules": "" },
      "create_ticket": { "enabled": false, "rules": "" },
      "flag_conversation": { "enabled": false, "rules": "" },
      "search_knowledge": { "enabled": true, "rules": "" }
    },
    "http": [],
    "client": [],
    "allow_anonymous_actions": false,
    "max_tool_rounds": 3
  },
  "guardrails": {
    "never_handle": {
      "enabled": true,
      "items": [
        "ادعاءات الأضرار أو الإصابات أو الحوادث",
        "التهديدات القانونية، أو ذكر المحامين أو الشرطة أو الجهات الرسمية",
        "مبالغ الاسترداد أو التعويض",
        "الشكاوى التي تذكر موظفًا بعينه",
        "طلبات بيانات عميل آخر"
      ]
    },
    "escalation_reply": { "ar": "", "en": "" },
    "business_scope": ""
  },
  "handoff": {
    "ttl_hours": 24,
    "never_expire": false,
    "outside_hours": "record",
    "destinations": [{ "type": "desk" }],
    "notify": { "emails": [], "unclaimed_reminder_minutes": 10 },
    "on_expire": "release_with_message",
    "expire_message": { "ar": "", "en": "" }
  },
  "business_hours": {
    "enabled": false,
    "schedule": [
      { "day": "sun", "open": "09:00", "close": "17:00" },
      { "day": "mon", "open": "09:00", "close": "17:00" },
      { "day": "tue", "open": "09:00", "close": "17:00" },
      { "day": "wed", "open": "09:00", "close": "17:00" },
      { "day": "thu", "open": "09:00", "close": "17:00" }
    ],
    "out_of_hours_message": { "ar": "", "en": "" },
    "outside_hours_ai": "answer"
  },
  "conversation": { "history_limit": 12, "idle_timeout_minutes": 30, "concurrency": "queue", "stream_mode": "auto" },
  "model": {
    "provider": "openai",
    "model": "gpt-6-luna",
    "credential": "auto",
    "max_reply_tokens": 1024,
    "temperature": null,
    "fallback_models": []
  },
  "variables": [],
  "overrides": { "allowed": [], "models": [] },
  "fallback": { "message": { "ar": "", "en": "" }, "handoff_on_failure": true },
  "widget": {
    "greeting": { "ar": "", "en": "" },
    "launcher_label": { "ar": "", "en": "" },
    "theme": { "accent": "#0F766E", "position": "end" },
    "anonymous_daily_conversations": 200
  }
}

نصوص بلغتين

الحقول التي يقرؤها العملاء حرفيًا نصوص مترجمة: كائن {"ar": "…", "en": "…"}. يختار K-Agent لغة آخر رسالة من العميل (إذا كانت 30% من حروفها أو أكثر عربية فاللغة عربية)، وإلا يرجع إلى locale.language. والقيمة الفارغة تستخدم النص الافتراضي المدمج لتلك اللغة إن وُجد. والنصوص المترجمة هي guardrails.escalation_reply وfallback.message وhandoff.expire_message وbusiness_hours.out_of_hours_message وwidget.greeting وwidget.launcher_label.

حقول الوكيل

تقع هذه الحقول بجانب الإعدادات، في المستوى الأعلى من كائن الوكيل.

الحقل	النوع	الافتراضي	الوصف
name	نص	—	اسم العرض، إلزامي.
slug	نص	مشتق من الاسم	الاسم في الروابط، ^[a-z0-9][a-z0-9-]{0,62}$، فريد في المشروع. يصلح أينما ظهر {agent}.
description	نص	""	لفريقك؛ لا يُرسل إلى النموذج أبدًا.
ai_paused	منطقي	false	يوقف ردود الذكاء الاصطناعي فورًا. غير مرتبط بالإصدارات؛ لا يحتاج If-Match؛ يُسجَّل في التدقيق.
actions_paused	منطقي	false	يزيل الأدوات ذات الأثر فورًا. غير مرتبط بالإصدارات؛ يُسجَّل في التدقيق.

اللغة والمنطقة (locale)

الحقل	النوع	الافتراضي	الوصف
language	ar · en	لغة المشروع	اللغة الأساسية للوكيل: المرجع للنصوص المترجمة والاتجاه الافتراضي للودجت.
timezone	اسم IANA	المنطقة الزمنية للمشروع (Asia/Riyadh)	تحدد ساعة الوكيل، وساعات العمل، وnext_open_local، والإشعارات. لا تُستخدم منطقة الخادم أبدًا.

الهوية (identity)

الحقل	النوع	الافتراضي	الوصف
enabled	منطقي	false	يفعّل كتلة الهوية. وحين يكون معطّلًا لا يضيف شيئًا إلى التعليمات.
bot_name	نص	""	الاسم الذي يعرّف به الوكيل نفسه حين يُسأل.
dialect	match · saudi · gulf · msa · english	match	لغة الردود ولهجتها. match يحاكي العميل. انظر اللهجة العربية والنبرة.
tone	friendly · formal · brief	friendly	نبرة الردود.
persona_notes	نص، ≤ 4,000	""	ملاحظات إضافية عن الشخصية. يُسمح بـ {{variables}}.

التعليمات (instructions)

الحقل	النوع	الافتراضي	الوصف
enabled	منطقي	true	التعطيل يُبقي النص لكنه يُخرجه من التعليمات.
text	نص، ≤ 20,000	""	تعليماتك: ما يقدمه النشاط، وكيف يجيب الوكيل، وما يتجنبه. تُعرض {{variables}} بيانات موسومة بوضوح.

المعرفة (knowledge)

الحقل	النوع	الافتراضي	الوصف
sources	مصفوفة	[]	عناصر {source_id, mode}، بالترتيب الذي تظهر به في التعليمات. mode إما always (داخل التعليمات) أو searchable (خلف search_knowledge). انظر المعرفة.

الأدوات (tools)

الحقل	النوع	الافتراضي	الوصف
enabled	منطقي	true	المفتاح الرئيسي. تعطيله يزيل كل الأدوات ويُبقي الصلاحيات أدناه.
builtin.transfer_to_human	{enabled, rules}	مفعّلة	تحويل المحادثة إلى فريقك.
builtin.create_ticket	{enabled, rules}	معطّلة	فتح تذكرة.
builtin.flag_conversation	{enabled, rules}	معطّلة	وسم الجلسة للمراجعة.
builtin.search_knowledge	{enabled, rules}	مفعّلة	البحث في المعرفة القابلة للبحث.
http	مصفوفة	[]	صلاحيات {tool_id, rules} لـأدوات HTTP.
client	مصفوفة	[]	أدوات جهة العميل بالحقول {name, description, parameters, rules, effect}. ‏effect إما read أو action (الافتراضي).
allow_anonymous_actions	منطقي	false	السماح بتشغيل الأدوات ذات الأثر للعملاء غير الموثّقين.
max_tool_rounds	عدد صحيح، 1–5	3	جولات النموذج والأدوات في الدور الواحد قبل إجابة نهائية دون أدوات.

rules (في كل صلاحية) حتى 4,000 حرف، ويُضاف إلى وصف الأداة قواعدَ شركتك الخاصة بها.

الضوابط (guardrails)

الحقل	النوع	الافتراضي	الوصف
never_handle.enabled	منطقي	true	كتلة «لا تتعامل معها بنفسك»، وتوضع في آخر التعليمات.
never_handle.items	مصفوفة نصوص	5 قيم افتراضية مترجمة	الحالات التي يجب أن يحوّلها الوكيل بدل الإجابة عنها. والقائمة التي أفرغتها تبقى فارغة.
escalation_reply	نص مترجم، ≤ 500 لكل لغة	فارغ	يُرسل حرفيًا عند نجاح تحويل ذي مسؤولية قانونية. والفارغ يعني أن الوكيل يصوغ الرد بنفسه؛ وتقترح لوحة التحكم نصًا يمكنك اعتماده.
business_scope	نص	""	جملة أو جملتان عن الغرض من هذا الوكيل.

لا يمكن لأي تجاوز في الطلبات تغيير هذه الحقول. انظر التحويل لموظف والأمان.

التحويل لموظف (handoff)

الحقل	النوع	الافتراضي	الوصف
ttl_hours	عدد صحيح، 1–720	24	المدة التي يُبقي فيها التحويل المفتوح الذكاءَ الاصطناعي صامتًا. يمدّها الاستلام ورسائل الفريق. القيمة 0 مرفوضة؛ استخدم never_expire.
never_expire	منطقي	false	إبقاء التحويلات مفتوحة حتى يغلقها أحد.
outside_hours	record · withhold	record	خارج ساعات العمل: واصل تسجيل التحويلات بصياغة صادقة (record)، أو أزل transfer_to_human (withhold).
destinations	مصفوفة	[{"type": "desk"}]	وجهة تحويلات الوكيل بالترتيب: desk أو webhook. أما التحويلات التي تطلبها الواجهة البرمجية أو السياسات أو فريقك فتصل دائمًا إلى مكتب التحويل.
notify.emails	مصفوفة عناوين بريد	[]	عناوين تنبيه للتحويلات الجديدة وغير المستلمة (يتطلب إعداد البريد على الخادم).
notify.unclaimed_reminder_minutes	عدد صحيح	10	متى يُرسل handoff.unclaimed لتحويل لم يستلمه أحد.
on_expire	release_with_message · close	release_with_message	عند انتهاء المدة: أعد المحادثة إلى الوكيل مع إشعار، أو أغلقها.
expire_message	نص مترجم	نص افتراضي مدمج	الإشعار الذي يراه العميل عند انتهاء مدة التحويل.

ساعات العمل (business_hours)

الحقل	النوع	الافتراضي	الوصف
enabled	منطقي	false	إخبار الوكيل بأوقات تواجد فريقك.
schedule	مصفوفة	الأحد–الخميس 09:00–17:00	عناصر {day, open, close} حيث day من sun إلى sat والوقت بصيغة 24 ساعة HH:MM. الفترة التي يكون فيها close ≤ open تمتد بعد منتصف الليل وتنتمي إلى يوم افتتاحها. والأيام غير المدرجة مغلقة؛ والتفعيل مع جدول فارغ يعني الفتح الدائم.
out_of_hours_message	نص مترجم	نص افتراضي مدمج	يُستخدم للتحويلات خارج الساعات، ويُرسل ردًا كاملًا مع message_only.
outside_hours_ai	answer · message_only	answer	خارج الساعات: واصل الإجابة بالذكاء الاصطناعي، أو أرسل out_of_hours_message حرفيًا دون أي استدعاء للذكاء الاصطناعي.

تعتمد ساعات العمل على locale.timezone. وعند تفعيلها يُخبَر الوكيل هل فريقك متصل الآن أو متى يعود.

المحادثة (conversation)

الحقل	النوع	الافتراضي	الوصف
history_limit	عدد صحيح، 2–100	12	عدد الرسائل الأخيرة من الجلسة التي يراها النموذج. تبدأ النافذة عند رسالة من العميل.
idle_timeout_minutes	عدد صحيح	30	فترة الخمول التي تبدأ مقطعًا جديدًا. لا تقطع السجل أبدًا.
concurrency	queue · reject · interrupt	queue	السياسة الافتراضية لجلسات الواجهة البرمجية الجديدة. جلسات الودجت تستخدم interrupt.
stream_mode	auto · live · buffered	auto	live يبث كل رمز؛ وbuffered يرسل النص جولةً جولة؛ وauto يبث مباشرة ما لم يكن رد التصعيد مُعدًّا، فيجمّع حينها.

النموذج (model)

الحقل	النوع	الافتراضي	الوصف
provider	openai · anthropic · deepseek · gemini · openai_compatible	افتراضي الخادم	مزوّد النموذج.
model	نص	افتراضي الخادم	معرّف نموذج من GET /v1/models، الذي يعرض أيضًا فئة كل نموذج ووزنه وهل تسمح به خطتك.
credential	auto · platform · pcred_…	auto	auto يستخدم مفتاح المنصة للمزوّد إن وُجد، وإلا مفتاح مشروعك لذلك المزوّد. وpcred_… يثبّت أحد مفاتيح المزوّدين الخاصة بك (الإعدادات ← مزوّدو النماذج، أو POST /v1/provider_credentials).
max_reply_tokens	عدد صحيح	1024	ميزانية الرد المرئي في كل استدعاء للنموذج. وتحصل نماذج التفكير على هامش إضافي تلقائيًا.
temperature	رقم أو null	null	درجة العشوائية، وتُتجاهل في النماذج التي لا تقبلها.
fallback_models	مصفوفة	[]	عناصر {provider, model} تُجرَّب بالترتيب عند فشل النموذج الأساسي.

المتغيرات (variables)

عرّف قيمًا يمررها تطبيقك لكل جلسة أو لكل رسالة، ثم استخدمها بالصيغة {{name}} في التعليمات أو ملاحظات الشخصية:

{
  "variables": [
    { "name": "customer_name", "type": "string", "required": false, "default": "", "secret": false, "client_settable": true, "description": "الاسم الأول، للترحيب" },
    { "name": "loyalty_tier", "type": "string", "required": false, "default": "standard", "secret": false, "client_settable": false, "description": "" },
    { "name": "crm_token", "type": "string", "required": true, "default": "", "secret": true, "client_settable": false, "description": "تستخدمه أداة order_status" }
  ]
}

الحقل	النوع	الافتراضي	الوصف
name	نص	—	^[a-z][a-z0-9_]{0,31}$. البادئة sys محجوزة: {{sys.date}} و{{sys.end_user.name}} مدمجان.
type	string · number · boolean	string	يُتحقق من القيم وفقه.
required	منطقي	false	غياب متغير إلزامي يعيد 422 variable_missing؛ والمتغير غير المعرّف يعيد 422 variable_unknown.
default	من نوع type	""	يُستخدم حين لا تُرسل قيمة. غير مسموح في المتغيرات السرية.
secret	منطقي	false	القيم السرية تُقبل مع كل طلب فقط (ask وmessages)، ولا تُخزَّن ولا تُسجَّل ولا تُعرض على النموذج أبدًا، ولا تُستخدم إلا في ترويسات أدوات HTTP بالصيغة {{var.name}}.
client_settable	منطقي	false	السماح للمتصفحات (رموز العميل والودجت) بتحديد هذا المتغير. لا يجوز للمتغيرات السرية.
description	نص	""	لفريقك.

تصل المتغيرات إلى النموذج بيانات موسومة بوضوح، لا تعليمات.

التجاوزات (overrides)

التجاوزات ممنوعة افتراضيًا. اسرد الحقول التي يجوز تغييرها لطلب ask واحد، أو لجلسة كاملة عبر POST /v1/sessions وPATCH /v1/sessions/{session} (أما التجاوزات لكل رسالة فتصل في الإصدار v1.1):

الحقل	النوع	الافتراضي	الوصف
allowed	مصفوفة	[]	أيٌّ من dialect وtone وinstructions_append وtemperature وmodel وtools_disable وhistory_limit (حتى القيمة المضبوطة).
models	مصفوفة	[]	النماذج التي يجوز للطلب التحول إليها حين يكون model مسموحًا.

لا ترسل التجاوزاتِ إلا المفاتيحُ السرية. ولا يمكن تجاوز never_handle وescalation_reply وصلاحيات الأدوات والوصول المرتبط بالهوية أبدًا. وتجاوز أي حقل غير مدرج يعيد 422 override_not_allowed.

رد الطوارئ (fallback)

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

الودجت (widget)

الحقل	النوع	الافتراضي	الوصف
greeting	نص مترجم	نص افتراضي مدمج	أول رسالة تظهر عند فتح الدردشة.
launcher_label	نص مترجم	نص افتراضي مدمج	النص على زر فتح الدردشة.
theme.accent	لون	#0F766E	لون التمييز في الودجت.
theme.position	start · end	end	زاوية زر الفتح؛ تتبع اتجاه الصفحة (end أسفل اليسار بالعربية، وأسفل اليمين بالإنجليزية).
anonymous_daily_conversations	عدد صحيح	200	الحد اليومي لمحادثات الودجت المجهولة لهذا الوكيل.

لا يقرأ الودجت من الإصدار المنشور إلا bot_name وlanguage والاتجاه وgreeting وlauncher_label وtheme.