الأدوات

الأدوات تتيح للوكيل أن يتصرف: يحوّل المحادثة إلى فريقك، أو يفتح تذكرة، أو يستعلم في أنظمتك. وهي ثلاثة أنواع:

النوع	أين تعمل	أين تُعرَّف
مدمجة	داخل K-Agent	متاحة دائمًا؛ فعّل كلًّا منها أو عطّله في `tools.builtin`
أداة HTTP (`tool_…`)	يستدعي K-Agent نقطة HTTPS الخاصة بك	`POST /v1/tools`، ثم تُمنح للوكلاء في `tools.http`
أداة من جهة العميل	يشغّلها تطبيقك ويعيد النتيجة	`tools.client` في إعدادات الوكيل

tools.enabled هو المفتاح الرئيسي: تعطيله يزيل كل الأدوات مع الإبقاء على صلاحياتك وقواعدك لوقت لاحق.

الأدوات المدمجة

الأداة	الأثر	الافتراضي	ما تفعله
`transfer_to_human`	تصعيد (escalation)	مفعّلة	تحوّل المحادثة إلى فريقك. معاملاتها: `reason_type` ‏(`customer_requested` · `out_of_scope` · `complaint` · `liability` · `technical`) و`summary` (الموضوع، لا الاتهام). تعيد حالة صادقة.
`create_ticket`	إجراء (action)	معطّلة	تفتح التذكرة `TKT-<n>` بالحقول `title` و`description` و`priority` ‏(`low` · `normal` · `high` · `urgent`) و`resolution_attempted`. ترفض إذا كانت للعميل تذكرة مفتوحة من الوكيل، وتعطي النموذج رقم التذكرة القائمة بدلًا من ذلك.
`flag_conversation`	تصعيد (escalation)	معطّلة	توسم الجلسة `flagged` مع `reason` و`urgency` ‏(`low` · `normal` · `high`) ليراجعها فريقك. للجلسات فقط.
`search_knowledge`	قراءة (read)	مفعّلة	تبحث في المعرفة القابلة للبحث لدى الوكيل باستعلام `query` يفهم العربية. لا تُعرض إلا حين يملك الوكيل مصادر قابلة للبحث.

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

قواعدك لكل أداة

لكل صلاحية أداة حقل rules (حتى 4,000 حرف). يُضاف إلى وصف الأداة تحت عنوان «قواعد هذه الشركة لهذا الإجراء»، فتقول متى تُستخدم الأداة بكلماتك:

{
  "tools": {
    "builtin": {
      "transfer_to_human": {
        "enabled": true,
        "rules": "حوّل أي سؤال عن طلبات الجملة أو هدايا الشركات. وفي رمضان حوّل طلبات التوصيل في اليوم نفسه."
      },
      "create_ticket": { "enabled": true, "rules": "لا تفتح تذكرة إلا لشكاوى التوصيل بعد أن يصف العميل المشكلة." }
    }
  }
}

تقترح لوحة التحكم قواعد جاهزة لكل أداة، مع سبب كل قاعدة.

الأثر ومتى تتاح الأدوات

لكل أداة أثر:

الأثر	الأدوات	مقيّدة؟
`read`	`search_knowledge`، وأدوات HTTP التي تستعلم فقط	أدوات HTTP للقراءة تتبع خاصية `requires_verified_user` فيها.
`escalation`	`transfer_to_human` و`flag_conversation`	أبدًا. تعمل في طلبات السؤال الواحد، وللمستخدمين المجهولين، وفي التجربة، فيعمل رد المسؤولية القانونية في كل مكان.
`action`	`create_ticket`، وأدوات HTTP التي تغيّر شيئًا، وأدوات جهة العميل (افتراضيًا)	تُزال حين يكون الطلب سؤالًا واحدًا دون `allow_actions: true`، أو حين لا يكون العميل موثّقًا و`tools.allow_anonymous_actions` معطّلة، أو حين يكون `actions_paused` مفعّلًا في الوكيل.

تُحدَّد قائمة الأدوات عند بداية المقطع وتبقى ثابتة، مرتبة بالاسم، حتى المقطع التالي، فيبقى التخزين المؤقت للتعليمات فعّالًا. وداخل المقطع تُرفض الأداة التي لا يمكن أن تنجح الآن مع إرشاد، بدل إزالتها.

فحص السياسات

قبل تنفيذ أي أداة يتحقق K-Agent من كل ما يلي. وإذا فشل أحدها يتلقى النموذج {"ok": false, "error": {"code": …, "guidance": …}} ولا يُنفَّذ شيء:

الأداة ضمن مجموعة أدوات التشغيل وtools.enabled مفعّل.
المعاملات تطابق مخطط JSON الخاص بالأداة بصرامة.
إذا احتاجت الأداة عميلًا موثّقًا فالتشغيل يملك واحدًا. ويملأ K-Agent الهوية من بيانات الاعتماد — والنموذج لا يقدّمها أبدًا.
أنها متاحة: ساعات العمل، ووجود الكتالوج، وعدم وجود تذكرة مفتوحة من الوكيل في حالة create_ticket.
لم تنجح الأداة نفسها بالمعاملات نفسها من قبل في هذا التشغيل.
لم يُلغَ التشغيل ولم يُستبدل.
حدود كل مستخدم: أدوات HTTP مجتمعة، 20 استدعاءً في الساعة لكل عميل (أو لكل جلسة للمجهولين)، مع احتساب كل محاولة؛ وcreate_ticket، 5 في اليوم.
لم تُستنفد ميزانية الجولات، ولا يُنفَّذ أكثر من 5 استدعاءات في الجولة الواحدة (الاستدعاءات الزائدة تتلقى too_many_calls).

يعمل الوكيل حتى tools.max_tool_rounds جولة (من 1 إلى 5، الافتراضي 3). وإذا ظل يريد أداة بعد الجولة الأخيرة تُنتَج إجابة نهائية واحدة والأدوات معطّلة. والتأكيدات — رقم التذكرة أو التحويل — تأتي من نتائج الأدوات فقط، لا من خيال النموذج.

أدوات HTTP

أداة HTTP تستدعي نقطة نهاية تملكها. يملأ K-Agent الطلب من قالب، ويستدعيه عبر عميل محمي، ولا يُظهر للنموذج إلا الحقول التي تختارها. يشرح دليل أدوات HTTP أداة كاملة من البداية إلى النهاية.

{
  "name": "order_status",
  "description": "Look up the status of the customer's order by its number.",
  "effect": "read",
  "requires_verified_user": true,
  "config": {
    "method": "GET",
    "url": "https://api.example.com/customers/{{end_user.external_id}}/orders/{{args.order_number}}",
    "headers": { "Authorization": "Bearer {{secret.ORDERS_TOKEN}}" },
    "parameters": {
      "type": "object",
      "properties": {
        "order_number": { "type": "string", "description": "The order number, e.g. 8812" }
      },
      "required": ["order_number"],
      "additionalProperties": false
    },
    "response": {
      "items_path": "data",
      "fields": [
        { "path": "status", "label": "الحالة" },
        { "path": "eta", "label": "موعد التوصيل المتوقع" }
      ],
      "max_items": 1,
      "empty_message": "لا يوجد طلب بهذا الرقم."
    },
    "timeout_ms": 8000
  }
}

قواعد القوالب

العناصر النائبة: {{args.x}} (من النموذج)، و{{end_user.external_id}} و{{end_user.traits.k}} (من بيانات الاعتماد، للعملاء الموثّقين فقط)، و{{secret.NAME}} (من أسرارك)، و{{var.name}} (من متغيرات الوكيل).
الإغلاق عند الفشل: أي عنصر نائب لم يُحل أو كانت قيمته فارغة يلغي الاستدعاء. لا يُرسل طلب ناقص أبدًا.
تُهرَّب القيم بحسب موضعها: مسار الرابط، أو سلسلة الاستعلام، أو الترويسة، أو جسم JSON.
يجب أن يبدأ الرابط بنص ثابت https://host[:port]/. العناصر النائبة مسموحة في المسار والاستعلام فقط، وبعد التعويض لا يجوز أن يحتوي المسار على مقاطع . أو ...
8 معاملات كحد أقصى. الأسماء args وend_user وsecret وvar وsys محجوزة.
أي عنصر نائب {{end_user.*}} يتطلب requires_verified_user: true. وفي هذه الأدوات تُرفض المعاملات المسماة بأسماء هوية (phone وmobile وemail وuser_id وcustomer_id وaccount_id وexternal_id) بالخطأ 422 identity_as_parameter — فالهوية تأتي من بيانات الاعتماد، لا من النموذج أبدًا.
لكل معامل صيغة x-kagent-format:
- token (الافتراضية، وإلزامية لكل ما يُستخدم في الرابط أو الترويسات): حروف وأرقام ومسافات و._@:+-، حتى 64 حرفًا؛
- text: لمعاملات جسم الطلب فقط؛ حتى 1,000 حرف، بترميز JSON، مع حذف محارف التحكم والاتجاه والمحارف الصفرية العرض.
تُحوَّل الأرقام العربية إلى أرقام لاتينية قبل الفحص، فيكون ٨٨١٢ و8812 رقم الطلب نفسه.
لا يُرسل السر إلا إلى المضيفات المدرجة في allowed_hosts الخاصة به؛ وغير ذلك يفشل بـ secret_host_not_allowed.
تُرفض الترويسات المسماة Host وForwarded وX-Forwarded-* وX-Real-IP وConnection وTransfer-Encoding وContent-Length وProxy-*.

حدود الشبكة

كل طلب إلى رابط تضبطه أنت — أدوات HTTP، ومصادر المعرفة من الواجهات البرمجية، والويب هوك، وعناوين base_url المخصصة للنماذج — يمرّ عبر عميل محمي واحد:

https:// فقط، على المنفذ 443 أو 8443، دون وسيط (proxy) ودون تحويلات؛
تُفحص العناوين عند الاتصال، بعد DNS: تُرفض عناوين الحلقة المحلية، والنطاقات الخاصة (10/8 و172.16/12 و192.168/16)، وNAT واسع النطاق (100.64/10)، وعناوين الربط المحلي وبيانات السحابة الوصفية (169.254/16)، والعناوين المحلية الفريدة وعناوين الربط المحلي في IPv6، والبث المتعدد، و0.0.0.0/8، ومضيفات K-Agent نفسها؛
مهلة الاتصال 3 ثوانٍ؛ والمدة الكلية حتى timeout_ms (15 ثانية كحد أقصى)؛
الاستجابات الأكبر من 1 ميغابايت تُرفض ولا تُقتطع.

ما يراه النموذج

الحقول التي تسردها في response.fields فقط (حتى 12 حقلًا، بتسميات)، من صفوف حتى max_items (20 كحد أقصى).
تُنظَّف القيم — تُحذف محارف التحكم والاتجاه والمحارف الصفرية العرض، مع الإبقاء على محارف الوصل العربية — وتُقتطع عند 200 حرف. وتبقى النتيجة كلها أقل من 4 كيلوبايت بحذف صفوف كاملة.
توسم النتيجة بأنها بيانات لا تعليمات، فلا يستطيع نص في واجهتك البرمجية توجيه الوكيل.
لا تصل أخطاء الطرف الآخر إلى النموذج إلا بالرموز upstream_failed أو unreadable أو rate_limited، بصياغة محايدة. أما رموز الحالة والأجسام فتذهب إلى خطوات التشغيل فقط.

كل استدعاء موقّع بترويسات Standard Webhooks ‏(webhook-id وwebhook-timestamp وwebhook-signature) باستخدام سر توقيع الأدوات في مشروعك (GET /v1/tool_signing_secret)، ويرسل User-Agent: K-Agent/1، فتستطيع نقطتك التحقق من أن الاستدعاء صادر من K-Agent.

تُنسخ تعريفات أدوات HTTP في كل إصدار منشور. بعد تعديل أداة، انشر الوكيل من جديد ليصل التغيير إلى الإنتاج.

أدوات جهة العميل

أداة جهة العميل تعمل في تطبيقك — كقراءة سلة التسوق في المتصفح، أو فتح شاشة في تطبيق الجوال. تعرّفها في الوكيل:

{
  "tools": {
    "client": [
      {
        "name": "get_cart",
        "description": "Returns the items in the customer's cart with prices.",
        "parameters": { "type": "object", "properties": {}, "additionalProperties": false },
        "effect": "read",
        "rules": "تحقّق من السلة قبل الإجابة عن أسئلة رسوم التوصيل."
      }
    ]
  }
}

حين يستدعيها النموذج يتوقف التشغيل مؤقتًا:

{
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "tool_calls": [{ "call_id": "call_4kq7", "name": "get_cart", "arguments": {} }],
    "expires_at": 1791272520
  }
}

يشغّل تطبيقك الأداة ويستأنف التشغيل عبر POST /v1/runs/{run}/submit_tool_outputs مع {"tool_outputs": [{"call_id": "call_4kq7", "output": {…}, "is_error": false}]}. يجب الرد على كل استدعاء مفتوح. وإذا لم تصل النتائج خلال 10 دقائق يفشل التشغيل بالرمز tool_outputs_expired. يعرض دليل أدوات جهة العميل الدورة كاملة.

أسماء أدوات جهة العميل تطابق ^[a-z][a-z0-9_]{0,47}$، وأثرها الافتراضي action. ولا تُعرض في طلبات store: false.

الأسماء

يجب أن تكون أسماء الأدوات فريدة بين أدوات الوكيل المدمجة وأدوات HTTP وأدوات جهة العميل (422 tool_name_conflict)، ولا يجوز أن تكرر اسم أداة مدمجة. أسماء أدوات HTTP تطابق ^[a-z][a-z0-9_]{0,29}$.

في لوحة التجربة

لوحة التجربة في لوحة التحكم بيئة معزولة: أدوات القراءة تعمل فعليًا، وأدوات الإجراء تعيد {"ok": true, "simulated": true} ما لم تفعّل تشغيل الإجراءات الحقيقية، والتحويلات والتذاكر توسم بأنها تجريبية ولا تصل أبدًا إلى مكتب التحويل أو الويب هوك.