This is the full developer documentation for K-Agent # وكيل واحد. استخدمه في أي مكان. > ابنِ مع K-Agent — أعدّ وكيلًا ذكيًا واحدًا بمعرفتك وأدواتك وقواعد الأمان الخاصة بك، ثم استخدمه عبر الواجهة البرمجية وجلسات المحادثة وحزمة OpenAI وودجت على موقعك. عربي أولًا، وفريقك على بُعد تحويل واحد. ## ابدأ [مقدمة](/docs/get-started/introduction/)ما هو K-Agent، ومكوّناته الأساسية، وما يحدث في الدور الواحد. [البدء السريع](/docs/get-started/quickstart/)أنشئ وكيلًا ومفتاحًا، واطرح سؤالًا، ثم حادث الوكيل في جلسة بمعرّفك الخاص. ## افهم المفاهيم [الجلسات ومعرّفات الجلسات](/docs/concepts/sessions/)معرّفنا sess\_ أو معرّفك external_id: العقد المنشور، والجلب أو الإنشاء، والسجل. [التشغيلات والبث](/docs/concepts/runs-and-streaming/)دورة حياة التشغيل، وقائمة الأحداث، والاستئناف بـ Last-Event-ID. [التحويل لموظف والأمان](/docs/concepts/handoff-and-safety/)قائمة «لا تتعامل معها بنفسك»، والرد الحرفي عند التصعيد، والتحويل الصادق. [مرجع الإعدادات](/docs/concepts/settings/)كل حقل في الإعدادات بنوعه وقيمته الافتراضية وحدوده. ## ابنِ [أضف ودجت الدردشة](/docs/guides/widget/)سطر script واحد، وعملاء موثّقون برموز العميل. [استخدم حزمة OpenAI](/docs/guides/openai-sdk/)احتفظ بكود OpenAI الخاص بك: معرّف الوكيل هو اسم النموذج. [أدوات HTTP](/docs/guides/http-tools/)دع الوكيل يستدعي واجهتك البرمجية بأمان. [الويب هوك](/docs/guides/webhooks/)أحداث موقّعة للتحويلات والردود والتذاكر. ## ارجع إلى المرجع [الأخطاء](/docs/reference/errors/)كل رمز خطأ، ومعناه، وما العمل. [مرجع الواجهة البرمجية](/docs/api/)كل نقاط النهاية، مولّدة من عقد OpenAPI. تبني بمساعدة مساعد ذكاء اصطناعي؟ وجّهه إلى [`/docs/llms.txt`](/docs/llms.txt)، أو إلى [`/docs/llms-full.txt`](/docs/llms-full.txt) ليحصل على التوثيق العربي كاملًا في ملف واحد. ولكل صفحة زر **نسخ الصفحة** ونسخة بصيغة Markdown. # مقدمة > ما هو K-Agent، وما مكوّناته الأساسية، وكيف يمرّ الطلب الواحد من الكود الخاص بك حتى يصل الرد. **K-Agent** منصة وكلاء ذكاء اصطناعي من Kerneltics. تُعدّ الوكيل مرة واحدة — هويته ولهجته، وتعليماته، ومعرفته، وأدواته، وضوابطه، وساعات العمل، وقواعد التحويل لموظف — ثم تستخدم الوكيل نفسه في كل مكان: من الخادم الخاص بك، وفي جلسات المحادثة، وعبر حزم OpenAI، وفي ودجت دردشة على موقعك، مع فريقك جاهزًا لاستلام المحادثة عندما يلزم إنسان. صُمّمت المنصة للعربية أولًا، للسعودية والخليج. كل إعداد ورسالة وخطأ متاح بالعربية والإنجليزية، والردود تتبع اللهجة التي تختارها. ## طرق استخدام وكيلك | نقطة الدخول | الغرض | الطريقة | | --------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | **سؤال واحد** | سؤال يدخل وجواب يخرج، بلا حالة محادثة. | `POST /v1/agents/{agent}/ask` | | **جلسات المحادثة** | محادثات مستمرة بسجلّ كامل، بمعرّفنا `sess_…` أو بمعرّفك الخاص `external_id`. | `POST /v1/sessions` ثم `POST /v1/sessions/{session}/messages` | | **البث المباشر** | عرض الرد أثناء كتابته عبر Server-Sent Events. | `"stream": true` في السؤال والجلسات والرسائل | | **واجهة متوافقة مع OpenAI** | احتفظ بكود حزمة OpenAI، ووجّهه إلى K-Agent، واستخدم معرّف الوكيل النصي (slug) اسمًا للنموذج. | `/openai/v1/chat/completions` | | **ودجت الدردشة** | فقاعة دردشة لموقعك، للزوار المجهولين والمستخدمين المسجّلين. | وسم ` ``` هذا كل ما يلزم للزوار المجهولين. يحمّل الودجت إعدادات الوكيل **المنشورة** — `bot_name` و`greeting` و`launcher_label` و`theme.accent` و`theme.position` — فتغيّر مظهره من محرّر الوكيل لا من الكود. | خاصية السكربت | الوصف | | ------------- | ----------------------------------------------------------------------------- | | `data-agent` | معرّف الوكيل. | | `data-key` | مفتاحك القابل للنشر. | | `data-api` | اختيارية. مصدر الواجهة البرمجية، إن كان مختلفًا عن المصدر الذي يقدّم السكربت. | ### أو ضع العنصر بنفسك للتحكم في مكان الدردشة وطريقة ظهورها، حمّل السكربت دون `data-agent` وأضف العنصر: ```html ``` | خاصية العنصر | الوصف | | ----------------- | ----------------------------------------------------------------------------------------------------------------- | | `agent` | معرّف الوكيل. إلزامية. | | `publishable-key` | مفتاحك القابل للنشر. | | `token-endpoint` | رابط في موقعك يعيد رمز عميل للمستخدم المسجّل (الخطوة 3). | | `api-base` | مصدر الواجهة البرمجية، اختيارية. | | `lang` | `ar` أو `en`. الافتراضي خاصية `lang` في العنصر، ثم ``، ثم لغة الوكيل. والعربية تُعرض من اليمين لليسار. | | `position` | `start` أو `end` (الافتراضي). تتبع اتجاه الصفحة: `end` أسفل اليسار بالعربية وأسفل اليمين بالإنجليزية. | | `open` | وجودها يفتح الدردشة من البداية. | ## ما يحصل عليه الزوار * تتدفق الردود أثناء كتابتها، وتظهر رسائل الزوار والوكلاء بالاتجاه المناسب للغتها. * تُحفظ المحادثة لكل متصفح: الزائر الذي يعود من الجهاز نفسه يكمل من حيث توقف. وخيار **محادثة جديدة** يبدأ من الصفر. * أثناء التحويل يوضح رأس الدردشة أن موظفًا أصبح في المحادثة، وتظهر ردود فريقك مباشرة. * الودجت يعمل جيدًا مع لوحة المفاتيح وقارئات الشاشة، ويملأ الشاشة على الجوال. ### الزوار المجهولون الزوار غير المسجّلين **عملاء مجهولون**. ولسلامتهم وسلامتك: * الأدوات ذات الأثر معطّلة ما لم يفعّل الوكيل `tools.allow_anonymous_actions`؛ * الأدوات التي تحتاج هوية موثّقة لا تعمل أبدًا؛ * تنطبق حدود: لكل عنوان IP، 20 محادثة و60 رسالة في الساعة؛ و40 رسالة كحد أقصى في المحادثة الواحدة؛ و`widget.anonymous_daily_conversations` لكل وكيل (الافتراضي 200). وبعد بلوغ الحد يرى الزائر رسالة مهذبة بالمحاولة لاحقًا. ## 3. المستخدمون المسجّلون (موثّقون) حين يكون الزائر مسجّلًا الدخول في موقعك، دعه يحادث الوكيل **بهويته**: يستطيع الوكيل حينها استخدام الأدوات المرتبطة بالهوية («وين *طلبي*؟»)، وتذكّر إجراءاته السابقة، ويعرف فريقك من هو. يصدر خادمك **رمز عميل** قصير العمر للمستخدم بمفتاحك السري، ويجلبه الودجت من `token-endpoint` في موقعك. المفتاح السري لا يصل إلى المتصفح أبدًا. ```html ``` يرسل الودجت طلب `POST` إلى `token-endpoint` من صفحتك (مع ملفات تعريف الارتباط الخاصة بموقعك، كطلب من المصدر نفسه)، ويتوقع JSON يحوي `token` و`expires_at`، كما يعيدهما `POST /v1/client_tokens` بالضبط. ويطلب رمزًا جديدًا قبل انتهاء صلاحية الرمز. * JavaScript ```js // Node.js + Express. `requireLogin` is your own authentication middleware. import express from 'express'; const app = express(); app.post('/kagent/token', requireLogin, async (req, res) => { const r = await fetch('https://api.k-agent.kerneltics.com/v1/client_tokens', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KAGENT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ agent: 'agt_01k6rz1m3w8q4t7v9x2b5c0dnf', end_user: { external_id: req.user.customerId, // your stable ID — never an email or phone name: req.user.firstName, traits: { plan: req.user.plan }, }, ttl_seconds: 900, }), }); if (!r.ok) return res.status(502).json({ error: 'token_unavailable' }); const { token, expires_at } = await r.json(); res.set('Cache-Control', 'no-store').json({ token, expires_at }); }); ``` * Python ```python # Flask. `login_required` and `current_user` come from your own auth (e.g. Flask-Login). import os import requests from flask import Flask app = Flask(__name__) @app.post("/kagent/token") @login_required def kagent_token(): r = requests.post( "https://api.k-agent.kerneltics.com/v1/client_tokens", headers={"Authorization": f"Bearer {os.environ['KAGENT_API_KEY']}"}, json={ "agent": "agt_01k6rz1m3w8q4t7v9x2b5c0dnf", "end_user": { "external_id": current_user.customer_id, # never an email or phone "name": current_user.first_name, "traits": {"plan": current_user.plan}, }, "ttl_seconds": 900, }, timeout=10, ) if not r.ok: return {"error": "token_unavailable"}, 502 data = r.json() return {"token": data["token"], "expires_at": data["expires_at"]}, 200, {"Cache-Control": "no-store"} ``` - احمِ نقطة النهاية بتسجيل الدخول المعتاد لديك، ولا تصدر الرموز إلا للمستخدم المسجّل نفسه. فالرمز يتيح لحامله المحادثة بصفة ذلك الشخص لمدة `ttl_seconds` (3600 كحد أقصى؛ و900 قيمة افتراضية جيدة). - استخدم معرّفًا `external_id` ثابتًا ومبهمًا للمستخدم. وإن كان مفتاحك الوحيد بريدًا أو رقم جوال [فاشتقّ منه معرّفًا بالتجزئة](/docs/concepts/sessions/#%D9%84%D8%A7-%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%B4%D8%AE%D8%B5%D9%8A%D8%A9-%D9%81%D9%8A-%D8%A7%D9%84%D9%85%D8%B9%D8%B1%D9%91%D9%81%D8%A7%D8%AA). - لمواصلة محادثة بعينها أضف `"session": ""` عند إصدار الرمز. - لتمرير قيم المتغيرات التي يعرّفها الوكيل بخاصية `client_settable` أضف `"variables": {…}`. - يتوقف الرمز عن العمل عند انتهاء صلاحيته، أو عند إلغاء المفتاح الذي أصدره، أو عند محو العميل. ## سياسة أمان المحتوى (CSP) إذا كان موقعك يرسل ترويسة CSP فاسمح بسكربت الودجت وطلباته إلى الواجهة البرمجية: ```text script-src 'self' https://api.k-agent.kerneltics.com; connect-src 'self' https://api.k-agent.kerneltics.com; ``` ## حل المشكلات | الخطأ | السبب والحل | | ----------------------------- | ---------------------------------------------------------------------------------------- | | `403 origin_not_allowed` | مصدر الصفحة غير مدرج في قائمة المفتاح. أضفه بالضبط، بما في ذلك المنفذ. | | `403 origin_required` | لم يصدر الطلب من صفحة في متصفح. المفاتيح القابلة للنشر لا تعمل إلا في المتصفحات. | | `403 principal_not_allowed` | استدعت بيانات اعتماد المتصفح مسارًا لا يُسمح لها به. نفّذ هذا الطلب من خادمك بمفتاح سري. | | `401 token_expired` | أعادت نقطة الرموز رمزًا منتهي الصلاحية، أو ساعة خادمك غير مضبوطة. | | `429 anonymous_limit_reached` | بلغ زائر مجهول أحد الحدود. أما المستخدمون المسجّلون برموز العميل فلا يخضعون لهذه الحدود. | # الأخطاء > غلاف الخطأ، وأنواع الأخطاء وحالات HTTP، وإرشادات إعادة المحاولة، وكل رمز خطأ تعيده واجهة K-Agent البرمجية — معناه وما العمل. كل خطأ من واجهة K-Agent البرمجية له الشكل نفسه، ورمز `code` ثابت تستطيع البناء عليه، ورسالة مكتوبة للناس بالعربية أو الإنجليزية. ## غلاف الخطأ ```json { "error": { "type": "conflict_error", "code": "session_busy", "message": "الجلسة مشغولة بالرد على رسالة أخرى. أعد المحاولة بعد لحظات.", "request_id": "req_01k6rz9f1j3m5p7r9t1w3y5a7c", "doc_url": "https://k-agent.kerneltics.com/docs/en/reference/errors/#session_busy" } } ``` | الحقل | الوصف | | ------------ | ------------------------------------------------------------------------------------------------------------------ | | `type` | الفئة العامة، أدناه. | | `code` | ثابت، بصيغة `snake_case`. **ابنِ عليه.** قد تُضاف رموز جديدة؛ فتعامل مع الرموز غير المعروفة حسب `type` وحالة HTTP. | | `message` | للناس، بلغة `Accept-Language` ‏(`ar` أو `en`). قد تتغير في أي وقت — لا تحلّلها أبدًا. | | `param` | يظهر حين يكون الخطأ في معامل واحد: اسم حقل، أو مؤشر JSON مثل `/tools/max_tool_rounds`. | | `request_id` | القيمة نفسها التي في ترويسة الاستجابة `Request-Id`. اذكرها عند التواصل مع الدعم. | | `doc_url` | رابط إلى هذه الصفحة، عند صف الرمز (النسخة الإنجليزية؛ والصفوف نفسها هنا بالعربية). | ## الأنواع والحالات | `type` | حالة HTTP | المعنى | | ----------------------- | -------------------------------------------------------------------- | -------------------------------------------------------- | | `invalid_request_error` | 400 (طلب مشوّه)، و422 (مفهوم لكنه غير صالح)، إضافة إلى 405 و413 و428 | أصلح الطلب. | | `authentication_error` | 401 | بيانات الاعتماد مفقودة أو غير صالحة أو منتهية أو مُلغاة. | | `permission_error` | 403 | بيانات الاعتماد صالحة لكنها لا تملك هذا الإذن. | | `not_found_error` | 404 | غير موجود — أو تابع لمشروع آخر أو لعميل آخر. | | `conflict_error` | 409، أو 412 عند قيمة `If-Match` قديمة | الحالة الراهنة لا تسمح بالطلب. | | `rate_limit_error` | 429 | طلبات كثيرة جدًا؛ انتظر `Retry-After`. | | `quota_error` | 429 | بُلغ حد في الخطة أو في التكلفة. | | `provider_error` | 502 | فشل مزوّد الذكاء الاصطناعي. | | `api_error` | 500 و503 | حدث خطأ من جهتنا. | ## إعادة المحاولة بأمان * **أعد المحاولة** عند `429` بعد ثواني `Retry-After`، وعند `409 session_busy` و`session_queue_full` و`idempotency_in_progress` بعد مهلة قصيرة، وعند `500` و`502` و`503` بفواصل متزايدة. والرموز الموسومة بـ *قابل لإعادة المحاولة* أدناه هي التي تستحق ذلك. * **لا تُعد المحاولة** حين تحمل الاستجابة `x-should-retry: false` (مثل `quota_exceeded`)، ولا عند أخطاء `4xx` الأخرى — أصلح الطلب أولًا. * **أرسل دائمًا `Idempotency-Key`** مع طلبات POST التي قد تعيدها، فلا تنشئ إعادة المحاولة أبدًا رسالة أو جلسة أو تذكرة ثانية. انظر [عدم التكرار](/docs/reference/idempotency/). ## الأخطاء في البث الأخطاء التي تقع قبل بدء البث استجابات JSON عادية. وبعد بدئه ينتهي التشغيل الفاشل بحدث `run.failed` يحمل `run.error`، ولا يُستخدم حدث `error` إلا لأعطال البث (`token_expired` و`stream_timeout` و`internal_error`). انظر [التشغيلات والبث](/docs/concepts/runs-and-streaming/#%D8%A7%D9%84%D8%A3%D8%AE%D8%B7%D8%A7%D8%A1-%D9%88%D8%A7%D9%84%D8%AD%D8%A7%D9%84%D8%A7%D8%AA-%D8%A7%D9%84%D8%AE%D8%A7%D8%B5%D8%A9). ## رموز الأخطاء ### طلب غير صالح (400 و405 و413 و422 و428) | الرمز | المعنى · ما العمل | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`allowed_origins_required`](#allowed_origins_required) HTTP 422 | يحتاج المفتاح القابل للنشر إلى مصدر مسموح به واحد على الأقل، مثل https\://www\.example.com.ما العمل: أضف مصدرًا واحدًا على الأقل بالصيغة `scheme://host[:port]` إلى `allowed_origins` في المفتاح القابل للنشر. | | [`credential_invalid`](#credential_invalid) HTTP 422 | رفض مزوّد الذكاء الاصطناعي هذا المفتاح. تحقّق منه ثم أعد المحاولة.ما العمل: رفض المزوّد المفتاح أثناء التحقق المباشر. انسخ المفتاح مجددًا من لوحة المزوّد وتأكد من أنه يستطيع استدعاء النموذج المختار. | | [`draft_not_allowed`](#draft_not_allowed) HTTP 422 | لا يمكن تشغيل المسودة إلا في جلسات التجربة.ما العمل: لا يعمل `version: "draft"` إلا في جلسات التجربة (`channel: "playground"`) لمن لديه دور محرر أو مفتاح بنطاق `agents:write`. انشر الإصدار لتستخدم التغييرات في أي مكان آخر. | | [`external_id_invalid`](#external_id_invalid) HTTP 422 | صيغة المعرّف الخارجي (external_id) غير صالحة. استخدم من 1 إلى 128 من الحروف اللاتينية أو الأرقام أو الرموز . \_ : -، على أن يبدأ بحرف أو رقم. لا يجوز أن يبدأ معرّف الجلسة بـ sess\_ ولا معرّف العميل بـ eu\_.ما العمل: استخدم من 1 إلى 128 حرفًا من `A–Z a–z 0–9 . _ : -`، تبدأ بحرف أو رقم. ولا يبدأ معرّف الجلسة بـ `sess_`، ولا معرّف العميل بـ `eu_`. | | [`idempotency_key_reused`](#idempotency_key_reused) HTTP 422 | سبق استخدام مفتاح Idempotency-Key هذا مع طلب مختلف. استخدم مفتاحًا جديدًا لكل طلب جديد.ما العمل: استخدم `Idempotency-Key` جديدًا لكل طلب مختلف، ولا تُعِد استخدام المفتاح إلا لإعادة الطلب نفسه حرفيًا. | | [`identity_as_parameter`](#identity_as_parameter) HTTP 422 | يجب ألا تطلب الأدوات التي تشترط عميلًا موثّقًا بيانات الهوية من النموذج، مثل رقم الجوال أو البريد الإلكتروني. استخدم العناصر النائبة end_user بدلًا من ذلك.ما العمل: احذف معاملات الجوال أو البريد أو معرّف المستخدم من الأدوات التي تشترط عميلًا موثّقًا، واستخدم العناصر النائبة `{{end_user.external_id}}` أو `{{end_user.traits.*}}` بدلًا منها. | | [`if_match_required`](#if_match_required) HTTP 428 | يتطلب هذا التعديل ترويسة If-Match تحمل قيمة etag الحالية.ما العمل: أرسل `If-Match: ` بقيمة etag الحالية للمسودة عند تعديل إعدادات الوكيل عبر `PATCH`. | | [`input_too_large`](#input_too_large) HTTP 413 | النص المُدخل أطول من المسموح.ما العمل: اختصر النص: الحد 4,000 حرف مع بيانات اعتماد المتصفح، و32,000 حرف مع المفتاح السري. | | [`invalid_api_version`](#invalid_api_version) HTTP 400 | تشير الترويسة K-Agent-Version إلى إصدار API غير معروف.ما العمل: أرسل `K-Agent-Version: 2026-10-06`، أو احذف الترويسة. | | [`invalid_cursor`](#invalid_cursor) HTTP 400 | مؤشر التصفح غير صالح لهذه القائمة.ما العمل: استخدم `first_id` أو `last_id` من صفحة سابقة للقائمة نفسها، ولا ترسل `after` و`before` معًا. | | [`invalid_idempotency_key`](#invalid_idempotency_key) HTTP 400 | يجب أن يتراوح طول الترويسة Idempotency-Key بين 1 و255 حرفًا.ما العمل: اجعل طول `Idempotency-Key` بين 1 و255 حرفًا؛ معرّف UUID خيار مناسب. | | [`invalid_json`](#invalid_json) HTTP 400 | محتوى الطلب ليس بصيغة JSON صحيحة.ما العمل: أرسل محتوى JSON صحيحًا. تحقّق من علامات التنصيص والفواصل الزائدة. | | [`invalid_parameter`](#invalid_parameter) HTTP 400 | قيمة المعامل "{param}" غير صالحة.ما العمل: صحّح القيمة المذكورة في `param`؛ يسرد مرجع الواجهة البرمجية القيم المسموح بها. | | [`method_not_allowed`](#method_not_allowed) HTTP 405 | لا تدعم نقطة الوصول هذه طريقة HTTP المستخدمة.ما العمل: استخدم طريقة HTTP الموضحة لهذا المسار في مرجع الواجهة البرمجية. | | [`model_not_allowed_on_plan`](#model_not_allowed_on_plan) HTTP 422 | هذا النموذج غير متاح في خطتك الحالية.ما العمل: اختر نموذجًا تسمح به خطتك (يعرض `GET /v1/models` الحقل `allowed_on_plan`) أو رقِّ خطتك. | | [`override_not_allowed`](#override_not_allowed) HTTP 422 | لا يسمح هذا الوكيل بتغيير هذا الإعداد في كل طلب على حدة.ما العمل: أضف الحقل إلى `overrides.allowed` في الوكيل (والنموذج إلى `overrides.models`)، ثم انشر وأعد المحاولة. لا يمكن تجاوز `never_handle` و`escalation_reply` وصلاحيات الأدوات أبدًا. | | [`placeholder_unresolved`](#placeholder_unresolved) HTTP 422 | لم تتوفر قيمة لأحد العناصر النائبة في رابط الأداة أو ترويساتها أو محتواها، لذا لم يُنفَّذ الاستدعاء.ما العمل: عنصر نائب `{{…}}` في رابط الأداة أو ترويساتها أو جسمها بلا قيمة، فلم يُرسل شيء. اجعل المعامل إلزاميًا، أو مرّر المتغير، أو تحقّق من خصائص العميل. | | [`project_mismatch`](#project_mismatch) HTTP 400 | تشير الترويسة X-Project-Id إلى مشروع غير المشروع الذي يتبع له هذا المفتاح أو الرمز.ما العمل: مفاتيح API والرموز تنتمي إلى مشروع بالفعل. احذف الترويسة `X-Project-Id`، أو استخدم مفتاحًا من ذلك المشروع. | | [`project_required`](#project_required) HTTP 400 | حدّد المشروع بإرسال معرّفه في الترويسة X-Project-Id.ما العمل: يجب أن ترسل طلبات لوحة التحكم المعتمدة على الكوكيز الترويسة `X-Project-Id`. أما مع مفتاح API فالمشروع يُستنتج من المفتاح. | | [`reference_not_found`](#reference_not_found) HTTP 422 | تشير الإعدادات إلى عنصر غير موجود في هذا المشروع.ما العمل: تشير الإعدادات إلى معرّف (`tool_…` أو `ks_…` أو `pcred_…`) غير موجود في هذا المشروع. أنشئ العنصر أولًا أو صحّح المرجع. | | [`request_too_large`](#request_too_large) HTTP 413 | حجم محتوى الطلب أكبر من المسموح.ما العمل: أبقِ حجم محتوى الطلب أقل من 1 ميغابايت (5 ميغابايت لمصادر المعرفة). | | [`secret_host_not_allowed`](#secret_host_not_allowed) HTTP 422 | لا يمكن إرسال السر إلا إلى المضيفات المدرجة في allowed_hosts الخاصة به.ما العمل: أضف مضيف الأداة إلى `allowed_hosts` في السر، أو استخدم سرًا مستقلًا لذلك المضيف. | | [`secret_variable_not_persistable`](#secret_variable_not_persistable) HTTP 422 | لا تُرسَل المتغيرات السرية إلا مع رسالة واحدة أو طلب سؤال واحد، ولا تُخزَّن في الجلسة أبدًا.ما العمل: أرسل المتغيرات السرية مع كل طلب (`ask` أو `messages`)، وليس مع `POST /v1/sessions` أو `PATCH`. | | [`system_message_not_allowed`](#system_message_not_allowed) HTTP 400 | لا تُقبل رسائل system وdeveloper، إذ تسري تعليمات الوكيل نفسه.ما العمل: احذف رسائل `system` و`developer` وضع التعليمات في إعدادات الوكيل. إذا سمح الوكيل بتجاوز `instructions_append` فستُستخدم تعليماتٍ لهذا الطلب. | | [`tool_name_conflict`](#tool_name_conflict) HTTP 422 | تستخدم أداةٌ أخرى لدى هذا الوكيل الاسمَ نفسه.ما العمل: غيّر اسم الأداة: يجب أن يكون الاسم فريدًا بين الأدوات المدمجة وأدوات HTTP وأدوات جهة العميل لدى الوكيل. | | [`tool_not_declared`](#tool_not_declared) HTTP 400 | يتضمن الطلب أداة لم يعرّفها الوكيل ضمن أدوات جهة العميل.ما العمل: لا ترسل في `tools` إلا الأدوات التي يعرّفها الوكيل ضمن أدوات جهة العميل، وبالأسماء نفسها. | | [`tool_outputs_incomplete`](#tool_outputs_incomplete) HTTP 422 | أرسل نتيجة لكل استدعاء أداة معلّق.ما العمل: أرسل نتيجة واحدة لكل `call_id` في `required_action.tool_calls`. | | [`tools_not_allowed_with_session`](#tools_not_allowed_with_session) HTTP 400 | لا يمكن إرسال أدوات جهة العميل عندما يكون الطلب مرتبطًا بجلسة.ما العمل: احذف `tools` من طلبات الواجهة المتوافقة مع OpenAI المرتبطة بجلسة، أو استدعِ بدون جلسة. | | [`unknown_event_type`](#unknown_event_type) HTTP 422 | تحتوي قائمة الأحداث على نوع غير موجود في دليل الأحداث. استخدم أنواع الأحداث الموجودة في الدليل أو \["\*"].ما العمل: لا تشترك إلا في أنواع الأحداث الواردة في قائمة دليل الويب هوك، أو في `["*"]` لكلها. | | [`unknown_field`](#unknown_field) HTTP 400 | الحقل "{param}" غير معروف.ما العمل: احذف الحقل المذكور في `param`. تُرفض الحقول غير المعروفة حتى لا يمر خطأ إملائي دون أن تلاحظه. | | [`unknown_model`](#unknown_model) HTTP 422 | هذا النموذج غير معروف.ما العمل: استخدم معرّف نموذج من `GET /v1/models`. | | [`unsupported_content_type`](#unsupported_content_type) HTTP 422 | المحتوى النصي فقط هو المدعوم.ما العمل: أرسل نصًا فقط: `input` كسلسلة نصية أو بالصيغة `[{"type":"text","text":"…"}]`. | | [`unsupported_parameter`](#unsupported_parameter) HTTP 400 | يستخدم الطلب معاملًا غير مدعوم.ما العمل: احذف `n` الأكبر من 1 و`logprobs` و`response_format: json_schema` من طلبات الواجهة المتوافقة مع OpenAI. | | [`url_not_allowed`](#url_not_allowed) HTTP 422 | هذا الرابط غير مسموح به. استخدم عنوانًا عامًا يبدأ بـ https\://.ما العمل: استخدم عنوانًا عامًا يبدأ بـ `https://` على المنفذ 443 أو 8443. العناوين الخاصة وعناوين الحلقة المحلية وبيانات السحابة الوصفية محظورة. | | [`validation_failed`](#validation_failed) HTTP 422 | يحتوي الطلب على قيمة غير صالحة.ما العمل: صحّح القيمة في مؤشر JSON المذكور في `param`؛ وتوضح الرسالة سبب الخطأ. | | [`variable_missing`](#variable_missing) HTTP 422 | لم تُرسَل قيمة أحد المتغيرات الإلزامية.ما العمل: أرسل كل متغير يحدده الوكيل كمتغير إلزامي (`required`). | | [`variable_unknown`](#variable_unknown) HTTP 422 | يحدد الطلب متغيرًا لم يُعرَّف في إعدادات هذا الوكيل.ما العمل: لا ترسل إلا المتغيرات التي يعرّفها الوكيل، وتحقّق من كتابة أسمائها. | | [`webhook_endpoint_limit_reached`](#webhook_endpoint_limit_reached) HTTP 422 | بلغ هذا المشروع الحد الأقصى لعدد نقاط استقبال الويب هوك.ما العمل: للمشروع 10 نقاط استقبال ويب هوك كحد أقصى. احذف إحداها، أو اشترك بنقطة موجودة في أحداث إضافية. | ### التحقق من الهوية (401) | الرمز | المعنى · ما العمل | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`authentication_required`](#authentication_required) HTTP 401 | يلزم التحقق من الهوية. أرسل مفتاح API في الترويسة Authorization بالصيغة "Bearer \".ما العمل: أرسل الترويسة `Authorization: Bearer ` مع مفتاح سري أو مفتاح قابل للنشر أو رمز عميل. | | [`invalid_api_key`](#invalid_api_key) HTTP 401 | مفتاح API غير صالح أو منتهي الصلاحية أو مُلغى.ما العمل: المفتاح مكتوب خطأً أو منتهي الصلاحية أو مُستبدل أو مُلغى. أنشئ مفتاحًا جديدًا أو استبدله من لوحة التحكم. | | [`invalid_client_token`](#invalid_client_token) HTTP 401 | رمز العميل غير صالح.ما العمل: أصدر رمز عميل جديدًا من خادمك عبر `POST /v1/client_tokens`. | | [`invalid_credentials`](#invalid_credentials) HTTP 401 | البريد الإلكتروني أو كلمة المرور غير صحيحة.ما العمل: تحقّق من البريد وكلمة المرور. المحاولات الفاشلة المتكررة تخضع لحد المعدّل. | | [`token_expired`](#token_expired) HTTP 401 | انتهت صلاحية رمز العميل. اطلب رمزًا جديدًا.ما العمل: احصل على رمز عميل جديد (في الودجت: `POST /v1/widget/token/refresh`، ومن خادمك: `POST /v1/client_tokens`) وأعد فتح البث مع `Last-Event-ID`. يصل هذا الرمز إلى البث المفتوح كحدث `error`. | ### الصلاحيات (403) | الرمز | المعنى · ما العمل | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`csrf_check_failed`](#csrf_check_failed) HTTP 403 | حُظر هذا الطلب لأنه صادر من موقع آخر.ما العمل: يجب أن تكون طلبات لوحة التحكم المعتمدة على الكوكيز من المصدر نفسه وبصيغة JSON. استخدم مفتاح API في تكاملات الخادم بدل الكوكيز. | | [`insufficient_scope`](#insufficient_scope) HTTP 403 | لا يملك مفتاح API هذا النطاقات (scopes) التي يتطلبها الطلب.ما العمل: استخدم مفتاحًا يملك النطاق الذي يتطلبه هذا المسار (مثل `runs:write` أو `sessions:read`)، أو مفتاحًا بصلاحيات `permissions: "all"`. | | [`origin_not_allowed`](#origin_not_allowed) HTTP 403 | مصدر هذا الموقع غير مسموح به لهذا المفتاح. أضفه إلى المصادر المسموح بها في إعدادات المفتاح.ما العمل: أضف هذا المصدر بالضبط (`scheme://host[:port]`) إلى `allowed_origins` في المفتاح القابل للنشر. | | [`origin_required`](#origin_required) HTTP 403 | يجب أن تصدر الطلبات التي تستخدم مفتاحًا قابلًا للنشر من متصفح يرسل الترويسة Origin.ما العمل: لا تعمل المفاتيح القابلة للنشر إلا من المتصفحات، لأنها ترسل الترويسة `Origin`. من الخادم استخدم مفتاحًا سريًا. | | [`permission_denied`](#permission_denied) HTTP 403 | ليست لديك صلاحية لتنفيذ هذا الإجراء. الصلاحية المطلوبة: {permission}.ما العمل: لا يشمل دورك الصلاحية المذكورة في الرسالة. اطلب من أحد المسؤولين دورًا يتضمنها. | | [`principal_not_allowed`](#principal_not_allowed) HTTP 403 | لا يمكن استخدام هذا النوع من بيانات الاعتماد مع نقطة الوصول هذه.ما العمل: يتطلب هذا المسار مفتاحًا سريًا أو مستخدمًا في لوحة التحكم. المفاتيح القابلة للنشر ورموز العميل لا تستدعي إلا مسارات المتصفح المذكورة في صفحة «العملاء والهوية». | | [`signup_closed`](#signup_closed) HTTP 403 | التسجيل مغلق على هذا الخادم. اطلب دعوة من أحد المسؤولين.ما العمل: اطلب دعوة من أحد المسؤولين. | ### غير موجود (404) | الرمز | المعنى · ما العمل | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`project_not_found`](#project_not_found) HTTP 404 | لم يُعثر على المشروع، أو أنك لست عضوًا فيه. تحقّق من الترويسة X-Project-Id.ما العمل: تحقّق من الترويسة `X-Project-Id`: المشروع غير موجود، أو لست عضوًا في منظمته. | | [`resource_not_found`](#resource_not_found) HTTP 404 | تعذّر العثور على {resource}.ما العمل: تحقّق من المعرّف أو الـ slug. العناصر التابعة لمشروع آخر أو لعميل آخر تعيد 404 أيضًا. | | [`route_not_found`](#route_not_found) HTTP 404 | لا توجد نقطة وصول بهذا المسار. تحقّق من الرابط في مرجع API.ما العمل: طابق المسار مع مرجع الواجهة البرمجية، بما في ذلك البادئة `/v1`. | | [`session_not_found`](#session_not_found) HTTP 404 | لم يُعثر على الجلسة. أنشئ الجلسات عبر POST /v1/sessions، ثم استخدم معرّفها أو معرّفك الخارجي (external_id).ما العمل: أنشئ الجلسات عبر `POST /v1/sessions` (جلب أو إنشاء)، ثم خاطبها بمعرّف `sess_…` أو بمعرّفك `external_id`. | ### تعارض (409 و412) | الرمز | المعنى · ما العمل | | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`agent_archived`](#agent_archived) HTTP 409 | هذا الوكيل مؤرشف ولم يعد يرد على الرسائل الجديدة.ما العمل: أُرشف هذا الوكيل (`DELETE /v1/agents/{agent}`). استخدم وكيلًا آخر، أو أنشئ وكيلًا جديدًا من ملف تصديره. | | [`agent_not_ready`](#agent_not_ready) HTTP 409 | الوكيل غير جاهز للرد بعد. راجع العوائق المذكورة في حالة جاهزيته.ما العمل: راجع `readiness.blockers` في كائن الوكيل (`GET /v1/agents/{agent}`): اربط مفتاح المزوّد، أو اختر نموذجًا تسمح به خطتك، أو أوقف `ai_paused`. لن تفيد إعادة المحاولة قبل إزالة العائق. | | [`already_member`](#already_member) HTTP 409 | هذا الشخص عضو في المؤسسة بالفعل.ما العمل: الشخص عضو في المنظمة بالفعل؛ غيّر دوره بدلًا من ذلك. | | [`client_message_id_conflict`](#client_message_id_conflict) HTTP 409 | سبق استخدام المعرّف client_message_id هذا لرسالة مختلفة.ما العمل: أعدت استخدام `client_message_id` مع محتوى مختلف. أنشئ معرّفًا جديدًا لكل رسالة جديدة، ولا تُعِد استخدامه إلا لإعادة إرسال الرسالة نفسها. | | [`email_taken`](#email_taken) HTTP 409 | يوجد حساب مسجّل بهذا البريد الإلكتروني. سجّل الدخول بدلًا من ذلك.ما العمل: سجّل الدخول بدلًا من ذلك، أو أنشئ حسابًا ببريد آخر. | | [`etag_mismatch`](#etag_mismatch) HTTP 412 | تغيّر هذا العنصر منذ أن حمّلته. أعد تحميله ثم طبّق تغييراتك من جديد.ما العمل: تغيّرت المسودة بعد قراءتك لها. اجلب الوكيل من جديد، وأعد تطبيق تعديلك، وأرسل قيمة `etag` الجديدة في `If-Match`. | | [`handoff_already_assigned`](#handoff_already_assigned) HTTP 409 | استلم عضو آخر في الفريق هذا التحويل بالفعل.ما العمل: استلمه زميل قبلك. حدّث قائمة الانتظار، ويمكن للمسؤولين إعادة الإسناد مع `force: true`. | | [`handoff_already_open`](#handoff_already_open) HTTP 409 | يوجد تحويل مفتوح لهذه الجلسة بالفعل.ما العمل: لهذه الجلسة تحويل مفتوح بالفعل. تابعه في مكتب التحويل، أو أنهِه قبل طلب تحويل آخر. | | [`handoff_not_open`](#handoff_not_open) HTTP 409 | لم يعد هذا التحويل مفتوحًا.ما العمل: أُغلق التحويل أو انتهت مدته بالفعل. حدّثه قبل أي إجراء. | | [`idempotency_in_progress`](#idempotency_in_progress) HTTP 409 قابل لإعادة المحاولة | ما زال طلب يحمل مفتاح Idempotency-Key نفسه قيد المعالجة. أعد المحاولة بعد اكتماله.ما العمل: ما زال الطلب الأول بهذا المفتاح قيد التنفيذ. أعد المحاولة بفواصل متزايدة، وستحصل على نتيجته المحفوظة عند اكتماله. | | [`invitation_expired`](#invitation_expired) HTTP 409 | انتهت صلاحية هذه الدعوة أو أُلغيت. اطلب دعوة جديدة.ما العمل: اطلب رابط دعوة جديدًا من أحد المسؤولين. الرابط يُستخدم مرة واحدة وتنتهي صلاحيته بعد 7 أيام. | | [`last_owner`](#last_owner) HTTP 409 | يجب أن يبقى للمؤسسة مالك واحد على الأقل.ما العمل: اجعل عضوًا آخر مالكًا قبل إزالة هذا العضو أو تغيير دوره. | | [`model_not_configured`](#model_not_configured) HTTP 409 | لا يوجد مفتاح API مُعدّ لمزوّد هذا النموذج. أضف مفتاح المزوّد من الإعدادات.ما العمل: اربط مفتاحًا لمزوّد النموذج (الإعدادات ← مزوّدو النماذج، أو `POST /v1/provider_credentials`)، أو اختر نموذجًا توفّره المنصة. | | [`name_taken`](#name_taken) HTTP 409 | هذا الاسم مستخدم بالفعل. اختر اسمًا مختلفًا.ما العمل: اختر اسمًا أو معرّفًا نصيًا (slug) مختلفًا. | | [`no_open_handoff`](#no_open_handoff) HTTP 409 | لا يوجد تحويل مفتوح لهذه الجلسة.ما العمل: لا يوجد تحويل مفتوح لإعادته أو إنهائه. اجلب الجلسة وتحقّق من `mode`. | | [`run_already_completed`](#run_already_completed) HTTP 409 | انتهى هذا التشغيل بالفعل ولا يمكن إلغاؤه.ما العمل: انتهى التشغيل بالفعل. لا يلزمك فعل شيء. | | [`run_not_requires_action`](#run_not_requires_action) HTTP 409 | هذا التشغيل لا ينتظر نتائج أدوات.ما العمل: لا ترسل نتائج الأدوات إلا وحالة التشغيل `requires_action`. اجلب التشغيل لترى حالته. | | [`session_agent_mismatch`](#session_agent_mismatch) HTTP 409 | المعرّف الخارجي (external_id) هذا مرتبط بجلسة لوكيل آخر.ما العمل: هذا `external_id` مرتبط بجلسة لوكيل آخر. استخدم معرّفًا مختلفًا لكل وكيل، مثلًا بإضافة slug الوكيل في أوله. | | [`session_busy`](#session_busy) HTTP 409 قابل لإعادة المحاولة | الجلسة مشغولة بالرد على رسالة أخرى. أعد المحاولة بعد لحظات.ما العمل: الجلسة مشغولة بالرد على رسالة أخرى وتستخدم `concurrency: "reject"`. انتظر عدد ثواني `Retry-After`، أو حوّل الجلسة إلى `queue`. | | [`session_closed`](#session_closed) HTTP 409 | هذه الجلسة مغلقة.ما العمل: أرسلت `if_closed: "error"`. اتركه على القيمة الافتراضية `reopen` لإعادة فتح الجلسة، أو ابدأ جلسة جديدة. | | [`session_end_user_mismatch`](#session_end_user_mismatch) HTTP 409 | هذه الجلسة تخص عميلًا آخر.ما العمل: الجلسة تخص عميلًا آخر، وعميل الجلسة لا يتغير أبدًا. استخدم معرّف جلسة مختلفًا. | | [`session_exists`](#session_exists) HTTP 409 | توجد جلسة بهذا المعرّف الخارجي (external_id) بالفعل.ما العمل: أرسلت `if_exists: "error"` والجلسة موجودة. احذف الخيار لاستئنافها، أو استخدم `external_id` جديدًا. | | [`session_queue_full`](#session_queue_full) HTTP 409 قابل لإعادة المحاولة | توجد رسائل كثيرة بانتظار الرد في هذه الجلسة. انتظر رد الوكيل ثم أعد المحاولة.ما العمل: توجد عشر رسائل بانتظار الرد في هذه الجلسة. انتظر الردود قبل إرسال المزيد. | | [`slug_taken`](#slug_taken) HTTP 409 | يستخدم وكيل آخر في هذا المشروع هذا المعرّف النصي (slug) بالفعل.ما العمل: يستخدم وكيل آخر في هذا المشروع هذا المعرّف النصي. اختر `slug` مختلفًا. | ### حدود المعدّل والحصة (429) | الرمز | المعنى · ما العمل | | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`anonymous_limit_reached`](#anonymous_limit_reached) HTTP 429 قابل لإعادة المحاولة | عدد الرسائل كبير حاليًا. يُرجى المحاولة لاحقًا.ما العمل: بلغ زائر مجهول في الودجت أحد الحدود (لكل عنوان IP أو لكل جلسة أو الحد اليومي). اطلب منه المحاولة لاحقًا، أو عرّف المستخدمين المسجّلين برموز العميل. | | [`cost_cap_exceeded`](#cost_cap_exceeded) HTTP 429 | بُلغ الحد اليومي للاستخدام. يُرجى المحاولة غدًا.ما العمل: بلغت المنظمة الحد اليومي لتكلفة النماذج. حتى اليوم التالي تُحوَّل الجلسات لموظف ويعيد `ask` الرمز 429. تواصل معنا لرفع الحد. | | [`playground_limit_reached`](#playground_limit_reached) HTTP 429 | بُلغ الحد اليومي لمحادثات التجربة. اربط مفتاح المزوّد الخاص بك لمواصلة التجربة.ما العمل: لتشغيلات لوحة التجربة على نماذج المنصة حد يومي لكل مشروع. اربط مفتاح مزوّدك لمواصلة التجربة، أو جرّب غدًا. | | [`quota_exceeded`](#quota_exceeded) HTTP 429 | استُنفدت حصة المحادثات الذكية في خطتك لهذا الشهر.ما العمل: استُنفدت المحادثات الذكية لهذا الشهر في الخطة (الخطة المجانية، أو خطة مدفوعة بسقف صارم). رقِّ خطتك أو انتظر الشهر التالي؛ تحمل الاستجابة `x-should-retry: false`. | | [`rate_limited`](#rate_limited) HTTP 429 قابل لإعادة المحاولة | عدد الطلبات كبير جدًا. انتظر قليلًا ثم أعد المحاولة.ما العمل: انتظر عدد الثواني المذكور في `Retry-After` ثم أعد المحاولة، ووزّع طلباتك على فترات. | ### مزوّد الذكاء الاصطناعي (502) | الرمز | المعنى · ما العمل | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`provider_auth_failed`](#provider_auth_failed) HTTP 502 | رفض مزوّد الذكاء الاصطناعي بيانات الاعتماد.ما العمل: رفض مزوّد النموذج بيانات الاعتماد. تحقّق من مفتاح المزوّد أو استبدله. | | [`provider_bad_request`](#provider_bad_request) HTTP 502 | رفض مزوّد الذكاء الاصطناعي الطلب.ما العمل: رفض المزوّد الطلب. راجع إعدادات النموذج، وإن تكرر الخطأ فتواصل مع الدعم وأرفق `request_id`. | | [`provider_error`](#provider_error) HTTP 502 قابل لإعادة المحاولة | أعاد مزوّد الذكاء الاصطناعي خطأً.ما العمل: أعد المحاولة لاحقًا. اضبط `model.fallback_models` لتكمل التشغيلات على نموذج آخر. | | [`provider_overloaded`](#provider_overloaded) HTTP 502 قابل لإعادة المحاولة | مزوّد الذكاء الاصطناعي مثقل بالطلبات حاليًا. أعد المحاولة بعد قليل.ما العمل: أعد المحاولة بفواصل متزايدة؛ وتُبقي `model.fallback_models` المحادثات مستمرة في الأثناء. | | [`provider_rate_limited`](#provider_rate_limited) HTTP 502 قابل لإعادة المحاولة | يقيّد مزوّد الذكاء الاصطناعي عدد الطلبات حاليًا. أعد المحاولة بعد قليل.ما العمل: يقيّد المزوّد طلبات المفتاح. أعد المحاولة بفواصل متزايدة أو ارفع حدودك لدى المزوّد. | | [`provider_refusal`](#provider_refusal) HTTP 502 | امتنع نموذج الذكاء الاصطناعي عن الإجابة.ما العمل: امتنع النموذج عن الإجابة. يجرّب K-Agent النماذج البديلة `fallback_models`، ثم يرسل رسالة الطوارئ ويحوّل الجلسة لموظف. | | [`provider_timeout`](#provider_timeout) HTTP 502 قابل لإعادة المحاولة | استغرق مزوّد الذكاء الاصطناعي وقتًا طويلًا في الرد.ما العمل: أعد المحاولة. وإن تكرر فاختر نموذجًا أسرع أو قيمة أصغر لـ `max_reply_tokens`. | | [`provider_unavailable`](#provider_unavailable) HTTP 502 قابل لإعادة المحاولة | مزوّد الذكاء الاصطناعي غير متاح حاليًا.ما العمل: أعد المحاولة لاحقًا، واضبط `model.fallback_models`. | ### الخادم (500 و503) | الرمز | المعنى · ما العمل | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`internal_error`](#internal_error) HTTP 500 قابل لإعادة المحاولة | حدث خطأ من جهتنا. أعد المحاولة، وإن تكرر الخطأ فتواصل مع الدعم وأرفق معرّف الطلب.ما العمل: أعد المحاولة بفواصل متزايدة. إن تكرر الخطأ فتواصل مع الدعم وأرفق `request_id`. | | [`service_unavailable`](#service_unavailable) HTTP 503 قابل لإعادة المحاولة | الخدمة غير متاحة مؤقتًا. أعد المحاولة بعد قليل.ما العمل: الخادم يُعاد تشغيله أو مثقل بالطلبات. أعد المحاولة بفواصل متزايدة. | ### رموز خارج استجابات HTTP هذه الرموز لا تعود خطأَ HTTP أبدًا. تظهر في `error` الخاص بالتشغيل (أخطاء التشغيل)، أو حدثَ `error` في البث، أو في نتيجة أداة لا يراها إلا النموذج — وتجدها في خطوات التشغيل وتبويب Debug في لوحة التحكم. | الرمز | المعنى · ما العمل | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`handed_off`](#handed_off) نتيجة أداة | حُوّلت المحادثة إلى أحد الموظفين.ما العمل: يُعاد إلى النموذج بدل بقية استدعاءات الأدوات في الجولة التي أنهى فيها تحويلٌ لسبب قانوني (liability) الدورَ. لا يلزمك فعل شيء. | | [`no_model_credential`](#no_model_credential) خطأ تشغيل | لم يُربط أي مفتاح API بمزوّد الذكاء الاصطناعي الخاص بالوكيل.ما العمل: لا يوجد مفتاح API لمزوّد الذكاء الاصطناعي الخاص بالوكيل، فانتهى التشغيل برسالة الطوارئ. اربط مفتاح مزوّد (الإعدادات ← مزوّدو النماذج، أو `POST /v1/provider_credentials`). أما طلبات الواجهة البرمجية فتتلقى `409 agent_not_ready` مع هذا العائق بدلًا من ذلك. | | [`run_interrupted`](#run_interrupted) خطأ تشغيل قابل لإعادة المحاولة | انقطع التشغيل قبل أن يكتمل.ما العمل: توقف التشغيل قبل اكتماله (مثلًا أثناء إعادة تشغيل الخادم) وانتهى عبر مسار «عدم الصمت». راجع الجلسة وأعد إرسال الرسالة إن لزم. | | [`stream_timeout`](#stream_timeout) حدث بث قابل لإعادة المحاولة | أُغلق البث لطول مدة فتحه. أعد الاتصال مع Last-Event-ID للمتابعة.ما العمل: أعد الاتصال مع `Last-Event-ID` (أو `?after=`) لتكمل من آخر حدث استلمته. | | [`ticket_already_open`](#ticket_already_open) نتيجة أداة | لدى هذا العميل تذكرة مفتوحة بالفعل.ما العمل: يُعاد إلى النموذج حين تكون لدى العميل تذكرة مفتوحة، فيخبره برقم التذكرة القائمة. لا يلزمك فعل شيء. | | [`too_many_calls`](#too_many_calls) نتيجة أداة | عدد استدعاءات الأدوات في الخطوة الواحدة أكبر من المسموح.ما العمل: تُنفَّذ 5 استدعاءات أدوات كحد أقصى في الجولة الواحدة، ويتلقى النموذج هذا الرمز للاستدعاءات الزائدة. لا يلزمك فعل شيء. | | [`tool_outputs_expired`](#tool_outputs_expired) خطأ تشغيل | انتهت مهلة انتظار نتائج الأدوات، فتوقّف التشغيل.ما العمل: يجب أن تصل نتائج الأدوات خلال 10 دقائق من `requires_action`. فشل التشغيل؛ أرسل رسالة جديدة للمتابعة. | | [`unreadable`](#unreadable) نتيجة أداة | وصلت نتيجة الاستعلام بصيغة تعذّرت قراءتها.ما العمل: أعادت نقطة أداة HTTP لديك محتوى ليس JSON أو لا يطابق `response.items_path` و`fields`. أصلح النقطة أو الإسقاط، وتحقّق عبر `POST /v1/tools/{tool}/test`. | | [`upstream_failed`](#upstream_failed) نتيجة أداة قابل لإعادة المحاولة | تعذّر إكمال الاستعلام في الوقت الحالي.ما العمل: فشلت نقطة أداة HTTP لديك (رمز غير 2xx، أو انتهاء المهلة، أو تجاوز 1 ميغابايت، أو عنوان محظور). راجع خطوات التشغيل واختبر الأداة. | ## التحذيرات بعض الاستجابات الناجحة تحمل `warnings`: ملاحظات غير مانعة تستحق التسجيل. | التحذير | المعنى | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `external_id_looks_like_phone` | يبدو `external_id` رقم هاتف. أبقِ البيانات الشخصية خارج المعرّفات، واحفظ بيانات التواصل في خصائص العميل. | | `external_id_looks_like_email` | يبدو `external_id` عنوان بريد إلكتروني. والنصيحة نفسها. | | `create_params_ignored` | الجلسة موجودة مسبقًا، فجرى تجاهل إعدادات الإنشاء الواردة في الطلب. | | `client_history_ignored` | الواجهة المتوافقة مع OpenAI: استُخدم سجل الجلسة المحفوظ وجرى تجاهل الرسائل السابقة الواردة في الطلب. | | `identity_as_parameter` | اسم معامل في أداة يبدو من بيانات الهوية الشخصية. فعّل `requires_verified_user` واستخدم العناصر النائبة `end_user` بدلًا منه. | # عدم التكرار > أعد أي طلب POST أو DELETE بأمان عبر Idempotency-Key، وأعد إرسال رسائل المحادثة بأمان عبر client_message_id. الشبكات تتعطل. قد ينتهي وقت الطلب بعد أن ينجز الخادم العمل فعلًا، فتنشئ إعادة المحاولة العادية جلسة ثانية أو رسالة ثانية أو إجابة ثانية. يمنحك K-Agent أداتين لجعل إعادة المحاولة آمنة. ## `Idempotency-Key` أرسل مفتاحًا فريدًا مع أي طلب `POST` أو `DELETE`. وإذا أعدت المحاولة بالمفتاح نفسه تحصل على النتيجة المحفوظة بدل تنفيذ ثانٍ: * curl ```bash curl https://api.k-agent.kerneltics.com/v1/sessions \ -H "Authorization: Bearer $KAGENT_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f1c2a0e-8d3b-4c55-9a77-1e2f3d4c5b6a" \ -d '{"agent": "store-assistant", "external_id": "order-8812", "input": "وين طلبي؟"}' ``` * JavaScript ```js const key = crypto.randomUUID(); // create once, reuse for every retry of this request const RETRY_409 = new Set(['idempotency_in_progress', 'session_busy', 'session_queue_full']); async function createSessionWithRetry(body, attempts = 4) { for (let i = 0; i < attempts; i++) { try { const res = await fetch('https://api.k-agent.kerneltics.com/v1/sessions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KAGENT_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': key, }, body: JSON.stringify(body), }); if (res.status === 409) { const { error } = await res.clone().json(); if (!RETRY_409.has(error.code)) return res; } else if (res.status < 500 && res.status !== 429) { return res; } } catch { // network error: retry with the same key } await new Promise((r) => setTimeout(r, 500 * 2 ** i)); } throw new Error('Gave up after retries'); } ``` * Python ```python import os, time, uuid, requests key = str(uuid.uuid4()) # create once, reuse for every retry of this request RETRY_409 = {"idempotency_in_progress", "session_busy", "session_queue_full"} def create_session_with_retry(body: dict, attempts: int = 4) -> requests.Response: for i in range(attempts): try: r = requests.post( "https://api.k-agent.kerneltics.com/v1/sessions", headers={"Authorization": f"Bearer {os.environ['KAGENT_API_KEY']}", "Idempotency-Key": key}, json=body, timeout=120, ) if r.status_code == 409: if r.json()["error"]["code"] not in RETRY_409: return r elif r.status_code < 500 and r.status_code != 429: return r except requests.ConnectionError: pass # network error: retry with the same key time.sleep(0.5 * 2 ** i) raise RuntimeError("Gave up after retries") ``` ### القواعد * **النطاق.** المفتاح محصور في مشروعك، وبيانات الاعتماد التي أرسلته، والمسار (الطريقة ونمط المسار). والمفتاح نفسه على مسار آخر مفتاح مختلف. * **الطول.** من 1 إلى 255 حرفًا (وإلا `400 invalid_idempotency_key`). ومعرّف UUID v4 مثالي. * **مدة الحفظ.** تُحفظ النتائج **24 ساعة**. وبعدها يمكن استخدام المفتاح من جديد. * **الإعادة** ترجع الحالة والجسم الأصليين، مع الترويسة `Idempotent-Replayed: true`. * **المفتاح نفسه مع طلب مختلف** — جسم آخر أو معرّف آخر في المسار — يعيد `422 idempotency_key_reused`. وتعتمد المقارنة على الجلسة بعد تحديدها، فمخاطبتها بمعرّف `sess_…` أو بـ `external_id` تُعدّ الطلب نفسه. * **ما زال قيد التنفيذ.** إذا لم ينتهِ الطلب الأول تعيد إعادة المحاولة `409 idempotency_in_progress`. انتظر وأعد المحاولة بالمفتاح نفسه. * **أخطاء الخادم لا تُحفظ.** خطأ `5xx` يقع قبل بدء أي عمل يمكن إعادته بالمفتاح نفسه وسيُنفَّذ من جديد. ### الطلبات التي تبدأ تشغيلًا في `ask`، و`POST /v1/sessions` مع `input`، والرسائل، و`submit_tool_outputs`، يرتبط المفتاح **بالتشغيل** فور وجوده: * تعيد إعادة المحاولة الحالة **الحالية** للتشغيل بالشكل المعتاد لاستجابة نقطة النهاية — فإن كان قد انتهى منذ ذلك الحين تحصل على التشغيل المنتهي؛ * إعادة طلب بثّ تعيد ربطك ببث ذلك التشغيل **من بدايته**؛ * لا يكون `409 idempotency_in_progress` ممكنًا إلا في اللحظة القصيرة قبل وجود التشغيل. ### الطلبات التي تعيد سرًا إنشاء مفتاح API أو استبداله، وإصدار رمز عميل، وبدء جلسة ودجت، وإنشاء نقطة استقبال ويب هوك أو تغيير سرها، وقراءة سر توقيع الأدوات — كلها تعيد سرًا **مرة واحدة**. وإعاداتها ترجع المورد نفسه مع السر بقيمة `null` و`"secret_redacted": true` — فالسر نفسه لا يُحفظ لإعادته أبدًا. ## `client_message_id` لرسائل المحادثة آلية ثانية أبسط: أعطِ كل رسالة معرّفك الخاص. ```bash curl https://api.k-agent.kerneltics.com/v1/sessions/order-8812/messages \ -H "Authorization: Bearer $KAGENT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input": "شكرًا!", "client_message_id": "wa-msg-77121"}' ``` * المعرّف `client_message_id` نفسه في الجلسة نفسها يعيد `{session, message, run}` الأصلية بالحالة `200` مع `Idempotent-Replayed: true` — دون رسالة ثانية ودون إجابة ثانية. * المعرّف نفسه مع نص مختلف يعيد `409 client_message_id_conflict`. * لا تنتهي صلاحيته ما دامت الجلسة موجودة، ما يجعله الأداة المناسبة للقنوات التي تعيد تسليم الرسائل بعد ساعات (الويب هوك من منصات المراسلة، وتطبيقات الجوال التي تعيد الإرسال بعد استعادة الاتصال). استخدم **الاثنين** متى استطعت: `client_message_id` لمنع تكرار الرسالة نفسها، و`Idempotency-Key` لجعل طلب HTTP آمنًا عند إعادته. # حدود المعدّل > معدلات الطلبات، وحدود المحادثات، وحدود الأحجام، والترويسات التي يرسلها K-Agent حين تبلغ أحدها — وكيف تتعامل معها. تحافظ الحدود على سرعة المنصة للجميع، وتحميك من التكاليف الجامحة ومن إساءة الاستخدام. وحين تبلغ أحدها تحصل على خطأ واضح برمز ثابت، ومعه ترويسة `Retry-After` حيث يفيد الانتظار. ## معدلات الطلبات | مَن | الحد | عند التجاوز | | ----------------------------- | --------------------------------------------------------------- | ------------------ | | المفتاح السري | 600 طلب في الدقيقة لكل مفتاح | `429 rate_limited` | | المفتاح القابل للنشر (الودجت) | 60 طلبًا في الدقيقة لكل عنوان IP، و20 رسالة في الدقيقة لكل جهاز | `429 rate_limited` | | تسجيل الدخول إلى لوحة التحكم | 10 محاولات في الدقيقة لكل عنوان IP، ولكل بريد | `429 rate_limited` | | إنشاء الحسابات | 5 في اليوم لكل عنوان IP | `429 rate_limited` | ## حدود المحادثات | ماذا | الحد | عند التجاوز | | ---------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- | | الرسائل المنتظرة في جلسة واحدة (`queue`) | 10 | `409 session_queue_full` | | رسالة تصل والجلسة ترد (`reject`) | — | `409 session_busy` مع `Retry-After: 2` | | جلسات الودجت المجهولة | 20 في الساعة لكل عنوان IP | `429 anonymous_limit_reached` مع إشعار مهذب | | رسائل الودجت المجهولة | 60 في الساعة لكل عنوان IP؛ و40 لكل جلسة | `429 anonymous_limit_reached` مع إشعار مهذب | | المحادثات المجهولة لكل وكيل | `widget.anonymous_daily_conversations` في اليوم (الافتراضي 200) | إشعار مهذب بالمحاولة لاحقًا | | تشغيلات لوحة التجربة على نماذج المنصة | 200 في اليوم لكل مشروع (بلا حد مع مفتاح مزوّدك الخاص) | `429 playground_limit_reached` | | المحادثات الذكية في الخطة المجانية | 100 في الشهر | تُحوَّل الجلسات لموظف مع إشعار؛ وتحصل `ask` على `429 quota_exceeded` | | تكلفة النماذج اليومية لكل منظمة | المجانية 1 دولار، وStarter ‏10، وBusiness ‏30، وScale ‏100 | تُحوَّل الجلسات لموظف مع إشعار؛ وتحصل `ask` على `429 cost_cap_exceeded` | ## حدود الأدوات | ماذا | الحد | | ------------------------------------- | ------------------------------------------------------------------------------------------------------ | | استدعاءات الأدوات المنفَّذة في الجولة | 5 (الاستدعاءات الزائدة تحصل على `too_many_calls`) | | جولات النموذج والأدوات في الدور | `tools.max_tool_rounds`، من 1 إلى 5 (الافتراضي 3) | | استدعاءات أدوات HTTP لكل عميل | 20 في الساعة عبر كل أدوات HTTP، مع احتساب كل محاولة؛ ولكل أداة `limits.per_end_user_per_hour` ‏(1–100) | | `create_ticket` لكل عميل | 5 في اليوم | | زمن أداة HTTP | حتى 15 ثانية (3 ثوانٍ للاتصال) | | استجابة أداة HTTP | حتى 1 ميغابايت؛ ولا يصل إلى النموذج أكثر من 20 صفًا و12 حقلًا، ضمن 4 كيلوبايت | | نتائج أدوات جهة العميل | خلال 10 دقائق | حين يُبلغ حد في الأدوات يُخبَر النموذج بصياغة محايدة، فيجيب مما لديه أو يحوّل المحادثة إلى فريقك؛ ولا يصل الطلب إلى واجهتك البرمجية أصلًا. ## حدود الأحجام | ماذا | الحد | عند التجاوز | | ----------------------------------------- | ------------------------------------------------ | ------------------------------------ | | `input` مع المفتاح السري | 32,000 حرف | `413 input_too_large` | | `input` مع مفتاح قابل للنشر أو رمز عميل | 4,000 حرف | `413 input_too_large` | | جسم الطلب | 1 ميغابايت (5 ميغابايت لمصادر المعرفة) | `413 request_too_large` | | `messages` في الواجهة المتوافقة مع OpenAI | 100 | يُرفض بخطأ بصيغة OpenAI | | حجم الصفحة في القوائم | 100 (الافتراضي 20) | يُقتصر على الحد | | `metadata` | 16 مفتاحًا؛ المفتاح حتى 64 حرفًا والقيمة حتى 512 | `422 validation_failed` | | `Idempotency-Key` | 255 حرفًا | `400 invalid_idempotency_key` | | نقاط استقبال الويب هوك لكل مشروع | 10 | `422 webhook_endpoint_limit_reached` | ## الترويسات | الترويسة | متى | المعنى | | ------------------ | ---------------------------------------- | ---------------------------------------- | | `Retry-After` | استجابات `429` وبعض استجابات `409` | الثواني التي تنتظرها قبل إعادة المحاولة. | | `RateLimit-Policy` | الاستجابات المحدودة | الحد المطبَّق: حصته ونافذته. | | `RateLimit` | الاستجابات المحدودة | ما تبقّى في النافذة الحالية ومتى تتجدد. | | `x-should-retry` | الأخطاء التي لا تفيد فيها إعادة المحاولة | `false` — مثل `quota_exceeded`. | تتبع `RateLimit-Policy` و`RateLimit` مسودة IETF لحقول ترويسات حدود المعدّل في HTTP. ## التعامل الجيد مع الحدود * **التزم بـ `Retry-After`.** انتظر هذه المدة على الأقل، وأضف قدرًا عشوائيًا بسيطًا حتى لا يعيد كثير من العملاء المحاولة في اللحظة نفسها. * **زِد فترات الانتظار تدريجيًا** عند تكرار `429` و`5xx`: مثل 0.5 ثانية، ثم 1، ثم 2، ثم 4، ثم توقف وأبلغ. * **لا تُعد المحاولة** حين تكون `x-should-retry` قيمتها `false`. * **اجعل إعادة المحاولة آمنة** بمفتاح `Idempotency-Key`، فلا تُنشئ أبدًا نسخة مكررة. * **استخدم طابورًا لا دفعات.** عند الاستيراد أو الترحيل بكميات كبيرة شغّل عددًا ثابتًا من العمّال بدل إطلاق كل الطلبات دفعة واحدة. * **عرّف المستخدمين المسجّلين** في الودجت برموز العميل: فالمستخدمون الموثّقون لا يخضعون لحدود المجهولين. تحتاج حدودًا أعلى؟ تواصل معنا — الحدود مضبوطة حسب الخطة ويمكن رفعها في اتفاقيات Enterprise. # سياسة الإصدارات > كيف تتطور واجهة K-Agent البرمجية — ‏/v1 لا يتغير إلا بالإضافة، وترويسة K-Agent-Version، وما يجب أن يتحمله تطبيقك. تبني على K-Agent مرة واحدة ويستمر عملك. إصدار الواجهة البرمجية جزء من المسار، `/v1`، و\*\*`/v1` لا يتغير إلا بالإضافة\*\*. ## ما الذي قد يتغير داخل `/v1` هذه تغييرات إضافية قد تصدر في أي وقت، دون إشعار سوى [سجل التغييرات](/docs/reference/changelog/): * نقاط نهاية جديدة؛ * حقول ومعاملات اختيارية جديدة في الطلبات؛ * حقول جديدة في الاستجابات وفي بيانات الأحداث؛ * **قيم** جديدة في القوائم المفتوحة (مثل `outcome` أو `reason_type` أو `channel` جديد)؛ * أنواع أحداث جديدة في البث والويب هوك؛ * رموز أخطاء وتحذيرات جديدة. وهذه **لن** تحدث داخل `/v1`: حذف نقطة نهاية أو حقل أو تغيير اسمه، أو تغيير نوع الحقل أو معناه، أو جعل حقل اختياري إلزاميًا، أو تغيير رمز خطأ تتلقاه بالفعل. فمثل هذه التغييرات تأتي مع إصدار رئيسي جديد يُعلن عنه قبل وقت كافٍ. ## اكتب عملاء متسامحين * **تجاهل الحقول التي لا تعرفها.** لا تفشل حين تحمل استجابة أو حدث حقولًا أكثر مما تتوقع. * **تعامل مع قيم القوائم غير المعروفة.** عامل `outcome` أو `status` غير معروف بقيمة افتراضية معقولة بدل الانهيار. وفي عقد OpenAPI تُعرَّف القوائم المفتوحة بالنوع `type: string` مع قائمة `x-enum-values` بقيم اليوم. * **تجاهل أنواع الأحداث غير المعروفة** في البث والويب هوك. * **ابنِ على `code` الخاص بالخطأ وحالة HTTP**، لا على `message` المقروءة، فهي مترجمة وقد تُعاد صياغتها. ## ترويسة `K-Agent-Version` ثبّت السلوك الذي كُتب عليه تكاملك بترويسة مؤرخة: ```text K-Agent-Version: 2026-10-06 ``` * `2026-10-06` هو الإصدار الحالي — والأول. والطلب دون الترويسة يستخدمه. * القيمة التي ترسلها تُعاد في كل استجابة. * القيمة غير المعروفة تعيد `400 invalid_api_version`. * الإصدارات المؤرخة هي الطريقة التي سنقدّم بها أي تغيير في السلوك لا يكون إضافيًا خالصًا، دون كسر العملاء الذين ثبّتوا تاريخًا أقدم. ## الإيقاف والإنهاء إذا أُوقفت نقطة نهاية أو حقل يومًا ما، فستحمل الاستجابات التي تستخدمه الترويسة القياسية `Deprecation` وترويسة `Sunset` بتاريخ توقفه عن العمل، وسيوضح سجل التغييرات البديل. هذه الترويسات محجوزة اليوم: لا شيء في `/v1` موقوف. ## العقد العقد القابل للقراءة آليًا هو وثيقة OpenAPI 3.1 على [`/docs/openapi.yaml`](/docs/openapi.yaml)، وتقدّمها الواجهة البرمجية أيضًا على `/openapi.json`. وتتحقق اختباراتنا من تطابق كل مسار يسجله الخادم معها، فيصف [مرجع الواجهة البرمجية](/docs/api/) دائمًا ما يفعله الخادم فعلًا. # سجل التغييرات > الجديد في K-Agent. صدر الإصدار 1.0 في 6 أكتوبر 2026. ## الإصدار v1.0 — ‏2026-10-06 الإصدار الأول من K-Agent: وكيل واحد، استخدمه في أي مكان. إصدار الواجهة البرمجية `2026-10-06`. ### استخدم وكيلك في أي مكان * **إجابات بسؤال واحد** عبر `POST /v1/agents/{agent}/ask`، مع سجل يرسله المستدعي، وتجاوزات لكل طلب، ووضع خصوصية `store: false`، وإجراءات عند الطلب. * **جلسات محادثة** بمعرّفات المنصة `sess_` أو **بمعرّفك الخاص `external_id`**، مع الجلب أو الإنشاء، ومخاطبة الجلسة بأي من المعرّفين في كل مكان — وفق [عقد معرّفات الجلسات](/docs/concepts/sessions/#%D8%B9%D9%82%D8%AF-%D9%85%D8%B9%D8%B1%D9%91%D9%81%D8%A7%D8%AA-%D8%A7%D9%84%D8%AC%D9%84%D8%B3%D8%A7%D8%AA) المنشور. * **البث المباشر** عبر Server-Sent Events، قابلًا للاستئناف بـ `Last-Event-ID`، مع أحداث `*.completed` معتمدة مرجعًا. * **سياسات تزامن** لكل جلسة: `queue` و`reject` و`interrupt`. * **واجهة متوافقة مع OpenAI** على `/openai/v1/chat/completions`، باسم الوكيل نموذجًا، وجلسات اختيارية، وامتداد `kagent`. * **ودجت الدردشة** (``) بمفاتيح قابلة للنشر، ومصادر مسموح بها، وزوار مجهولين، ومستخدمين موثّقين عبر رموز العميل. ### أعدّه مرة، وشاهد كل شيء * وثيقة إعدادات واحدة تغطي الهوية واللهجة العربية والنبرة، والتعليمات، والمعرفة، والأدوات، والضوابط، والتحويل لموظف، وساعات العمل، والمحادثة، والنموذج، والمتغيرات، والتجاوزات، ورد الطوارئ، والودجت — وتُعاد كاملة دائمًا. * **المسودات والإصدارات:** نشر تلقائي للإصدار 1، وتعديل بـ `If-Match` ورقعة دمج JSON، ونشر، واستعادة، ومقارنة، وتصدير واستيراد، و`config_hash` في كل تشغيل. * **«أشعة إكس» للتعليمات** (`prompt_preview`) تعرض كل كتلة بمصدرها وإصدارها ورموزها. * **الجاهزية** مع عوائق صريحة، ومفتاحا الإيقاف `ai_paused` و`actions_paused`. * قوالب جاهزة: خدمة العملاء، وأسئلة المبيعات، ومساعد الحجوزات، والأسئلة الداخلية. ### أمان في الكود * قائمة «لا تتعامل معها بنفسك»، مفعّلة افتراضيًا وفي آخر التعليمات. * الرد الحرفي عند التصعيد لتحويلات المسؤولية القانونية، بالعربية والإنجليزية. * نتائج تحويل صادقة (`queued` و`recorded` و`recorded_closed` و`already` و`failed`) وقاعدة «لا صمت أبدًا» مع إعادة المحاولة والنماذج البديلة ورسالة الطوارئ. * انتهاء منزلق لمدة التحويل، وتحويلات تقنية لا تُصمت المحادثة، و**مكتب التحويل** مع الاستلام والرد والملاحظات الداخلية والإعادة والإغلاق وتولّي المحادثة. ### الأدوات والمعرفة * أدوات مدمجة: `transfer_to_human` و`create_ticket` و`flag_conversation` و`search_knowledge`. * **أدوات HTTP** بقوالب تُغلق عند الفشل، وأسرار بمضيفات مسموح بها، وهوية من العملاء الموثّقين، وإسقاط للاستجابة، ونقطة اختبار مباشر، واستدعاءات صادرة موقّعة. * **أدوات جهة العميل** مع `requires_action` و`submit_tool_outputs`. * مصادر معرفة (`text` و`catalog` و`api`) بوضع `always` أو `searchable`، مع بحث يفهم العربية وتحديث مجدول من الواجهات البرمجية يحتفظ بآخر نسخة سليمة. * عميل شبكة محمي لكل رابط تضبطه. ### المنصة * مفاتيح سرية بنطاقات وتقييد بالوكلاء، ومفاتيح قابلة للنشر، ورموز عميل، وأدوار للفريق (مالك، ومسؤول، ومطوّر، ومحرّر، ودعم، ومشاهد). * ويب هوك وفق Standard Webhooks مع إعادة المحاولة، وسجل للإرسالات، وأحداث تجريبية؛ وسجل أحداث على `/v1/events`. * وحدة الفوترة **المحادثة الذكية** مع أوزان النماذج والحصص والتنبيهات، وواجهة الاستخدام البرمجية. * استخدام مفتاح نموذجك الخاص (OpenAI أو Anthropic أو DeepSeek أو أي مزوّد متوافق مع OpenAI)، مع التحقق منه مباشرة. * سجل التدقيق، ومحو بيانات العملاء، وإعدادات الاحتفاظ بالبيانات. * توثيق بالعربية والإنجليزية، ومرجع تفاعلي للواجهة البرمجية، و`llms.txt`، ونسخة Markdown من كل صفحة.