# دوال المساعد الذكي

## **كيفية حذف سجل محادثة مع المساعد الذكي**

clear\_assistant\_chat\_history() - هذه الدالة تحذف سجل محادثات العميل مع المساعد. لا تأخذ أي معاملات.

### مثال 

1. إعدادات كتلة المُنشئ

<div data-with-frame="true"><figure><img src="/files/30a047addceaa8031431b648f03fca2afca6b45a" alt=""><figcaption></figcaption></figure></div>

2. إعدادات علامة تبويب المساعد الذكي

<div data-with-frame="true"><figure><img src="/files/b0a0d77236792cb805e3cef71e4b9969921151c5" alt="" width="563"><figcaption></figcaption></figure></div>

## **كيفية إرسال سؤال إلى المساعد الذكي**

ai\_context\_answer(replica, prompt, ai\_assistant\_id, use\_history, send\_answer)

المعلمات:

<table><thead><tr><th width="173">المعامل</th><th width="221">الوصف</th><th>ملاحظة</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark> replica </td><td>معامل مطلوب، رسالة للمساعد</td><td></td></tr><tr><td>prompt</td><td>معامل اختياري، تعليمات للمساعد</td><td>إذا لم يتم تحديد المعامل ولكن تم توفير المعامل ai_assistant_id، فسيتم استخدام التعليمات من إعدادات المساعد المحدد</td></tr><tr><td>ai_assistant_id </td><td>معرّف المساعد الذي سيُرسل إليه السؤال؛</td><td>إذا لم يتم توفيره، فسيُستخدم المساعد بدون إعدادات افتراضية</td></tr><tr><td>use_history</td><td>ما إذا كان ينبغي للمساعد استخدام سجل المحادثة للإجابة عن السؤال</td><td>True - استخدام، False - عدم الاستخدام. افتراضيًا - True</td></tr><tr><td>send_answer</td><td>إرسال الرد بعد انتهاء مهلة المساعد</td><td>للتفعيل، مرّر "1"</td></tr></tbody></table>

مزيد من التفاصيل حول `send_answer` المعلمة:

تتضمن إعدادات المساعد معاملات يمكن ضبطها في حال استغرق رد الروبوت وقتًا طويلاً

<div data-with-frame="true"><figure><img src="/files/4dce78d38fca4aec9c72a7d85aeae1a013062507" alt="" width="375"><figcaption></figcaption></figure></div>

في محادثة عادية مع المساعد (وليس عبر دالة)، إذا استغرق الرد وقتًا أطول من الحد المحدد (مثل 20 ثانية)، يتم إخطار العميل بالتأخير. ثم تُرسل إجابة المساعد إلى الدردشة بمجرد إنشائها.

بالنسبة للطلبات التي تتم عبر دالة في الآلة الحاسبة، إذا استغرق المساعد وقتًا طويلاً للرد، تُدرج رسالة تأخير في نتيجة الدالة. يتيح هذا المعامل إرسال رد المساعد بشكل منفصل بمجرد أن يصبح جاهزًا.&#x20;

### كيفية تعليم الروبوت تحليل خبرته الخاصة وإنشاء أزرار

لنستخدم `clean_assistant_chat_history()` و `ai_context_answer(replica, prompt)` الدوال في المثال أدناه. كما يلزم الوصول إلى مكوّن الآلة الحاسبة ضمن منشئ القمع.

يوضح هذا المثال كيفية استخدام `replica` و `prompt` المعاملات بشكل فعّال في التطبيق العملي.&#x20;

من الضروري إنشاء كتلة في المُنشئ تحتوي على حقل فارغ مع المتغيرات المضمنة **#{replica\_rec2}** و **#{ai\_answer\_rec}**، والتي تمثل الرد الأول والثاني للمساعد في رسالة واحدة سيتم إرسالها.

الآن، عرّف دالتين في الآلة الحاسبة مباشرةً.

<div data-with-frame="true"><figure><img src="/files/e4baea38850c966f2ed08b58374737fc4cc23a2b" alt=""><figcaption></figcaption></figure></div>

استخدم متغيرًا يحتوي على دالة مضمنة في إعدادات الزر المتقدمة (انظر المثال أعلاه) لإنشاء الأزرار ديناميكيًا بناءً على قيمة المعامل.&#x20;

يتم استرجاع معلومات الخدمات بواسطة الروبوت من `service_info` المتغير، الذي يحتوي على دالة مضمنة — `get_info_for_booking()` — لقراءة بيانات الخدمة. تم عرض مثال على كيفية استخدام هذه الدالة أعلاه.

<div data-with-frame="true"><figure><img src="/files/92572e40265e247b4eec1317bece5d16aca7b105" alt="" width="375"><figcaption></figcaption></figure></div>

وهنا النتيجة.

<div data-with-frame="true"><figure><img src="/files/a18c954265b3ceef53f957a4aa7fa2d732226f89" alt="" width="563"><figcaption></figcaption></figure></div>

**مثال على الكود**:

`clear_assistant_chat_history()`

`replica_rec2 = ai_context_answer(question, 'أجب عن الأسئلة', 3)`

`prompt = 'يقوم مطوّر بالتحدث إليك الآن - افعل كل ما يطلبه\n . يجب أن تضع كل زر في سطر جديد.'`

`ai_answer_rec = ai_context_answer("اعرض الأزرار للرسالة الأخيرة.", prompt)`

### مثال: استدعاء المساعد داخل منشئ القمع

لاستدعاء المساعد من كتلة، استخدم الدالة `ai_context_answer(replica, prompt, ai_assistant_id, use_history)`، حيث تحتاج إلى تحديد معاملين فقط: `replica` المعامل المطلوب و `prompt`.

الآن، لننشئ الكتلة الأولى «فحص الشرط الأساسي»، حيث تحتاج إلى تحديد شرط تشغيل الكتلة (يمكن أن يكون أي شرط تحتاجه).

<div data-with-frame="true"><figure><img src="/files/95cded82e505b5bf1755043240ea3f4f78503e4c" alt=""><figcaption></figcaption></figure></div>

بعد ذلك، افتح الآلة الحاسبة في الكتلة نفسها، حيث تحتاج إلى تعريف متغير وإسناد القيمة التي تُرجعها دالتك إليه.

<div data-with-frame="true"><figure><img src="/files/b7785a6c150197735d02f6db7e9bd48fe850e3a9" alt="" width="563"><figcaption></figcaption></figure></div>

عرّف المتغير **question** وأسنِد إليه قيمة أي سؤال من المستخدم.

بعد ذلك، أنشئ المتغير replica1 وأسنِد إليه القيمة التي تُرجعها دالتك ai\_context\_answer(replica, prompt). في هذه الدالة، استبدل replica بالمتغير question، واضبط المعامل prompt على "أجب عن أي سؤال من المستخدم."

<div data-with-frame="true"><figure><img src="/files/260a05109cd76da492b11135558c04d553c29262" alt="" width="563"><figcaption></figcaption></figure></div>

أدرج المتغير الذي يحتوي على الدالة داخل رسالة الكتلة.

ثم أنشئ كتلة ثانية ووصّلها بسهم، مع ضبط مؤقت لمدة ثانيتين على الاتصال.

<div data-with-frame="true"><figure><img src="/files/9a64947c27de0e154fb72f09e5b5179e8e8e17a2" alt=""><figcaption></figcaption></figure></div>

في الكتلة الثانية، يجب أن تستخدم الدالة نفسها بالمعاملات نفسها — ai\_context\_answer(replica, prompt).

افتح الآلة الحاسبة في الكتلة الثانية وعرّف المتغير الثاني باسم replica2.

<div data-with-frame="true"><figure><img src="/files/57a4fd9e8e989c887da029e9866a2524acddaaa5" alt=""><figcaption></figcaption></figure></div>

في المعامل prompt، قدّم تعليمات للمساعد: يجب أن يحسب عدد الأسماء التي وردت في رسالته السابقة.

في المعامل replica، قدّم رسالة المساعد: "كم عدد الأسماء التي كانت في رسالتك السابقة؟"

ثم أدرج المتغير replica2 داخل رسالة الكتلة الثانية.

<div data-with-frame="true"><figure><img src="/files/1323c0a19f404ddd3ca0aba4362b3c9b430743f3" alt="" width="563"><figcaption></figcaption></figure></div>

اكتمل إعداد الكتلة.

إذا لم يكن المساعد مفعّلًا، فانتقل إلى علامة التبويب "AI Assistant" وفعّل المساعد باختيار الدور "disabled":

<div data-with-frame="true"><figure><img src="/files/991bf12fd2138431afc66509c4e84bfbef529c29" alt="" width="292"><figcaption></figcaption></figure></div>

الآن، دعنا نختبر مساعدنا في نافذة اختبار الروبوت.

<div data-with-frame="true"><figure><img src="/files/4a51f8a92250c2d2c378b4c75ad9659d57af0a5d" alt="" width="375"><figcaption></figcaption></figure></div>

لقد عمل الروبوت بشكل صحيح.

## كيفية العمل مع Google Sheets

get\_info\_from\_table(sheet\_id, number\_sheet, sheet\_json\_keys, start\_row, end\_row, start\_col, end\_col) - هذه الدالة مخصصة لقراءة البيانات من جدول بيانات.

<table><thead><tr><th width="248">المعلمات</th><th>الوصف</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark> sheet_id</td><td>معرّف جدول Google Spreadsheet</td></tr><tr><td>number_sheet</td><td>رقم الورقة في جدول البيانات؛ افتراضيًا = 1</td></tr><tr><td>sheet_json_keys </td><td>معامل اختياري — مفتاح الوصول إلى بيانات جدول البيانات</td></tr><tr><td>start_row</td><td><p>معامل اختياري، عدد صحيح. يحدد بداية نطاق الصفوف.
</p><p>مرّر رقم الصف الذي يجب قراءة قيم الجدول منه بشكل شامل. يجب إدخال القيمة بدون علامات اقتباس.</p></td></tr><tr><td>end_row</td><td>معامل اختياري، عدد صحيح. يحدد نهاية نطاق الصفوف.
<br>مرّر رقم الصف الذي يجب قراءة قيم الجدول حتى وصولًا إليه بشكل شامل. يجب إدخال القيمة بدون علامات اقتباس.</td></tr><tr><td>start_col</td><td>معامل اختياري، نص. يحدد بداية نطاق الأعمدة.
<br>مرّر حرف العمود الذي يجب قراءة قيم الجدول منه بشكل شامل. يجب إحاطة القيمة بعلامات اقتباس</td></tr><tr><td>end_col</td><td>معامل اختياري، نص. يحدد نهاية نطاق الأعمدة.
<br>مرّر حرف العمود الذي يجب قراءة قيم الجدول حتى وصولًا إليه بشكل شامل. يجب إحاطة القيمة بعلامات اقتباس.</td></tr></tbody></table>

مثال على كتابة المعاملات:

<div data-with-frame="true"><figure><img src="/files/5d3f5e8b97cc458e98045c42802aa3b85d59faa4" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/d7b3ba6c3e77df4710ca1a2d6d2ffa05a3eb302f" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="warning" %}

## يرجى الملاحظة

المعاملات لتحديد نطاق الصفوف والأعمدة `(start_row, end_row, start_col, end_col)` تتيح للمساعد قراءة بيانات جدول البيانات بدءًا من الموقع المطلوب داخل الجدول.
{% endhint %}

{% hint style="info" %}
سلوك الدالة عند تحديد نطاق جزئي يكون كما يلي:

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

**مثال:**

الاستدعاء `get_info_from_table('<<spreadsheet id>>', 2, None, 2, 5, 'a', 'd')` يسترجع جميع البيانات بدءًا من الصف 2، العمود 2 (B)، حتى الصف 5، وبين العمودين A وD.
{% endhint %}

{% hint style="warning" %}

## يرجى الملاحظة

لتحسين الأداء والموثوقية، نوصي بـ **تخزين جميع البيانات مؤقتًا** من جدول Google Sheet الخاص بك داخل متغيرات المشروع عند العمل عليه.

**الفوائد الرئيسية:**

1. **أداء محسّن:** يُسرّع بشكل كبير زمن استجابة الدردشة الآلية من خلال الوصول إلى المتغيرات المحلية بدلًا من الاستعلام عن جدول البيانات الخارجي مع كل طلب.
2. **موثوقية أفضل:** يقلل من الأخطاء المتعلقة بزمن تأخر الشبكة أو حصص واجهة برمجة التطبيقات أو أذونات الوصول إلى جدول البيانات.
3. **اتساق البيانات:** يضمن تخزين البيانات في إعدادات المشروع **حصول جميع المستخدمين على وصول متزامن ومتسق** إلى نفس مجموعة البيانات، مما يمنع التباينات أثناء التحديثات.
   {% endhint %}

#### مثال على الاستخدام

{% hint style="info" %}
يمكنك قراءة المزيد عن **get\_info\_from\_table** الدالة في المقال "[Google Sheets for AI Assistant](/doc/ar/chatbot/ai/jdawl-google-llmsaad-althky.md)."
{% endhint %}

## كيفية إدارة الحجوزات عبر الإنترنت

get\_info\_for\_booking(slot\_interval, company\_id) - صُممت هذه الدالة لقراءة بيانات الخدمة من نظام الحجز عبر الإنترنت المُعدّ.

وتقبل معاملات اختيارية:

1. slot\_interval (اختياري) - فاصل زمني بالدقائق بين الفترات الزمنية المتاحة. الصيغة المتوقعة: عدد صحيح يقبل القسمة على 5. القيمة الافتراضية: 60 (دقيقة).
2. company\_id اختياري) - معرّف فرع. الصيغة المتوقعة: *عدد صحيح* أو *مصفوفة من الأعداد الصحيحة*. عند توفير هذا المعامل، ستُعاد فقط البيانات الخاصة بالفرع (الفروع) المحدد.
   \
   مثال: 50142، "50142"، أو "\[50142, 66352]"

{% hint style="warning" %}
لا يُنصح بتعيين قيمة صغيرة جدًا (مثل أقل من 30)، لأن المساعد سيولد عددًا كبيرًا جدًا من الفترات الزمنية. &#x20;
{% endhint %}

### مثال على الاستخدام

أولًا، تحتاج إلى إعداد كتلة تحدّث المعلومات حول جميع الخدمات بعد تهيئة إعدادات الفرع في قسم "Services".

يجب تعريف هذه الكتلة قبل أن يبدأ المساعد بالعمل، لضمان ألا يقوم الذكاء الاصطناعي بتوليد إجابات عشوائية.

<div data-with-frame="true"><figure><img src="/files/bf8bf8433a37b9eb25ce755cdcacb334fdcd1af5" alt=""><figcaption></figcaption></figure></div>

بعد ذلك، شغّل الكتلة في نافذة اختبار الروبوت لتحديث المتغير:

<div data-with-frame="true"><figure><img src="/files/666b3ddcee807c617bb295f75fa237478f1484a1" alt="" width="375"><figcaption></figcaption></figure></div>

بعد ذلك، سيظهر المتغير المحدد الذي يحتوي على بيانات خدمة الحجز عبر الإنترنت في قسم متغيرات المشروع ضمن "Project settings."

<div data-with-frame="true"><figure><img src="/files/8e67d9b3e91c886325ef6a7c747a80c137e9c9a1" alt="" width="563"><figcaption></figcaption></figure></div>

يخزن هذا المتغير قيم الخدمة التي سيستخدمها روبوت الذكاء الاصطناعي في عملياته. سيكون المتغير service\_info متاحًا لجميع عملاء المشروع.

بعد ذلك، لننتقل إلى إعداد الكتلة التالية.

<div data-with-frame="true"><figure><img src="/files/d4a2f47e68490006a1e36c300af779404a635d5e" alt=""><figcaption></figcaption></figure></div>

تؤدي هذه الكتلة الوظائف التالية:

أ) يتم استدعاؤها في إعدادات المساعد لإنشاء سجل باستخدام المتغيرات المتعلقة بالخدمة؛

ب) تنشئ حجزًا للعميل؛

ج) تحدّث متغيرات المشروع بعد الحجز، وتزيل الفترات الزمنية التي لم تعد متاحة في الجدول.

إذا تم إعداد الروبوت بشكل صحيح، فبعد تلقي جميع البيانات من العميل، سيرسل الذكاء الاصطناعي المعلومات إلى الكتلة المحددة. في تلك الكتلة، سيتم حجز الخدمة للعميل باستخدام الدالة create\_booking\_by\_name(!service\_name, !date, !date\_time, company\_id).

<div data-with-frame="true"><figure><img src="/files/3a4f32f50e021996ea3bb2087bcc8fc2399baa05" alt=""><figcaption></figcaption></figure></div>

تُمرَّر القيم التي يجمعها الروبوت كمعاملات إلى create\_booking\_by\_name(!service\_name, !date, !date\_time, company\_id).

تنشئ الدالة create\_booking\_by\_name(service\_name, date, date\_time, company\_id) حجزًا في النظام باستخدام البيانات التي يقدمها مساعد الذكاء الاصطناعي. وهي تقبل ثلاثة معاملات مطلوبة لإنشاء الحجز:

<table><thead><tr><th width="297">المعلمات</th><th>الوصف</th></tr></thead><tbody><tr><td>! service_name</td><td>معلمة مطلوبة، اسم الخدمة</td></tr><tr><td>! date</td><td>التاريخ بصيغة dd.mm.yyyy</td></tr><tr><td>! date_time</td><td>وقت الخدمة بصيغة hh:mm</td></tr><tr><td>company_id </td><td>معرّف الفرع، اختياري.
<br>إذا تم تحديده، فسيتم إنشاء الحجز للخدمة ذات الاسم المحدد التابعة لهذا الفرع بالذات.
<br>قد يكون هذا المعامل ضروريًا في الحالات التي تمتلك فيها فروع متعددة خدمات تحمل الاسم نفسه.</td></tr></tbody></table>

نظرًا لأن المعلومات حول الفترات المتاحة لن تعود محدثة، يُستخدم المتغير نفسه مع دالته المضمنة لتحديث التواريخ والأوقات المتاحة للحجز.

<div data-with-frame="true"><figure><img src="/files/106117a951c47489c78a27245c8602942221b1e5" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}

## يرجى الملاحظة

إذا كانت هناك أي تغييرات في الجدول أو الموظفين أو الخدمات، فشغّل الكتلة التي تحتوي على متغير المشروع مع الدالة المضمنة في وضع الاختبار (انظر الشكل: الكتلة 1).
{% endhint %}

{% hint style="info" %}
[تم شرح كيفية إعداد روبوت ذكاء اصطناعي للحجز عبر الإنترنت في المقال الذي يحمل الاسم نفسه.](/doc/ar/chatbot/ai/online-booking.md)
{% endhint %}

## استرجاع الحجوزات من الجدول

get\_records\_from\_table(table\_id, start\_row, count, start\_col, end\_col) - استرجاع الحجوزات من الجدول

| المعامل    | الوصف                                                       | ملاحظة                                                                                        |
| ---------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| table\_id  | معرّف الجدول                                                |                                                                                               |
| start\_row | معامل اختياري، عدد صحيح. يحدد بداية نطاق الصفوف.            | مرّر رقم الصف الذي يجب قراءة قيم الجدول منه بشكل شامل. يُكتب بدون علامات اقتباس.              |
| count      | معامل اختياري، عدد صحيح. يحدد عدد الصفوف المطلوب استرجاعها. | افتراضيًا - 1000، والحد الأقصى - 5000. يُكتب بدون علامات اقتباس.                              |
| start\_col | معامل اختياري، نص. يحدد بداية نطاق الأعمدة.                 | مرّر حرف العمود الذي يجب قراءة قيم الجدول منه بشكل شامل. يُكتب بين علامتي اقتباس.             |
| end\_col   | معامل اختياري، نص. يحدد نهاية نطاق الأعمدة.                 | مرّر حرف العمود الذي يجب قراءة قيم الجدول حتى وصولًا إليه بشكل شامل. يُكتب بين علامتي اقتباس. |

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

### مثال (الآلة الحاسبة)

إذا كنت بحاجة إلى استرجاع السجلات من الجدول، افتح قسم "Calculator" في إعدادات الكتلة وأدخل الدالة مع المعاملات المطلوبة.

<div data-with-frame="true"><figure><img src="/files/e455d670ad5fcac549713f262cf324f75070e4ab" alt=""><figcaption></figcaption></figure></div>

لتمرير المعاملات كمتغير مشروع، أضف بادئة اسم المتغير الذي يحتوي على الدالة بـ **project**.

<div data-with-frame="true"><figure><img src="/files/55e928707b18a3607f36698d83c5c559e19ae700" alt=""><figcaption></figcaption></figure></div>

هذا مثال الجدول.

<div data-with-frame="true"><figure><img src="/files/98533f9c98de9dd949213c99dcdae663c3e9cc94" alt="" width="563"><figcaption></figcaption></figure></div>

سيستجيب الروبوت على النحو التالي.

<div data-with-frame="true"><figure><img src="/files/8579d74e2f1b9b847c61caf3b13e03d5b43e1272" alt="" width="375"><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/ar/chatbot/ai/functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.