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

> كل حقل في إعدادات الوكيل — نوعه، وقيمته الافتراضية، وحدوده، ووظيفته — تمامًا كما يعيده GET /v1/agents/{agent}.

إعدادات الوكيل وثيقة JSON واحدة. يعيدها `GET /v1/agents/{agent}` **كاملة** دائمًا، مع ملء كل قيمة افتراضية؛ وتُرفض الحقول غير المعروفة. عدّلها من محرّر الصفحة الواحدة في لوحة التحكم أو عبر [رقعة دمج](/docs/concepts/agents-and-versions/#عدّل-المسودة). ومخطط JSON بأوصاف عربية وإنجليزية متاح عبر `GET /v1/agents/config_schema`.

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

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

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

```json
{
  "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` يحاكي العميل. انظر [اللهجة العربية والنبرة](/docs/guides/arabic-dialect-and-tone/). |
| `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`). انظر [المعرفة](/docs/concepts/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](/docs/guides/http-tools/). |
| `client` | مصفوفة | `[]` | [أدوات جهة العميل](/docs/guides/client-tools/) بالحقول `{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` | نص | `""` | جملة أو جملتان عن الغرض من هذا الوكيل. |

لا يمكن لأي تجاوز في الطلبات تغيير هذه الحقول. انظر [التحويل لموظف والأمان](/docs/concepts/handoff-and-safety/).

## التحويل لموظف (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` | فترة الخمول التي تبدأ [مقطعًا](/docs/concepts/sessions/#السجل-والمقاطع) جديدًا. لا تقطع السجل أبدًا. |
| `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}}` في التعليمات أو ملاحظات الشخصية:

```json
{
  "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`.