# الأدوات

> الأدوات المدمجة، وأدوات HTTP التي تستدعي واجهتك البرمجية (قواعد القوالب وحدود الشبكة)، وأدوات جهة العميل التي يشغّلها تطبيقك — وفحوص السياسات التي يمرّ بها كل استدعاء أولًا.

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

| النوع | أين تعمل | أين تُعرَّف |
|---|---|---|
| **مدمجة** | داخل 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` (الموضوع، لا الاتهام). تعيد [حالة صادقة](/docs/concepts/handoff-and-safety/#نتائج-أدوات-صادقة). |
| `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) | مفعّلة | تبحث في [المعرفة](/docs/concepts/knowledge/) القابلة للبحث لدى الوكيل باستعلام `query` يفهم العربية. لا تُعرض إلا حين يملك الوكيل مصادر قابلة للبحث. |

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

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

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

```json
{
  "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` مفعّلًا في الوكيل. |

تُحدَّد قائمة الأدوات عند بداية [المقطع](/docs/concepts/sessions/#السجل-والمقاطع) وتبقى ثابتة، مرتبة بالاسم، حتى المقطع التالي، فيبقى التخزين المؤقت للتعليمات فعّالًا. وداخل المقطع تُرفض الأداة التي لا يمكن أن تنجح الآن مع إرشاد، بدل إزالتها.

## فحص السياسات

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

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

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

## أدوات HTTP

أداة HTTP تستدعي نقطة نهاية تملكها. يملأ K-Agent الطلب من قالب، ويستدعيه عبر عميل محمي، ولا يُظهر للنموذج إلا الحقول التي تختارها. يشرح [دليل أدوات HTTP](/docs/guides/http-tools/) أداة كاملة من البداية إلى النهاية.

```json
{
  "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](https://www.standardwebhooks.com/) ‏(`webhook-id` و`webhook-timestamp` و`webhook-signature`) باستخدام سر توقيع الأدوات في مشروعك (`GET /v1/tool_signing_secret`)، ويرسل `User-Agent: K-Agent/1`، فتستطيع نقطتك التحقق من أن الاستدعاء صادر من K-Agent.

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

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

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

```json
{
  "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": "تحقّق من السلة قبل الإجابة عن أسئلة رسوم التوصيل."
      }
    ]
  }
}
```

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

```json
{
  "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`. يعرض [دليل أدوات جهة العميل](/docs/guides/client-tools/) الدورة كاملة.

أسماء أدوات جهة العميل تطابق `^[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}` ما لم تفعّل **تشغيل الإجراءات الحقيقية**، والتحويلات والتذاكر توسم بأنها تجريبية ولا تصل أبدًا إلى مكتب التحويل أو الويب هوك.