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

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

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

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

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

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، فلا يستطيع شخصان (أو سكربتان) الكتابة فوق تغييرات بعضهما:

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) تُطبَّق على المسودة: الكائنات تُدمج، والمصفوفات تُستبدل كاملة، وnull يعيد الحقل إلى قيمته الافتراضية. ثم يُتحقق من النتيجة المدمجة كاملة.
• غياب If-Match يعيد 428 if_match_required، والقيمة القديمة تعيد 412 etag_mismatch: اجلب الوكيل من جديد وأعد تطبيق تعديلك.
• أخطاء التحقق تعيد 422 مع param بمؤشر JSON مثل /tools/max_tool_rounds.

انشر

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 يستخدمها الوكيل. تعديل الأداة لاحقًا لا يغيّر الإصدارات المنشورة: انشر من جديد لاعتماد التعريف الجديد؛
• ملاحظتك، ومن نشر، ومتى.

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

تراجع

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

# 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> يسرد كل حقل تغيّر:

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

{
  "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 تنتقل إلى الإصدار الجديد عند حدّ المقطع التالي — أول رسالة بعد فترة خمول، أو أول رسالة بعد النشر. انظر المقاطع.

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

يسجّل كل تشغيل 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 وأدوات جهة العميل)، ويبقى الرد والتحويل لموظف يعملان.

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

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	القوالب الجاهزة