# الوكلاء والإصدارات

> كيف تُكتب إعدادات الوكيل في مسودة، وتُنشر إصدارات لا تتغير، وتُقارن ويُتراجع عنها — وكيف تتتبع كل إجابة إلى الإعدادات التي أنتجتها بالضبط.

**الوكيل** مساعد مُعدّ مسبقًا. له اسم، ومعرّف نصي (slug)، ووصف، و**وثيقة إعدادات** واحدة: الهوية واللهجة، والتعليمات، والمعرفة، والأدوات، والضوابط، والتحويل لموظف، وساعات العمل، والمحادثة، والنموذج، والمتغيرات، والتجاوزات، ورد الطوارئ، والودجت. كل حقل مشروح في [مرجع الإعدادات](/docs/concepts/settings/).

- يعيد `GET /v1/agents/{agent}` الإعدادات **كاملة** دائمًا، مع ملء كل قيمة افتراضية. لا يوجد إعداد مخفي.
- تُرفض الحقول غير المعروفة، فلا يمرّ خطأ إملائي دون أن تلاحظه.
- مخطط JSON للإعدادات متاح عبر `GET /v1/agents/config_schema`، مع عناوين وأوصاف بالعربية والإنجليزية لكل حقل.
- `{agent}` في الرابط هو معرّف الوكيل (`agt_…`) أو معرّفه النصي (`store-assistant`). المعرّف النصي يطابق `^[a-z0-9][a-z0-9-]{0,62}$`.

## المسودة والإصدارات

لكل وكيل **مسودة** واحدة قابلة للتعديل وقائمة **إصدارات** مرقّمة لا تتغير:

```text
create ──► v1 (published automatically)
            │
  PATCH the draft … PATCH the draft
            │
  publish ──► v2 ──► publish ──► v3
                        │
  restore v1 into the draft, then publish ──► v4 (same settings as v1)
```

- **إنشاء الوكيل ينشر الإصدار 1 فورًا**، فيعمل أول استدعاء لك دون خطوة إضافية.
- التعديل لا يغيّر أي إصدار منشور. تبقى تغييراتك في المسودة حتى تنشرها.
- يعرض كائن الوكيل `published_version` و`has_unpublished_changes`، فتعرف دائمًا هل تختلف المسودة عمّا هو منشور.

## عدّل المسودة

`PATCH /v1/agents/{agent}` يعدّل المسودة، ويتطلب قيمة etag الحالية للمسودة في `If-Match`، فلا يستطيع شخصان (أو سكربتان) الكتابة فوق تغييرات بعضهما:

```bash
ETAG=$(curl -s https://api.k-agent.kerneltics.com/v1/agents/store-assistant \
  -H "Authorization: Bearer $KAGENT_API_KEY" | jq -r .draft.etag)

curl -X PATCH https://api.k-agent.kerneltics.com/v1/agents/store-assistant \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -d '{
    "config": {
      "identity": { "enabled": true, "bot_name": "مساعد ندى", "dialect": "saudi" },
      "conversation": { "history_limit": 20 }
    }
  }'
```

- يقبل جسم الطلب `name` و`slug` و`description` و`config` و`ai_paused` و`actions_paused`.
- `config` **رقعة دمج JSON** ([RFC 7396](https://www.rfc-editor.org/rfc/rfc7396)) تُطبَّق على المسودة: الكائنات تُدمج، والمصفوفات تُستبدل كاملة، و`null` يعيد الحقل إلى قيمته الافتراضية. ثم يُتحقق من النتيجة المدمجة كاملة.
- غياب `If-Match` يعيد `428 if_match_required`، والقيمة القديمة تعيد `412 etag_mismatch`: اجلب الوكيل من جديد وأعد تطبيق تعديلك.
- أخطاء التحقق تعيد `422` مع `param` بمؤشر JSON مثل `/tools/max_tool_rounds`.

## انشر

```bash
curl https://api.k-agent.kerneltics.com/v1/agents/store-assistant/publish \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "اللهجة السعودية ونافذة سجل أطول"}'
```

النشر ينشئ الإصدار N+1 من المسودة. الإصدار لا يتغير بعد إنشائه، ويحفظ:

- الإعدادات كاملة و`config_hash` — أي `sha256:` متبوعًا بتجزئة SHA-256 لنص JSON القياسي للإعدادات، فتنتج الإعدادات المتطابقة التجزئة نفسها دائمًا؛
- **نسخة من تعريف كل أداة HTTP** يستخدمها الوكيل. تعديل الأداة لاحقًا لا يغيّر الإصدارات المنشورة: انشر من جديد لاعتماد التعريف الجديد؛
- ملاحظتك، ومن نشر، ومتى.

مصادر المعرفة **لا** تُنسخ: هي حيّة لكل الإصدارات، فتحديث قائمة أسعارك يسري دون إصدار جديد.

## تراجع

التراجع استعادةٌ يتبعها نشر:

```bash
# Copy version 1 into the draft…
curl -X POST https://api.k-agent.kerneltics.com/v1/agents/store-assistant/versions/1/restore \
  -H "Authorization: Bearer $KAGENT_API_KEY"

# …then publish it as a new version.
curl https://api.k-agent.kerneltics.com/v1/agents/store-assistant/publish \
  -H "Authorization: Bearer $KAGENT_API_KEY" -H "Content-Type: application/json" \
  -d '{"note": "تراجع إلى الإصدار 1"}'
```

لا يُعاد كتابة التاريخ أبدًا: الإعدادات المستعادة تصبح إصدارًا جديدًا أعلى رقمًا.

## قارن بين الإصدارات

`GET /v1/agents/{agent}/diff?from=<n|draft>&to=<n|draft>` يسرد كل حقل تغيّر:

```bash
curl "https://api.k-agent.kerneltics.com/v1/agents/store-assistant/diff?from=1&to=draft" \
  -H "Authorization: Bearer $KAGENT_API_KEY"
```

```json
{
  "changes": [
    { "path": "/identity/dialect", "kind": "changed", "before": "match", "after": "saudi" },
    { "path": "/conversation/history_limit", "kind": "changed", "before": 12, "after": 20 }
  ]
}
```

يسرد `GET /v1/agents/{agent}/versions` الإصدارات، ويعيد `GET /v1/agents/{agent}/versions/{n}` إصدارًا واحدًا.

## أي إصدار يجيب على الطلب

1. `version: "draft"` يعمل **في جلسات التجربة فقط** (لوحة التجربة في لوحة التحكم، أو `channel: "playground"`)، لمستخدمي لوحة التحكم بدور محرر فأعلى أو للمفاتيح السرية ذات النطاق `agents:write`. وفي غير ذلك يعيد `422 draft_not_allowed`.
2. الجلسة المنشأة بـ `version_policy: "pinned"` مع `version` تبقى على ذلك الإصدار.
3. كل ما عدا ذلك يستخدم **أحدث إصدار منشور**.

الجلسات على السياسة الافتراضية `latest` تنتقل إلى الإصدار الجديد عند حدّ المقطع التالي — أول رسالة بعد فترة خمول، أو أول رسالة بعد النشر. انظر [المقاطع](/docs/concepts/sessions/#السجل-والمقاطع).

## كل إجابة قابلة للتتبع

يسجّل كل تشغيل `agent.version` و`config_hash` و`snapshot_hash` (تجزئة التعليمات وقائمة الأدوات المجمّدة للمحادثة). فتستطيع دائمًا إثبات الإعدادات التي أنتجت إجابة بعينها. ويعرض `GET /v1/runs/{run}/steps` استدعاءات النموذج والأدوات في ذلك التشغيل.

## مفاتيح الإيقاف المؤقت

مفتاحان على المستوى الأعلى يسريان فورًا، دون إصدار جديد ودون `If-Match`:

| الحقل | الأثر |
|---|---|
| `ai_paused` | يوقف ردود الذكاء الاصطناعي فورًا. تعيد طلبات الواجهة البرمجية `409 agent_not_ready` مع العائق `ai_paused`، ويرى زوار الودجت إشعارًا قصيرًا بدل الإجابة. |
| `actions_paused` | يزيل الأدوات ذات الأثر (`create_ticket` وأدوات HTTP من نوع action وأدوات جهة العميل)، ويبقى الرد والتحويل لموظف يعملان. |

يُسجَّل التغييران في سجل التدقيق.

```bash
curl -X PATCH https://api.k-agent.kerneltics.com/v1/agents/store-assistant \
  -H "Authorization: Bearer $KAGENT_API_KEY" -H "Content-Type: application/json" \
  -d '{"actions_paused": true}'
```

## الجاهزية

يحمل كائن الوكيل `readiness: {ready, blockers}`. ما دامت `ready` قيمتها false تعيد طلبات الواجهة البرمجية `409 agent_not_ready` مع العوائق، بدل إجابة ناقصة مربكة:

| العائق | المعنى |
|---|---|
| `no_model_credential` | لم يُربط أي مفتاح API بمزوّد الذكاء الاصطناعي الخاص بالوكيل. |
| `credential_invalid` | رفض المزوّد مفتاح API المرتبط. |
| `model_not_allowed_on_plan` | نموذج الوكيل غير متاح في خطتك. |
| `quota_exhausted` | استُنفدت حصة المحادثات الذكية لهذا الشهر. |
| `ai_paused` | ردود الذكاء الاصطناعي متوقفة مؤقتًا لهذا الوكيل. |
| `provider_unavailable` | مزوّد الذكاء الاصطناعي غير متاح حاليًا. |
| `knowledge_sync_failing` | يتعذّر تحديث أحد مصادر المعرفة. |

مشكلات الإعداد لا تُعاد محاولتها ولا تُحوَّل لموظف كأن المزوّد تعطّل — بل يُبلَّغ عنها لتصلحها.

## القوالب والتصدير و«أشعة إكس»

- يسرد `GET /v1/agent_templates` أربعة وكلاء جاهزين — خدمة العملاء، وأسئلة المبيعات، ومساعد الحجوزات، والأسئلة الداخلية — كلٌّ بإعدادات كاملة ومترجمة. أنشئ من أحدها بـ `POST /v1/agents {"name": "…", "template": "<template id>"}`.
- يعيد `GET /v1/agents/{agent}/export` الإعدادات بصيغة JSON، مع الإشارة إلى الأسرار بأسمائها فقط، وينشئ `POST /v1/agents/import` وكيلًا من ملف كهذا. استخدمهما لحفظ الوكلاء في Git أو نقلهم بين المشاريع.
- `POST /v1/agents/{agent}/prompt_preview` هو **«أشعة إكس» للتعليمات**: التعليمات المجمّعة كتلًا، لكل كتلة مصدرها وإصدارها وتقدير رموزها وهل هي ضمن البادئة القابلة للتخزين المؤقت. وتظهر قواعد المنصة أيضًا — لا شيء مخفي.

## نقاط النهاية

| الطريقة والمسار | الغرض |
|---|---|
| `POST /v1/agents` | إنشاء وكيل (من الصفر أو من `template`)، وينشر الإصدار 1 |
| `GET /v1/agents` | سرد الوكلاء |
| `GET /v1/agents/{agent}` | جلب وكيل بإعدادات مسودته كاملة |
| `PATCH /v1/agents/{agent}` | تعديل المسودة (`If-Match`)، أو تبديل مفاتيح الإيقاف |
| `DELETE /v1/agents/{agent}` | أرشفة الوكيل |
| `POST /v1/agents/{agent}/publish` | نشر المسودة إصدارًا جديدًا |
| `GET /v1/agents/{agent}/versions` | سرد الإصدارات |
| `GET /v1/agents/{agent}/versions/{n}` | جلب إصدار واحد |
| `POST /v1/agents/{agent}/versions/{n}/restore` | نسخ إصدار إلى المسودة |
| `GET /v1/agents/{agent}/diff` | مقارنة إصدارين أو المسودة |
| `GET /v1/agents/{agent}/export` و`POST /v1/agents/import` | التصدير والاستيراد |
| `POST /v1/agents/{agent}/prompt_preview` | «أشعة إكس» للتعليمات |
| `GET /v1/agents/config_schema` | مخطط JSON للإعدادات |
| `GET /v1/agent_templates` | القوالب الجاهزة |