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

# دليل إعداد وكيل الذكاء الاصطناعي

> انتقل من مفتاح ترخيص إلى وكيل ذكاء اصطناعي يرد على تذاكر Discord الخاصة بك.

يستغرق الإعداد نحو 15 دقيقة. تحتاج إلى أربعة أشياء:

* **مفتاح ترخيص** EchoAuth AI Agent. [اشترِ واحدًا من المتجر](https://shop.echoauth.dev/product/echos-ai-agent-hosted) إذا لم يكن لديك بعد.
* **خادم Discord** يمكنك إضافة بوتات إليه وإدارة الأدوار فيه.
* **مفتاح API من [OpenRouter](https://openrouter.ai)**. مفتاح OpenRouter واحد يغطي كل ما يحتاجه الوكيل: الإجابات ولقطات الشاشة والبحث.
* اختياريًا، **موقع توثيق** أو بعض التوثيق المكتوب ليجيب منه الوكيل.

نحن نستضيف وكيلك ونبقيه يعمل. تقوم بإعداده من لوحة التحكم على [agent.echoauth.dev](https://agent.echoauth.dev).

> [!NOTE]
>
> **الإعداد الموصى به.** جرى الاختبار طويل الأمد باستخدام OpenRouter فقط، مع هذه النماذج الثلاثة:
>
> | الدور | النموذج |
> | - | - |
> | المحادثة / الوكيل | `deepseek/deepseek-v4-flash-0731` |
> | التضمين (Embedding) | `qwen/qwen3-embedding-8b` |
> | الرؤية (اكتشاف الصور) | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` |
>
> مزودون آخرون (NVIDIA وOpenAI وAnthropic) متاحون في لوحة التحكم، لكن هذا هو المزيج الذي اختبرناه مع مرور الوقت.

## 1. أنشئ حسابك

**1. افتح صفحة التسجيل**

انتقل إلى [agent.echoauth.dev/register](https://agent.echoauth.dev/register).

**2. أدخل مفتاح الترخيص**

الصق المفتاح من بريد الشراء. يبدو مثل `ECHO-XXXX-XXXX-XXXX-XXXX`.

**3. اختر اسم مستخدم وكلمة مرور**

يجب أن تكون كلمة المرور 8 أحرف على الأقل. انقر على **Create account**.

![نموذج التسجيل مع حقول مفتاح الترخيص واسم المستخدم وكلمة المرور](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/01-register.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=572419f600e4182cf06122e903cf3aa6)

صفحة التسجيل

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

![لوحة التحكم تعرض وكيلًا واحدًا وحالة الترخيص والاستخدام](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/02-dashboard.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=2397a77fc1428106e09dcbc3b2869dab)

لوحة التحكم بعد تسجيل الدخول

> [!NOTE]
>
> إذا ظهرت عبارة **No agents yet**، فافتح **License** في الشريط الجانبي وتحقق من أن ترخيصك نشط.

انقر على وكيلك لفتح صفحته. كل ما عدا ذلك في هذا الدليل يبدأ من هنا: يفتح **Configure** الإعدادات، ويعرض **Live logs** ما يفعله الوكيل، ويطبّق **Update Agent** الإعدادات التي تتطلب إعادة نشر.

![صفحة الوكيل مع Configure وLive logs وRestart وUpdate Agent](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/03-agent.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=6c4ca792bd16efd8e9e175519f337123)

صفحة الوكيل

## 2. أنشئ بوت Discord الخاص بك

يجيب وكيلك عبر بوت Discord يخصك. أنشئ واحدًا في Discord Developer Portal.

**1. أنشئ تطبيقًا**

افتح [Discord Developer Portal](https://discord.com/developers/applications) وانقر على **New Application**. سمّه باسم وكيل الدعم لديك، مثل "Acme Support".

**2. فعّل Message Content intent**

انتقل إلى **Bot**. ضمن **Privileged Gateway Intents**، فعّل **Message Content Intent** واحفظ.

> [!WARNING]
>
> بدون هذا الـ intent، يتلقى البوت رسائل فارغة ولا يرد أبدًا.

**3. انسخ رمز البوت**

وأنت ما زلت في **Bot**، انقر على **Reset Token** وانسخ الرمز. ستلصقه في لوحة التحكم في القسم التالي. ابقه سريًا: كل من لديه الرمز يمكنه التحكم في بوتك.

**4. ادعُ البوت إلى خادمك**

انتقل إلى **OAuth2** → **URL Generator**. حدّد النطاقين `bot` و`applications.commands` ثم صلاحيات البوت هذه:

* View Channels
* Send Messages
* Read Message History
* Embed Links
* Attach Files

افتح الرابط الناتج وأضف البوت إلى خادمك.

**5. أعط البوت صلاحية الوصول إلى فئة التذاكر**

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

## 3. أضف مفاتيحك

أنشئ مفتاح API من [openrouter.ai/keys](https://openrouter.ai/keys) وأضف بعض الرصيد إلى حساب OpenRouter الخاص بك. نموذج الرؤية مجاني، لكن نموذجي المحادثة والتضمين يُدفع مقابلهما حسب الاستخدام.

ثم، في صفحة وكيلك، انقر على **Configure** وافتح تبويب **API Keys**.

![تبويب API Keys يعرض مفتاح OpenRouter API ورمز بوت Discord معلّمين كـ configured](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/04-keys.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=635dd8eb112950e6f74cfdc24c4f5664)

تبويب API Keys، مع مفتاح OpenRouter ورمز بوت Discord مُعدَّين

1. الصق مفتاحك في **OpenRouter API Key**.
2. الصق **Discord Bot Token**.
3. انقر على **Save**.

يمكنك ترك حقول OpenAI وAnthropic وNVIDIA فارغة. تُخزَّن المفاتيح مشفّرة ولا تُعرض مرة أخرى بعد الحفظ. تؤكد شارة **configured** أن المفتاح مُعَدّ.

## 4. اختر نماذج الذكاء الاصطناعي

افتح تبويب **AI Settings**. يستخدم الوكيل ثلاثة نماذج. اضبط الثلاثة على **OpenRouter** واختر النماذج الموصى بها:

| الإعداد | ماذا يفعل | المزود | النموذج |
| - | - | - | - |
| **Chat / Agent Model** | يكتب الإجابات ويقرر ما يبحث عنه في مستنداتك. | OpenRouter | `deepseek/deepseek-v4-flash-0731` |
| **Vision Model** | يقرأ لقطات الشاشة التي يرفقها العملاء بالتذاكر. | OpenRouter | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` |
| **Embedding Model** | يفهرس توثيقك ويبحث فيه. | OpenRouter | `qwen/qwen3-embedding-8b` |

![تبويب AI Settings مع اختيار OpenRouter لنماذج المحادثة والرؤية والتضمين](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/05-ai.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=9c43f2bab0d0ade4e7a897f04f0a21f0)

تبويب AI Settings مع نماذج OpenRouter الموصى بها

> [!NOTE]
>
> تحت نموذج التضمين، تحذر لوحة التحكم من أنه يتجاوز 2000 بُعد. هذا متوقع مع `qwen/qwen3-embedding-8b`. لا يزال البحث يعمل: فهو يفحص كل مقطع بدلًا من استخدام فهرس، ويبقى سريعًا مع قاعدة معرفة من بضعة آلاف مقاطع.

ثم اكتب **Base Prompt**. وهو التعليمات الدائمة للوكيل: لمن يعمل وما النبرة التي يستخدمها وما الذي لا يجب أن يفعله أبدًا. مثلًا:

```text theme={null}
You are the support agent for Acme Store. Be friendly and concise.
Answer only from the documentation. If you are not sure, ask a staff member to step in.
```

> [!WARNING]
>
> اختر نموذج التضمين قبل أن تفهرس أي شيء. تغييره لاحقًا يجعل الفهرس الحالي غير صالح للاستخدام حتى تعيد بناءه.

## 5. اربطه بتذاكرك

افتح تبويب **Discord**. تخبر هذه الإعدادات الوكيل أين يجيب ومن يُعدّ من الفريق.

![تبويب Discord مع أدوار المالك وأدوار الفريق ومعرّفات فئات التذاكر ومعرّفات بوتات التذاكر ونماذج الصور](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/06-discord.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=43f9146b21aa094f8d7629f409930f57)

تبويب Discord

لنسخ المعرّفات، فعّل **Developer Mode** في Discord من **User Settings** → **Advanced**. ثم انقر بزر الماوس الأيمن على دور أو فئة أو مستخدم واختر **Copy ID**.

> [accordion] Owner Role IDs
>
> الأدوار التي يمكنها استخدام كل أوامر الشرطة المائلة، بما في ذلك `/pause_bot` و`/edit_base`. افصل بين المعرّفات المتعددة بفواصل.

> [accordion] Staff Role IDs
>
> أدوار فريق الدعم لديك. عندما يكتب أحد أفراد الفريق في تذكرة، يتراجع الوكيل ويبقى صامتًا في تلك التذكرة. لإعادته، اذكر البوت في التذكرة أو استخدم `/restart` هناك.

> [accordion] Ticket Category IDs
>
> الفئات التي تُنشأ فيها قنوات تذاكرك. يجيب الوكيل فقط داخل هذه الفئات.

> [accordion] Ticket Bot IDs
>
> معرّف مستخدم بوت التذاكر لديك، مثل Ticket Tool أو SellAuth Tickets. يتجاهل الوكيل البوتات الأخرى، لذا أضف بوتك هنا ليتمكن الوكيل من قراءة رسالة فتح التذكرة.

> [accordion] Image Models
>
> نماذج رؤية احتياطية، واحد في كل سطر، تُجرَّب بالترتيب إذا فشل نموذج الرؤية من AI Settings. ضع هذه البدائل:\
> `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free`\
> `google/gemma-4-31b-it:free`\
> `google/gemma-4-26b-a4b-it:free`\
> `thinkingmachines/inkling-small:free`\
> `dots-studio/dots-3-note-preview:free`

انقر على **Save**.

## 6. أعط الوكيل توثيقك

افتح تبويب **Knowledge Base**. يجيب الوكيل من مصدرين، ويمكنك استخدام أحدهما أو كليهما.

![تبويب Knowledge Base مع زر Index documentation وDocs URL وقاعدة المعرفة الداخلية](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/07-knowledge.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=18150d070975d8635a2a87c251b04dfa)

تبويب Knowledge Base

> [tab] Docs site
>
> استخدم هذا إذا كان توثيقك منشورًا على Mintlify.
>
> 1. أدخل **Docs URL** الخاص بك، مثل `https://docs.acme-store.com`، بدون شرطة مائلة في النهاية. يجب أن يقدّم الموقع `/llms.txt`، وهو ما يفعله Mintlify تلقائيًا.
> 2. انقر على **Save**، ثم انتقل إلى صفحة وكيلك وانقر على **Update Agent**.
> 3. بالعودة إلى هذا التبويب، انقر على **Index documentation**. تستغرق بضع مئات من الصفحات بضع دقائق، ويمكنك مغادرة الصفحة أثناء ذلك.
>
> مع ضبط **Sync Mode** على **Poll llms.txt hourly**، يفحص الوكيل توثيقك كل ساعة ويعيد فهرسة الصفحات التي تغيّرت فقط.

> [tab] Internal knowledge base
>
> استخدم هذا لكل ما ليس على موقع توثيق: الأسئلة الشائعة والسياسات ورموز الأخطاء.
>
> 1. مرّر إلى **Internal Knowledge Base**.
> 2. الصق نصك، أو انقر على **Load file** واختر ملف `.txt` أو `.md`.
> 3. انقر على **Save**.
>
> يفهرسه الوكيل خلال نحو دقيقة. النص العادي كاف: العناوين بأحرف كبيرة (ALL CAPS) أو بين أسطر `=====` تصبح أقسامًا قابلة للبحث.

أبقِ **Documentation Retrieval** و**Agentic Retrieval** مفعّلين. مع تفعيل الاسترجاع، يبحث الوكيل فقط عن المقاطع ذات الصلة بكل سؤال بدلًا من قراءة كل شيء في كل مرة.

## 7. اضبط توقيت الرد والتصعيد

افتح تبويب **Behavior**.

![تبويب Behavior مع توقيت الرد وكلمات طلب المساعدة البشرية](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/08-behavior.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=14df915b4ac0f9860f6e3a6b3a61d318)

تبويب Behavior

ينتظر الوكيل حتى يتوقف العميل عن الكتابة، ثم يجيب على كل شيء في رد واحد. كل رسالة جديدة تعيد تشغيل المؤقت.

| الإعداد | الافتراضي | المعنى |
| - | - | - |
| After ticket opens | 45 ث | انتظار بعد أول رسالة، لأن العملاء غالبًا ما يضيفون تفاصيل أو لقطات شاشة. |
| After each message | 30 ث | مدة الهدوء اللازمة بعد الرسائل اللاحقة قبل الرد. |
| Maximum wait | 180 ث | يرد بعد هذه المدة حتى لو استمر العميل في الكتابة. |

تحت **Human Help Keywords**، اسرد الكلمات التي يجب أن تُحيل التذكرة إلى فريقك، كلمة في كل سطر. مثل `refund` أو `chargeback` أو `real person`.

## 8. فعّل التنبيهات (اختياري)

افتح تبويب **Notifications** والصق معرّف قناة خاصة بالفريق. ينشر الوكيل هناك عندما يقترب ترخيصك من الانتهاء وعندما يرفض مزود الذكاء الاصطناعي مفتاحك أو تنفد الحصة.

![تبويب Notifications مع معرّف قناة الإشعارات](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/09-notifications.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=5906f4bf0dbdf4fa308c4958553bded2)

تبويب Notifications

## 9. ابدأ الوكيل

عُد إلى صفحة وكيلك وانقر على **Update Agent**. يُعيد هذا نشر الوكيل برمز البوت ورابط التوثيق ونموذج التضمين الخاصين بك. تظهر المخرجات تحت الزر أثناء التشغيل.

> [!NOTE]
>
> تصل معظم الإعدادات إلى الوكيل العامل خلال نحو دقيقة، دون إعادة نشر. تحتاج إلى **Update Agent** فقط بعد تغيير **Discord Bot Token** أو **Docs URL** أو **Embedding Model** أو **Sync Mode**.

للتحقق من أن كل شيء يعمل:

1. افتح تذكرة اختبار في خادمك واطرح سؤالًا يجيب عنه توثيقك.
2. افتح **Live logs** في صفحة وكيلك وراقب الوكيل وهو يستلم الرسالة ويبحث في توثيقك ويرد.

![Live logs تعرض بدء الوكيل ومزامنته وبحثه في التوثيق ورده في تذكرة](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/11-logs.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=18d1bd77e85407858cd81751cd36388e)

Live logs

تظهر شارة حالة وكيلك **Online** عندما يكون قيد التشغيل.

## أوامر الشرطة المائلة

بمجرد أن يكون الوكيل في خادمك، يمكن للمالكين والفريق التحكم فيه من Discord.

| الأمر | من | ماذا يفعل |
| - | - | - |
| `/stop` | المالك، الفريق | يمنع الوكيل من الرد في هذه القناة. |
| `/restart` | المالك، الفريق | يسمح للوكيل بالرد في هذه القناة مرة أخرى. |
| `/mute_existing` | المالك، الفريق | يوقف الوكيل في كل تذكرة مفتوحة بالفعل. |
| `/pause_bot` | المالك | يوقف الوكيل مؤقتًا في كل مكان. |
| `/resume_bot` | المالك | يستأنف عمل الوكيل في كل مكان. |
| `/edit_base` | المالك | يعدّل الـ base prompt. |
| `/chat_model` | المالك | يغيّر نموذج المحادثة. |

يمكنك أيضًا إيقاف الوكيل مؤقتًا من لوحة التحكم باستخدام **Global Bot Pause** في تبويب **Discord**.

## أبقِ ترخيصك نشطًا

يبقى وكيلك متصلًا ما دام ترخيصك نشطًا. تعرض صفحة **License** الأيام المتبقية وتاريخ الانتهاء.

![صفحة الترخيص مع الحالة والأيام المتبقية والخطط المتاحة](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/10-license.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=62db270604520c9a0c2815db6201b908)

صفحة License

للتجديد، اشترِ مفتاحًا جديدًا من [المتجر](https://shop.echoauth.dev/product/echos-ai-agent-hosted) وانقر على **Renew license** والصق المفتاح. يُضاف الوقت إلى ترخيصك الحالي.

## استكشاف الأخطاء وإصلاحها

> [accordion] البوت متصل لكنه لا يرد أبدًا
>
> * تحقق من أن **Message Content Intent** مفعّل في Discord Developer Portal.
> * تحقق من أن معرّف فئة التذكرة موجود في **Ticket Category IDs**.
> * تحقق من أن البوت يستطيع رؤية تلك الفئة وإرسال الرسائل فيها.
> * تحقق من أن أحد أفراد الفريق لم يكتب بالفعل في التذكرة. اذكر البوت أو استخدم `/restart` لإعادته.
> * تحقق من أن **Global Bot Pause** مطفأ.

> [accordion] يتجاهل البوت رسالة فتح التذكرة
>
> أضف معرّف مستخدم بوت التذاكر الخاص بك إلى **Ticket Bot IDs** في تبويب **Discord**.

> [accordion] الوكيل لا يستخدم توثيقي
>
> افتح تبويب **Knowledge Base**. إذا كتب **Documentation is not indexed yet**، فانقر على **Index documentation**. وإذا كتب **The index does not match the embedding model**، فانقر على **Clear and rebuild the index**، أو أعد ضبط نموذج التضمين إلى النموذج المعروض واحفظ.

> [accordion] تفشل الردود أو الفهرسة مع خطأ من OpenRouter
>
> تحقق من أن حساب OpenRouter لديه رصيد وأن المفتاح في تبويب **API Keys** لا يزال صالحًا. قد تخضع النماذج المجانية مثل نموذج الرؤية لحد من معدل الطلبات في أوقات الزحام؛ عندئذ ينتقل الوكيل إلى النموذج التالي في **Image Models**.

> [accordion] توقف الوكيل عن الاستجابة
>
> افتح **Live logs** وابحث عن أخطاء، مثل مفتاح غير صالح أو رصيد نفد. ثم انقر على **Restart** في صفحة الوكيل. إذا لم ينفع ذلك، فانقر على **Update Agent**.


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