إدارة HITL للتدفقات

​

نظرة عامة

​

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

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

​

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

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}")

​

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

​

تهيئة المنصة

​

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

​

هدف SLA

​

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

​

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

​

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

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

​

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

​

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

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

​

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

​

هيكل القاعدة

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

​

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

​

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

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

​

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

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

​

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

​

التهيئة

​

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

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

​

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

​

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

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

​

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

​

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

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

​

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

​

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

​

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

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

​

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

​

واجهة Webhooks API

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

​

تهيئة Webhooks

​

أحداث Webhook

​

حمولة Webhook

{
  "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}
Content-Type: application/json

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

​

الأمان

​

أمان Webhook

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

​

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

​

التحقق

import hmac
import hashlib

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

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

​

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

​

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

​

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

​

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

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

​

مسار التدقيق

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

​

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

​

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

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

​

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

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

​

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

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

​

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

1. استخدم التعيين الديناميكي: اسحب عناوين بريد المعيّنين من حالة التدفق للتوجيه المرن.
2. هيّئ الاستجابة التلقائية: أعد استجابة احتياطية للمراجعات غير الحرجة لمنع تعليق التدفقات.
3. راقب أوقات الاستجابة: استخدم التحليلات لتحديد الاختناقات وتحسين عملية المراجعة.
4. اجعل رسائل المراجعة واضحة: اكتب رسائل واضحة وقابلة للتنفيذ في مزيّن @human_feedback.
5. اختبر تدفق البريد: أرسل طلبات اختبار للتحقق من تسليم البريد قبل الانتقال للإنتاج.

​

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