crewAI/docs/ar/enterprise/features/flow-hitl-management.mdx

---
title: "إدارة HITL للتدفقات"
description: "مراجعة بشرية بمستوى المؤسسات للتدفقات مع إشعارات البريد الإلكتروني أولاً وقواعد التوجيه وإمكانيات الاستجابة التلقائية"
icon: "users-gear"
mode: "wide"
---

<Note>
تتطلب ميزات إدارة Flow HITL مزيّن `@human_feedback`، المتاح في **CrewAI الإصدار 1.8.0 أو أحدث**. تنطبق هذه الميزات تحديدًا على **التدفقات (Flows)**، وليس الأطقم (Crews).
</Note>

يوفر CrewAI Enterprise نظامًا شاملًا لإدارة الإنسان في الحلقة (HITL) للتدفقات يحوّل سير عمل الذكاء الاصطناعي إلى عمليات تعاونية بين الإنسان والذكاء الاصطناعي. تستخدم المنصة **بنية البريد الإلكتروني أولاً** التي تمكّن أي شخص لديه عنوان بريد إلكتروني من الرد على طلبات المراجعة — بدون الحاجة لحساب على المنصة.

## نظرة عامة

<CardGroup cols={3}>
  <Card title="تصميم البريد الإلكتروني أولاً" icon="envelope">
    يمكن للمستجيبين الرد مباشرة على رسائل الإشعار لتقديم الملاحظات
  </Card>
  <Card title="توجيه مرن" icon="route">
    توجيه الطلبات إلى بريد إلكتروني محدد بناءً على أنماط الطرق أو حالة التدفق
  </Card>
  <Card title="استجابة تلقائية" icon="clock">
    تهيئة استجابات احتياطية تلقائية عندما لا يرد أي شخص في الوقت المحدد
  </Card>
</CardGroup>

### الفوائد الرئيسية

- **نموذج ذهني بسيط**: عناوين البريد الإلكتروني عالمية؛ لا حاجة لإدارة مستخدمين أو أدوار المنصة
- **مستجيبون خارجيون**: يمكن لأي شخص لديه بريد إلكتروني الرد، حتى غير مستخدمي المنصة
- **تعيين ديناميكي**: سحب بريد المعيّن مباشرة من حالة التدفق (مثل `sales_rep_email`)
- **تهيئة مخفضة**: إعدادات أقل للتهيئة، وقت أسرع للقيمة
- **البريد الإلكتروني كقناة رئيسية**: يفضل معظم المستخدمين الرد عبر البريد الإلكتروني بدلاً من تسجيل الدخول إلى لوحة التحكم

## إعداد نقاط المراجعة البشرية في التدفقات

هيّئ نقاط تفتيش المراجعة البشرية داخل تدفقاتك باستخدام مزيّن `@human_feedback`. عندما يصل التنفيذ إلى نقطة مراجعة، يتوقف النظام ويُخطر المعيّن عبر البريد الإلكتروني وينتظر الاستجابة.

```python
from crewai.flow.flow import Flow, start, listen, or_
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult

class ContentApprovalFlow(Flow):
    @start()
    def generate_content(self):
        return "Generated marketing copy for Q1 campaign..."

    @human_feedback(
        message="Please review this content for brand compliance:",
        emit=["approved", "rejected", "needs_revision"],
    )
    @listen(or_("generate_content", "needs_revision"))
    def review_content(self):
        return "Marketing copy for review..."

    @listen("approved")
    def publish_content(self, result: HumanFeedbackResult):
        print(f"Publishing approved content. Reviewer notes: {result.feedback}")

    @listen("rejected")
    def archive_content(self, result: HumanFeedbackResult):
        print(f"Content rejected. Reason: {result.feedback}")
```

للحصول على تفاصيل التنفيذ الكاملة، راجع دليل [التغذية الراجعة البشرية في التدفقات](/ar/learn/human-feedback-in-flows).

### معاملات المزيّن

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `message` | `str` | الرسالة المعروضة للمراجع البشري |
| `emit` | `list[str]` | خيارات الاستجابة الصالحة (تُعرض كأزرار في الواجهة) |

## تهيئة المنصة

الوصول إلى تهيئة HITL من: **النشر** ← **الإعدادات** ← **تهيئة الإنسان في الحلقة**

<Frame>
  <img src="/images/enterprise/hitl-settings-overview.png" alt="HITL Configuration Settings" />
</Frame>

### إشعارات البريد الإلكتروني

تبديل لتفعيل أو تعطيل إشعارات البريد الإلكتروني لطلبات HITL.

| الإعداد | الافتراضي | الوصف |
|---------|---------|-------------|
| إشعارات البريد الإلكتروني | مفعّل | إرسال رسائل عند طلب الملاحظات |

<Note>
عند التعطيل، يجب على المستجيبين استخدام واجهة لوحة التحكم أو يجب تهيئة webhooks لأنظمة إشعارات مخصصة.
</Note>

### هدف SLA

تعيين وقت استجابة مستهدف لأغراض التتبع والمقاييس.

| الإعداد | الوصف |
|---------|-------------|
| هدف SLA (دقائق) | وقت الاستجابة المستهدف. يُستخدم لمقاييس لوحة التحكم وتتبع SLA |

اتركه فارغًا لتعطيل تتبع SLA.

## إشعارات واستجابات البريد الإلكتروني

يستخدم نظام HITL بنية البريد الإلكتروني أولاً حيث يمكن للمستجيبين الرد مباشرة على رسائل الإشعار.

### كيف تعمل استجابات البريد الإلكتروني

<Steps>
  <Step title="إرسال الإشعار">
    عند إنشاء طلب HITL، يُرسل بريد إلكتروني إلى المستجيب المعيّن مع محتوى المراجعة والسياق.
  </Step>
  <Step title="عنوان الرد">
    يتضمن البريد عنوان رد خاص مع رمز موقّع للمصادقة.
  </Step>
  <Step title="رد المستخدم">
    يرد المستجيب ببساطة على البريد بملاحظاته — بدون حاجة لتسجيل الدخول.
  </Step>
  <Step title="التحقق من الرمز">
    تستقبل المنصة الرد، وتتحقق من الرمز الموقّع، وتطابق بريد المرسل.
  </Step>
  <Step title="استئناف التدفق">
    تُسجل الملاحظات ويستمر التدفق مع مدخلات الإنسان.
  </Step>
</Steps>

### تنسيق الاستجابة

يمكن للمستجيبين الرد بـ:

- **خيار emit**: إذا تطابق الرد مع خيار `emit` (مثل "approved")، يُستخدم مباشرة
- **نص حر**: أي نص استجابة يُمرر إلى التدفق كملاحظات
- **نص عادي**: يُستخدم السطر الأول من نص الرد كملاحظات

### رسائل التأكيد

بعد معالجة الرد، يستلم المستجيب رسالة تأكيد تشير إلى ما إذا تم إرسال الملاحظات بنجاح أو حدث خطأ.

### أمان رمز البريد

- الرموز موقّعة تشفيريًا للأمان
- تنتهي صلاحية الرموز بعد 7 أيام
- يجب أن يتطابق بريد المرسل مع البريد المصرّح به في الرمز
- تُرسل رسائل تأكيد/خطأ بعد المعالجة

## قواعد التوجيه

توجيه طلبات HITL إلى عناوين بريد إلكتروني محددة بناءً على أنماط الطرق.

<Frame>
  <img src="/images/enterprise/hitl-settings-routing-rules.png" alt="HITL Routing Rules Configuration" />
</Frame>

### هيكل القاعدة

```json
{
  "name": "Approvals to Finance",
  "match": {
    "method_name": "approve_*"
  },
  "assign_to_email": "finance@company.com",
  "assign_from_input": "manager_email"
}
```

### أنماط المطابقة

| النمط | الوصف | مثال المطابقة |
|---------|-------------|---------------|
| `approve_*` | حرف بدل (أي أحرف) | `approve_payment`، `approve_vendor` |
| `review_?` | حرف واحد | `review_a`، `review_1` |
| `validate_payment` | مطابقة تامة | `validate_payment` فقط |

### أولوية التعيين

1. **تعيين ديناميكي** (`assign_from_input`): إذا تم تهيئته، يسحب البريد من حالة التدفق
2. **بريد ثابت** (`assign_to_email`): يرجع إلى البريد المهيأ
3. **منشئ النشر**: إذا لم تتطابق أي قاعدة، يُستخدم بريد منشئ النشر

### مثال التعيين الديناميكي

إذا كانت حالة تدفقك تحتوي على `{"sales_rep_email": "alice@company.com"}`، هيّئ:

```json
{
  "name": "Route to Sales Rep",
  "match": {
    "method_name": "review_*"
  },
  "assign_from_input": "sales_rep_email"
}
```

سيتم تعيين الطلب إلى `alice@company.com` تلقائيًا.

<Tip>
**حالة استخدام**: اسحب المعيّن من CRM أو قاعدة البيانات أو خطوة تدفق سابقة لتوجيه المراجعات ديناميكيًا إلى الشخص المناسب.
</Tip>

## الاستجابة التلقائية

الاستجابة تلقائيًا لطلبات HITL إذا لم يستجب أي شخص خلال المهلة المحددة. يضمن هذا عدم تعليق التدفقات إلى أجل غير مسمى.

### التهيئة

| الإعداد | الوصف |
|---------|-------------|
| مفعّل | تبديل لتفعيل الاستجابة التلقائية |
| المهلة (دقائق) | الوقت المنتظر قبل الاستجابة التلقائية |
| النتيجة الافتراضية | قيمة الاستجابة (يجب أن تطابق خيار `emit`) |

<Frame>
  <img src="/images/enterprise/hitl-settings-auto-respond.png" alt="HITL Auto-Response Configuration" />
</Frame>

### حالات الاستخدام

- **الامتثال لـ SLA**: ضمان عدم تعليق التدفقات إلى أجل غير مسمى
- **الموافقة الافتراضية**: الموافقة التلقائية على الطلبات منخفضة المخاطر بعد انتهاء المهلة
- **التراجع السلس**: المتابعة بافتراضي آمن عندما يكون المراجعون غير متاحين

<Warning>
استخدم الاستجابة التلقائية بحذر. فعّلها فقط للمراجعات غير الحرجة حيث تكون الاستجابة الافتراضية مقبولة.
</Warning>

## عملية المراجعة

### واجهة لوحة التحكم

توفر واجهة مراجعة HITL تجربة نظيفة ومركّزة للمراجعين:

- **عرض Markdown**: تنسيق غني لمحتوى المراجعة مع تمييز الصيغة
- **لوحة السياق**: عرض حالة التدفق وتاريخ التنفيذ والمعلومات ذات الصلة
- **إدخال الملاحظات**: تقديم ملاحظات وتعليقات مفصلة مع قرارك
- **إجراءات سريعة**: أزرار خيارات emit بنقرة واحدة مع تعليقات اختيارية

<Frame>
  <img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="HITL Pending Requests List" />
</Frame>

### طرق الاستجابة

يمكن للمراجعين الاستجابة عبر ثلاث قنوات:

| الطريقة | الوصف |
|--------|-------------|
| **الرد عبر البريد** | الرد مباشرة على رسالة الإشعار |
| **لوحة التحكم** | استخدام واجهة لوحة تحكم المؤسسة |
| **API/Webhook** | استجابة برمجية عبر API |

### السجل ومسار التدقيق

يتم تتبع كل تفاعل HITL بجدول زمني كامل:

- سجل القرارات (موافقة/رفض/مراجعة)
- هوية المراجع والطابع الزمني
- الملاحظات والتعليقات المقدمة
- طريقة الاستجابة (بريد/لوحة تحكم/API)
- مقاييس وقت الاستجابة

## التحليلات والمراقبة

تتبع أداء HITL مع تحليلات شاملة.

### لوحة تحكم الأداء

<Frame>
  <img src="/images/enterprise/hitl-metrics.png" alt="HITL Metrics Dashboard" />
</Frame>

<CardGroup cols={2}>
  <Card title="أوقات الاستجابة" icon="stopwatch">
    مراقبة متوسط وميديان أوقات الاستجابة حسب المراجع أو التدفق.
  </Card>
  <Card title="اتجاهات الحجم" icon="chart-bar">
    تحليل أنماط حجم المراجعة لتحسين قدرة الفريق.
  </Card>
  <Card title="توزيع القرارات" icon="chart-pie">
    عرض معدلات الموافقة/الرفض عبر أنواع المراجعة المختلفة.
  </Card>
  <Card title="تتبع SLA" icon="chart-line">
    تتبع نسبة المراجعات المكتملة ضمن أهداف SLA.
  </Card>
</CardGroup>

### التدقيق والامتثال

إمكانيات تدقيق جاهزة للمؤسسات للمتطلبات التنظيمية:

- سجل قرارات كامل مع الطوابع الزمنية
- التحقق من هوية المراجع
- سجلات تدقيق غير قابلة للتغيير
- إمكانيات التصدير لتقارير الامتثال

## حالات الاستخدام الشائعة

<AccordionGroup>
  <Accordion title="المراجعات الأمنية" icon="shield-halved">
    **حالة الاستخدام**: أتمتة استبيانات الأمان الداخلية مع التحقق البشري

    - يولّد الذكاء الاصطناعي الردود على الاستبيانات الأمنية
    - يراجع فريق الأمن ويتحقق من الدقة عبر البريد الإلكتروني
    - يتم تجميع الردود المعتمدة في التقديم النهائي
    - مسار تدقيق كامل للامتثال
  </Accordion>

  <Accordion title="الموافقة على المحتوى" icon="file-lines">
    **حالة الاستخدام**: محتوى تسويقي يتطلب مراجعة قانونية/العلامة التجارية

    - يولّد الذكاء الاصطناعي نصوص تسويقية أو محتوى وسائل التواصل
    - التوجيه إلى بريد فريق العلامة التجارية لمراجعة النبرة/الأسلوب
    - النشر التلقائي عند الموافقة
  </Accordion>

  <Accordion title="الموافقات المالية" icon="money-bill">
    **حالة الاستخدام**: تقارير النفقات، شروط العقود، تخصيصات الميزانية

    - يعالج الذكاء الاصطناعي مسبقًا ويصنف الطلبات المالية
    - التوجيه بناءً على عتبات المبالغ باستخدام التعيين الديناميكي
    - الحفاظ على مسار تدقيق كامل للامتثال المالي
  </Accordion>

  <Accordion title="التعيين الديناميكي من CRM" icon="database">
    **حالة الاستخدام**: توجيه المراجعات إلى مالكي الحسابات من CRM

    - يجلب التدفق بريد مالك الحساب من CRM
    - تخزين البريد في حالة التدفق (مثل `account_owner_email`)
    - استخدام `assign_from_input` للتوجيه إلى الشخص المناسب تلقائيًا
  </Accordion>

  <Accordion title="ضمان الجودة" icon="magnifying-glass">
    **حالة الاستخدام**: التحقق من مخرجات الذكاء الاصطناعي قبل التسليم للعميل

    - يولّد الذكاء الاصطناعي محتوى أو ردود موجهة للعميل
    - يراجع فريق ضمان الجودة عبر إشعار البريد الإلكتروني
    - حلقات الملاحظات تحسّن أداء الذكاء الاصطناعي بمرور الوقت
  </Accordion>
</AccordionGroup>

## واجهة Webhooks API

عندما تتوقف تدفقاتك للملاحظات البشرية، يمكنك تهيئة webhooks لإرسال بيانات الطلب إلى تطبيقك. يتيح هذا:

- بناء واجهات موافقة مخصصة
- التكامل مع الأدوات الداخلية (Jira، ServiceNow، لوحات تحكم مخصصة)
- توجيه الموافقات إلى أنظمة طرف ثالث
- إشعارات تطبيقات الجوال
- أنظمة القرار المؤتمتة

<Frame>
  <img src="/images/enterprise/hitl-settings-webhook.png" alt="HITL Webhook Configuration" />
</Frame>

### تهيئة Webhooks

<Steps>
  <Step title="الانتقال إلى الإعدادات">
    اذهب إلى **النشر** ← **الإعدادات** ← **الإنسان في الحلقة**
  </Step>
  <Step title="توسيع قسم Webhooks">
    انقر لتوسيع تهيئة **Webhooks**
  </Step>
  <Step title="إضافة عنوان Webhook">
    أدخل عنوان webhook الخاص بك (يجب أن يكون HTTPS في الإنتاج)
  </Step>
  <Step title="حفظ التهيئة">
    انقر على **حفظ التهيئة** للتفعيل
  </Step>
</Steps>

يمكنك تهيئة webhooks متعددة. يستقبل كل webhook نشط جميع أحداث HITL.

### أحداث Webhook

ستستقبل نقطة النهاية طلبات HTTP POST لهذه الأحداث:

| نوع الحدث | متى يُطلق |
|------------|----------------|
| `new_request` | يتوقف تدفق ويطلب ملاحظات بشرية |

### حمولة Webhook

تستقبل جميع webhooks حمولة JSON بهذا الهيكل:

```json
{
  "event": "new_request",
  "request": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_id": "flow_abc123",
    "method_name": "review_article",
    "message": "Please review this article for publication.",
    "emit_options": ["approved", "rejected", "request_changes"],
    "state": {
      "article_id": 12345,
      "author": "john@example.com",
      "category": "technology"
    },
    "metadata": {},
    "created_at": "2026-01-14T12:00:00Z"
  },
  "deployment": {
    "id": 456,
    "name": "Content Review Flow",
    "organization_id": 789
  },
  "callback_url": "https://api.crewai.com/...",
  "assigned_to_email": "reviewer@company.com"
}
```

### الرد على الطلبات

لإرسال الملاحظات، **أرسل POST إلى `callback_url`** المضمّن في حمولة webhook.

```http
POST {callback_url}
Content-Type: application/json

{
  "feedback": "Approved. Great article!",
  "source": "my_custom_app"
}
```

### الأمان

<Info>
جميع طلبات webhook موقّعة تشفيريًا باستخدام HMAC-SHA256 لضمان الأصالة ومنع التلاعب.
</Info>

#### أمان Webhook

- **توقيعات HMAC-SHA256**: يتضمن كل webhook توقيعًا تشفيريًا
- **أسرار لكل webhook**: لكل webhook سر توقيع فريد
- **مشفرة أثناء التخزين**: أسرار التوقيع مشفرة في قاعدة البيانات
- **التحقق من الطابع الزمني**: يمنع هجمات الإعادة

#### ترويسات التوقيع

يتضمن كل طلب webhook هذه الترويسات:

| الترويسة | الوصف |
|--------|-------------|
| `X-Signature` | توقيع HMAC-SHA256: `sha256=<hex_digest>` |
| `X-Timestamp` | الطابع الزمني Unix عند توقيع الطلب |

#### التحقق

تحقق بحساب:

```python
import hmac
import hashlib

expected = hmac.new(
    signing_secret.encode(),
    f"{timestamp}.{payload}".encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected, signature):
    # توقيع صالح
```

### معالجة الأخطاء

يجب أن تعيد نقطة نهاية webhook كود حالة 2xx لتأكيد الاستلام:

| استجابتك | سلوكنا |
|---------------|--------------|
| 2xx | تم تسليم Webhook بنجاح |
| 4xx/5xx | مسجل كفشل، بدون إعادة محاولة |
| مهلة (30 ثانية) | مسجل كفشل، بدون إعادة محاولة |

## الأمان والتحكم في الوصول المبني على الأدوار

### الوصول إلى لوحة التحكم

يُتحكم في وصول HITL على مستوى النشر:

| الصلاحية | القدرة |
|------------|------------|
| `manage_human_feedback` | تهيئة إعدادات HITL، عرض جميع الطلبات |
| `respond_to_human_feedback` | الرد على الطلبات، عرض الطلبات المعيّنة |

### تصريح استجابة البريد الإلكتروني

للردود عبر البريد:
1. يشفّر رمز الرد البريد المصرّح به
2. يجب أن يتطابق بريد المرسل مع بريد الرمز
3. يجب ألا يكون الرمز منتهي الصلاحية (7 أيام افتراضيًا)
4. يجب أن يكون الطلب لا يزال معلقًا

### مسار التدقيق

يتم تسجيل جميع إجراءات HITL:
- إنشاء الطلب
- تغييرات التعيين
- إرسال الاستجابة (مع المصدر: لوحة تحكم/بريد/API)
- حالة استئناف التدفق

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

### عدم إرسال الرسائل

1. تحقق من تفعيل "إشعارات البريد الإلكتروني" في التهيئة
2. تحقق من مطابقة قواعد التوجيه لاسم الطريقة
3. تحقق من صلاحية بريد المعيّن
4. تحقق من احتياطي منشئ النشر إذا لم تتطابق أي قواعد توجيه

### عدم معالجة ردود البريد

1. تحقق من عدم انتهاء صلاحية الرمز (7 أيام افتراضيًا)
2. تحقق من مطابقة بريد المرسل للبريد المعيّن
3. تأكد من أن الطلب لا يزال معلقًا (لم يتم الرد عليه بعد)

### عدم استئناف التدفق

1. تحقق من حالة الطلب في لوحة التحكم
2. تحقق من إمكانية الوصول إلى callback URL
3. تأكد من أن النشر لا يزال قيد التشغيل

## أفضل الممارسات

<Tip>
**ابدأ ببساطة**: ابدأ بإشعارات البريد الإلكتروني لمنشئ النشر، ثم أضف قواعد التوجيه مع نضوج سير عملك.
</Tip>

1. **استخدم التعيين الديناميكي**: اسحب عناوين بريد المعيّنين من حالة التدفق للتوجيه المرن.

2. **هيّئ الاستجابة التلقائية**: أعد استجابة احتياطية للمراجعات غير الحرجة لمنع تعليق التدفقات.

3. **راقب أوقات الاستجابة**: استخدم التحليلات لتحديد الاختناقات وتحسين عملية المراجعة.

4. **اجعل رسائل المراجعة واضحة**: اكتب رسائل واضحة وقابلة للتنفيذ في مزيّن `@human_feedback`.

5. **اختبر تدفق البريد**: أرسل طلبات اختبار للتحقق من تسليم البريد قبل الانتقال للإنتاج.

## الموارد ذات الصلة

<CardGroup cols={2}>
  <Card title="التغذية الراجعة البشرية في التدفقات" icon="code" href="/ar/learn/human-feedback-in-flows">
    دليل التنفيذ لمزيّن `@human_feedback`
  </Card>
  <Card title="دليل سير عمل Flow HITL" icon="route" href="/ar/enterprise/guides/human-in-the-loop">
    دليل خطوة بخطوة لإعداد سير عمل HITL
  </Card>
  <Card title="تهيئة RBAC" icon="shield-check" href="/ar/enterprise/features/rbac">
    تهيئة التحكم في الوصول المبني على الأدوار لمؤسستك
  </Card>
  <Card title="بث Webhook" icon="bolt" href="/ar/enterprise/features/webhook-streaming">
    إعداد إشعارات الأحداث في الوقت الفعلي
  </Card>
</CardGroup>