> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karzoun.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# أدوات مخصصة: انتظار العودة والعودة إلى الوكيل

> متى تفعّل انتظار العودة على نية وكيل المساعد، وكيف تبني فرعاً ينتهي بإجراء العودة إلى الوكيل، مع سيناريوهات وأمثلة وأخطاء شائعة.

أحياناً يحتاج الوكيل معلومة **من خارج قدراته المدمجة**: استعلام ERP، تحقق من شحنة عبر API، حساب سعر خاص، أو تشغيل منطق شروط في الأتمتة — ثم **يكمل الحوار** بنفس الجلسة وكأنه استدعى أداة داخلية.

يوفّر كرزون نمط **انتظار العودة (أداة مخصصة)** على النية مع إجراء **العودة إلى الوكيل** (`Return to agent` / `copilotAgentReturn`).

يشرح هذا الدليل متى تختار مخرجاً مقابل أداة مخصصة، وكيف تبني الفرع حتى لا يصمت العميل بلا رد.

## الفكرة بجملة

```
العميل يطلب شيئاً يحتاج نظاماً خارجياً
  → الوكيل يستدعي نية بأدوات/نوايا العقدة
    (مع تفعيل «انتظار العودة»)
  → المسار على منفذ النية يعمل
    (HTTP، شروط، إجراءات ذكاء اصطناعي…)
  → فرع ينتهي بـ «العودة إلى الوكيل» + نتيجة
  → الوكيل يستأنف ويرد للعميل مستنداً للنتيجة
```

بدون **العودة إلى الوكيل**، الأداة المخصصة **لا تكتمل**: العميل لا يسمع رداً إضافياً من تلك الأداة (صمت متعمّد — بلا اعتذار تلقائي).

## متى مخرج؟ ومتى أداة مخصصة؟

| النمط | إعداد النية | ماذا يحدث بعد المنفذ | هل يعود الوكيل؟ |
| - | - | - | - |
| **مخرج (افتراضي)** | «انتظار العودة» **معطّل** | المسار يغادر جلسة الوكيل (تحويل، Flow حجز، رسالة…) | فقط إن أعدت العميل لاحقاً لعقدة وكيل جديدة |
| **أداة مخصصة** | «انتظار العودة» **مفعّل** | المسار ينفّذ عملاً ثم **يجب** أن ينتهي بـ **العودة إلى الوكيل** | نعم — عبر ذلك الإجراء فقط |

| اختر **مخرج** عندما… | اختر **أداة مخصصة** عندما… |
| - | - |
| التحويل لموظف / طابور ([تصعيد منظّم](/ar/help-center/guides/ai/agent-handover)) | تحتاج نتيجة API أو ERP ثم رد الوكيل للعميل |
| إرسال [واتساب Flow](/ar/help-center/guides/ai/agent-booking-flows) للحجز (غالباً مخرج) | تحقق مخزون/سعر/أهلية ثم صياغة رد ذكي |
| إنهاء الحوار برسالة ثابتة | تشغيل شروط + توليد/تلخيص ثم إكمال المحادثة |

<Tip>
  حجز Flow والتصعيد المنظّم يبقيان عادةً **مخارج**. لا تفعّل انتظار العودة عليهما إلا إن صمّمتَ عمداً أن يعود الوكيل بعد عمل المسار بنتيجة أداة.
</Tip>

## المكوّنان في المحرر

### 1) على عقدة وكيل المساعد — النية

في [عقدة وكيل المساعد](/ar/help-center/guides/automations/nodes/ai-agent) أضف أداة/نية:

| الحقل | ماذا تضبط |
| - | - |
| **الاسم** | اسم أداة واضح للنموذج (مثال: `track_order`، `check_eligibility`) — يفضّل `snake_case` |
| **الوصف** | متى يستدعيها الوكيل (وما لا يستدعيها له) |
| **المعاملات** | ما يجمعه من الدردشة قبل الاستدعاء (رقم طلب، مدينة…) مع حفظها في حقول/متغيرات إن لزم |
| **انتظار العودة (أداة مخصصة)** | **مفعّل** لهذا النمط |
| **المخرج التالي** | أول عقدة على فرع الأداة (غالباً طلب HTTP أو عقدة إجراءات) |

بعد التفعيل تظهر شارة **أداة مخصصة** على بطاقة النية، ويظهر منفذها على اللوحة كالمعتاد.

<Frame caption="تفعيل انتظار العودة على النية">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/karzoun-chat/images/help/ai/agent-custom-tool-intent-await-gif.webp" alt="تفعيل انتظار العودة وظهور شارة أداة مخصصة على النية" />
</Frame>

### 2) على المسار — إجراء العودة إلى الوكيل

الإجراء يعيش في فئة **إجراءات الذكاء الاصطناعي** (عقدة **إجراءات الذكاء الاصطناعي** أو قائمة أدوات الذكاء الاصطناعي):

| | |
| - | - |
| **الاسم في الواجهة** | العودة إلى الوكيل / Return to agent |
| **الاسم البرمجي** | `copilotAgentReturn` (في الكتالوج: `automations:copilotAgentReturn`) |
| **الحقل الأهم** | **نتيجة (Result payload)** — مسار حقل/متغير قيمته تُمرَّر للوكيل كنتيجة الأداة |

| ماذا تضع في «نتيجة» | مثال |
| - | - |
| جسم استجابة HTTP | مسار المتغير الذي يحفظه إجراء الطلب (مثل `variables.httpBody` أو الحقل الذي اخترته في حفظ الاستجابة) |
| كائن JSON بعد معالجة | مخرج دالة JS أو عملية JSON |
| فارغ | يُستخدم احتياطياً معاملات النية المحفوظة (`copilotIntentParams`) إن وُجدت — الأفضل تمرير نتيجة صريحة |

<Frame caption="إجراء العودة إلى الوكيل وحقل النتيجة">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/karzoun-chat/images/help/ai/agent-custom-tool-return-action.webp" alt="إجراء العودة إلى الوكيل مع حقل نتيجة مربوط بمتغير" />
</Frame>

<Frame caption="نية أداة مخصصة وفرع ينتهي بالعودة">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/karzoun-chat/images/help/ai/agent-custom-tool-await-return.webp" alt="بطاقة نية بأداة مخصصة وفرع مسار ينتهي بالعودة إلى الوكيل" />
</Frame>

## تسلسل التشغيل (ماذا يحدث تحت الغطاء باختصار)

1. الوكيل يقرر استدعاء النية ويجمع المعاملات.
2. يمكنه إرسال **رد قصير اختياري** للعميل («لحظة أتأكد من الشحنة…») ثم يخرج للمنفذ.
3. النظام يُبقي جلسة الوكيل ويحجز **تذكرة انتظار** للمحادثة (مهلة تقريبية **١٠ دقائق**).
4. فرع الأتمتة يعمل بحرية (شروط، HTTP، إجراءات ذكاء اصطناعي…).
5. **العودة إلى الوكيل** تقرأ النتيجة، تحقّنها للوكيل كنتيجة أداة، فيكمل الدور ويرد للعميل — وتظهر استدعاءات الأداة في البريد الوارد كالمعتاد.
6. إن لم تُنفَّذ العودة، أو انتهت المهلة، أو تكلّم العميل برسالة جديدة قبل العودة: **لا يُختلق رد اعتذار** من الوكيل لتلك الأداة.

## سيناريوهات جاهزة للبناء

### أ) تتبع شحنة عبر API خارجي

**الهدف:** العميل يرسل رقم الطلب؛ النظام يستعلم عن حالة الشحنة؛ الوكيل يصيغ الرد بلغة ودودة.

```
وكيل المساعد
  نية: track_order
  انتظار العودة: ✓
  معاملات: order_id (إلزامي) → احفظه في متغير/حقل
       │
       ▼
طلب HTTP (GET /shipments/{order_id})
  احفظ الاستجابة في متغير (مثلاً variables.shipmentStatus)
       │
       ▼
العودة إلى الوكيل
  نتيجة = variables.shipmentStatus
```

في **وصف النية** اكتب: متى تُستدعى، وأن الرقم يجب جمعه من الدردشة أو من سياق معروف، وألا يخترع حالة شحنة من ذاكرته.

<Frame caption="فرع تتبع شحنة: نية → HTTP → عودة">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/karzoun-chat/images/help/ai/agent-custom-tool-branch-wire.webp" alt="مسار أتمتة من نية تتبع شحنة عبر HTTP ثم العودة إلى الوكيل" />
</Frame>

### ب) أهلية عرض / كوبون من نظام الولاء

**الهدف:** التحقق من أهلية العميل قبل أن يعد الوكيل بخصم.

```
نية: check_promo_eligibility (انتظار عودة ✓)
  معاملات: promo_code اختيارياً؛ معرّف العميل من السياق إن وُجد
       │
       ▼
شرط: هل للعميل وسوم/خصائص معيّنة؟
  ├── لا → العودة بنتيجة { eligible: false, reason: "..." }
  └── نعم → HTTP لنظام الولاء → العودة بنتيجة الاستجابة
```

الوكيل بعد العودة يشرح للعميل بلغة طبيعية **دون** اختراع أهلية لم تأتِ في النتيجة.

### ج) حساب سعر مخصص ثم صياغة عرض

**الهدف:** منطق تسعير في الأتمتة (JS أو API) ثم رد بيعي من الوكيل.

```
نية: quote_custom_price (انتظار عودة ✓)
  معاملات: product_ref، quantity، city
       │
       ▼
دالة JavaScript أو HTTP حاسبة أسعار
  → احفظ { price, currency, validUntil }
       │
       ▼
(اختياري) إجراء توليد نص داخل إجراءات الذكاء الاصطناعي
  لصياغة مسودة داخلية — أو اترك الصياغة للوكيل بعد العودة
       │
       ▼
العودة إلى الوكيل بالنتيجة المنظمة
```

### د) إثراء من CRM ثم متابعة الحوار

**الهدف:** جلب سجل تذاكر/ملاحظات من نظام خارجي قبل أن يجيب الوكيل على شكوى متكررة.

```
نية: fetch_crm_context (انتظار عودة ✓)
       │
       ▼
HTTP / GraphQL داخلي → احفظ الملخص
       │
       ▼
العودة إلى الوكيل
```

بعدها يستطيع الوكيل الاعتذار والتصعيد إن لزم — مع معرفة حقيقية من النتيجة لا من التخمين.

### ه) ماذا لا تضع هنا؟

| الحالة | الأنسب بدل أداة مخصصة |
| - | - |
| تحويل لموظف بملاحظات منظمة | [تصعيد منظّم](/ar/help-center/guides/ai/agent-handover) كمخرج |
| جمع حقول حجز في نموذج واتساب | [حجز عبر Flow](/ar/help-center/guides/ai/agent-booking-flows) كمخرج |
| بحث معرفة / كتالوج داخل كرزون | [قدرات الوكيل](/ar/help-center/guides/ai/agent-tools-access) + [أدوات الوكيل الذكي](/ar/help-center/guides/automations/ai-tools-actions) دون مغادرة الجلسة |
| توليد/تصنيف/استخراج لمرة واحدة بلا حوار وكيل | عقدة [إجراءات الذكاء الاصطناعي](/ar/help-center/guides/automations/ai-tools-actions#عقدة-إجراءات-الذكاء-الاصطناعي) في المسار مباشرة |

## قواعد ذهبية

1. **كل فرع `انتظار العودة = ✓` ينتهي بـ العودة إلى الوكيل** — وإلا صمت الأداة.
2. **مرّر نتيجة صريحة** في حقل النتيجة؛ لا تعتمد على مهلة الخمول «لإكمال» الأداة (الخمول يمسح التذكرة دون اختراع نتيجة).
3. **اجعل وصف النية صارماً** حتى لا يستدعيها الوكيل لأسئلة يستطيع حلّها بمعرفة/قدرات داخلية.
4. **رد قصير أثناء الانتظار** اختياري ومفيد إن كان HTTP بطيئاً — لا تعد بنتيجة نهائية قبل العودة.
5. **اختبر المسار المنشور** من محادثة حقيقية: استدعاء النية، نجاح HTTP، وفشل HTTP (هل ما زلت تعود بنتيجة خطأ مفهومة؟).

## إن لم يحدث… (سلوك متعمّد)

| الحدث | النتيجة التي يراها العميل/الباني |
| - | - |
| لم تُنفَّذ «العودة إلى الوكيل» | لا رد إضافي من تلك الأداة — **بلا** اعتذار تلقائي من الوكيل |
| انتهت مهلة تذكرة الانتظار (\~١٠ دقائق) | نفس الصمت للأداة؛ الجلسة قد تُدار لاحقاً برسالة جديدة كالمعتاد |
| رسالة جديدة من العميل أثناء انتظار الأداة | يُلغى انتظار الأداة ويُعالج الدور الجديد |
| مهلة خمول الجلسة أثناء الانتظار | يتقدم المسار من منطق الخمول **دون** اختراع نتيجة أداة |
| تنفيذ «العودة» بلا تذكرة صالحة | **لا عملية** صامتة (لا خطأ مزعج على العميل) |

## أخطاء شائعة

| الخطأ | النتيجة | الصواب |
| - | - | - |
| تفعيل انتظار العودة دون إجراء العودة في الفرع | العميل ينتظر ولا يصل رد من الأداة | أنهِ الفرع دائماً بـ العودة إلى الوكيل |
| تفعيل انتظار العودة على نية تصعيد | الوكيل قد يعود بعد «تحويل» غير مكتمل | اترك التصعيد **مخرجاً** |
| نتيجة تشير لمسار حقل فارغ/خاطئ | الوكيل يستلم فارغاً أو معاملات النية فقط | اختبر مسار الحقل من سجل التنفيذ |
| الاعتماد على الخمول بدل العودة | لا تُحقَن نتيجة؛ صمت الأداة | العودة فقط هي مسار النجاح |
| نية بلا معاملات بينما API يحتاج معرّفاً | استدعاء فاشل أو تخمين من الوكيل | اجعل المعامل إلزامياً أو خذه من سياق التنفيذ |
| وضع العودة في فرع غير متصل بمنفذ النية | التذكرة لا تُستهلَك كما تتوقع | اربط منفذ النية → سلسلة العمل → العودة |

## خطوات البناء السريعة

<Steps>
  <Step title="عرّف النية على وكيل المساعد">
    اسم، وصف قوي، معاملات، وفعّل **انتظار العودة (أداة مخصصة)**. انشر مسودة العقدة حتى يظهر المنفذ.
  </Step>

  <Step title="ابنِ فرع العمل">
    من منفذ النية: طلب HTTP و/أو شروط و/أو إجراءات ذكاء اصطناعي. احفظ المخرج في متغير واضح.
  </Step>

  <Step title="أنهِ بـ العودة إلى الوكيل">
    من عقدة إجراءات الذكاء الاصطناعي أضف **العودة إلى الوكيل** واختر مسار **النتيجة**.
  </Step>

  <Step title="انشر واختبر">
    مسار مسودة لا يكفي على القناة. اختبر نجاحاً وفشلاً للـ API، وتأكد أن رد الوكيل يعتمد على النتيجة لا على التخمين.
  </Step>
</Steps>

## الخطوة التالية

بنيت أداة مخصصة تعود للوكيل. بعد ذلك:

* راجع حدود الجلسة والصمت: [حدود معروفة وحلول بديلة](/ar/help-center/guides/ai/known-limitations).
* أو اربط مخارج أخرى: [تصعيد منظّم](/ar/help-center/guides/ai/agent-handover) · [حجز عبر Flow](/ar/help-center/guides/ai/agent-booking-flows).

## ذات صلة

* [عقدة: وكيل المساعد](/ar/help-center/guides/automations/nodes/ai-agent)
* [النشر عبر الأتمتة](/ar/help-center/guides/ai/deploy-with-automations)
* [أدوات الوكيل الذكي وإجراءات الذكاء الاصطناعي](/ar/help-center/guides/automations/ai-tools-actions)
* [تصعيد منظّم](/ar/help-center/guides/ai/agent-handover)
* [حجز عبر واتساب Flow](/ar/help-center/guides/ai/agent-booking-flows)
* [طلب HTTP](/ar/help-center/guides/automations/nodes/actions/http-request)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.