وثائق Amargi Agents

نظرة عامّة

Amargi Agents هي بيئة تشغيل وكلاء ذكاء اصطناعيّ متعدّدة المستأجرين. تُعرّف وكيلاً بدور (Role) + موجِّه نظام (System prompt) + قائمة أدوات (Tools)، ثمّ تستدعيه من أيّ مكان (Reach AI auto-replies، Escalate AI suggestions، أنظمتك الخاصّة عبر API). كلّ تشغيل (Run) يُلتقَط بكلّ تفاصيله: استدعاءات النموذج، رموز الإدخال/الإخراج، التكلفة بالدولار، الزمن، استدعاءات الأدوات (مع الإدخالات والإخراجات)، والقرار النهائيّ.

نُشغِّل Anthropic Claude افتراضياً (مُلزَم تعاقدياً بعدم تدريب نماذجها على مطالبات/ردود العملاء). الفِرَق المؤسسيّة يمكنها توصيل مفاتيح API الخاصّة بها أو الاستضافة الذاتيّة.

بدء سريع

1. افتح app.amargicreative.com → Agents.
2. اضغط "وكيل جديد". أدخل الاسم، الدور (مثلاً "مُصنّف الدعم")، ومُوجِّه النظام.
3. أرفق أدوات (Tools)، اختر من مكتبة الأدوات الجاهزة (lookup_order، send_email، query_kb) أو سجِّل أدوات مُخصَّصة عبر مانيفست القدرات.
4. اختبر في حقل اللعب: أدخل رسالة، شاهد التشغيل يتدفّق في الوقت الفعليّ مع كلّ استدعاء أداة + استدلال.
5. اقرنه بمحفِّز، استمع لرسائل Reach الواردة، أو استدعِه من Escalate عند فتح تذكرة، أو استدعِه من API الخاصّ بك.

مفاهيم رئيسيّة

الوكيل (Agent)

تعريف ثابت يحدّد كيف يتصرّف الوكيل عند استدعائه. يحتوي على: الاسم، الدور (Role)، مُوجِّه النظام (System Prompt)، قائمة الأدوات المسموحة، نموذج LLM (claude-sonnet-4، إلخ.)، حدود التكلفة، الحدّ الأقصى للدورات (لمنع الحلقات).

الأداة (Tool)

دالّة يمكن للوكيل استدعاؤها. مُعرَّفة بـ schema JSON (الاسم، الوصف، الإدخالات، الإخراجات). الأدوات إمّا داخليّة (يُديرها Amargi، مثل query_kb) أو مُخصَّصة (تُسجِّل نقطة نهاية HTTPS، يستدعيها وقت تشغيل الوكلاء عند الحاجة).

التشغيل (Run)

استدعاء واحد للوكيل. يحتوي السجلّ على: المُدخَل (الرسالة الأوّليّة)، كلّ دورة (turn) من حلقة النموذج (الاستدلال + استدعاءات الأدوات + الردود)، الإخراج النهائيّ، رموز الإدخال/الإخراج، التكلفة بالدولار، الزمن. كلّ run يكتب صفّاً في escalate.agent_runs.

مانيفست القدرات (Capability manifest)

وثيقة JSON قابلة للتسجيل تصف أداة مُخصَّصة: الاسم، الوصف، schema الإدخالات، schema الإخراجات، عنوان URL لاستدعاء (HTTPS، يجب أن يُوقَّع بـ HMAC). يُتيح للفِرَق إضافة أدوات داخليّة (lookup_account، charge_card، إلخ.) إلى مكتبة الأدوات الخاصّة بمؤسستهم بدون كتابة كود.

سلاسل الموافقة

بالنسبة للأدوات عالية المخاطر (تحويل أموال، حذف بيانات، إرسال إلى عميل خارجيّ)، يمكنك تعيين سياسة "تتطلّب موافقة بشر". عندما يحاول الوكيل استدعاء تلك الأداة، يتوقّف التشغيل، تُنشأ مهمّة للمراجَع البشريّ، يكمل التشغيل بعد الموافقة (أو يفشل إن رُفض). كلّ موافقة مُسجَّلة.

مهامّ شائعة

إنشاء وكيل مُصنّف

1. Agents → New agent
2. الدور: "Support Classifier".
3. مُوجِّه النظام: "صنِّف رسالة الدعم الواردة إلى billing | shipping | bug | general."
4. الأدوات: لا شيء (الإخراج الخالص يكفي).
5. النموذج: claude-haiku-4 (للسرعة والتكلفة).
6. حفظ، اختبار في حقل اللعب.

تسجيل أداة مُخصَّصة

1. اكتب مانيفست JSON يصف الأداة (الاسم، الإدخالات، الإخراجات، عنوان URL).
2. Tools → Register manifest — الصق الـ JSON.
3. يولّد Agents سرّاً HMAC. خادم الأداة الخاصّ بك يجب أن يتحقّق من الرأس X-Agents-Signature.
4. استخدم الأداة في تعريف أيّ وكيل.

استدعاء وكيل من API

1. احصل على مفتاح API من Hub (Settings → API Keys).
2. POST لـ https://agents.amargicreative.com/api/v1/agents/:id/runs بالحمولة JSON { "input": "...رسالة المستخدم..." }.
3. الردّ يحتوي على run_id (للاستفسار اللاحق) والإخراج النهائيّ.

مراقبة التكاليف

كلّ تشغيل يُسجِّل التكلفة بالدولار في خانة cost_usd. تُجمَّع تلقائياً لكلّ يوم + وكيل في بطاقة "Agent activity" على صفحة Reports. تُنشئ تنبيهات على عتبة التكلفة الشهريّة في Settings → AI Cost Quota.

مرجع API

كلّ نقاط نهاية Agents تحت https://agents.amargicreative.com/api/v1/.

• GET /api/v1/agents — سرد الوكلاء.
• POST /api/v1/agents — إنشاء وكيل جديد.
• GET /api/v1/agents/:id — استرجاع وكيل.
• POST /api/v1/agents/:id/runs — استدعاء وكيل (synchronous).
• POST /api/v1/agents/:id/runs/async — استدعاء وكيل (asynchronous، يُعيد run_id فوراً).
• GET /api/v1/runs/:id — استرجاع تشغيل بالتفاصيل الكاملة.
• GET /api/v1/runs — سرد التشغيلات. تصفية حسب agent_id، from، to، agent_role.
• GET /api/v1/runs/summary — مُلخَّص مُجمَّع (تشغيلات لكلّ يوم، التكلفة، الرموز).
• POST /api/v1/tools — تسجيل أداة مُخصَّصة عبر مانيفست.
• GET /api/v1/tools — سرد الأدوات (مُدمَجة + مُخصَّصة).
• POST /api/v1/approvals/:id/approve — الموافقة على تشغيل مُعلَّق.

التكامل مع المنتجات الأخرى

• Reach — الردود الآليّة للذكاء الاصطناعي تستدعي وكلاء عند استلام رسالة WhatsApp. يَظهَر التشغيل في سجلّ المحادثة + لوحة المُشغِّل.
• Escalate — يستدعي وكلاء على حدث ticket.opened لاقتراح حلّ (يَظهَر للمشغّل كرسالة "AI suggestion" قابلة للقبول/الرفض).
• Your systems — استدعِ من أيّ خادم خلفيّ عبر API. مفيد لتلخيص تذكرة، تصنيف بريد، أو أيّ مهمّة تستفيد من LLM.

الحصول على المساعدة

• دعم البريد الإلكترونيّ: contact@amargicreative.com
• موقف الخصوصيّة (تدريب Anthropic، احتفاظ التشغيل): موقف الخصوصيّة.