الانتقال من inputs.id إلى restore_from_state_id

Warning

تمرير id داخل inputs لترطيب تدفق @persist هو مهجور ومقرر إزالته في إصدار مستقبلي. البديل، restore_from_state_id، متاح في CrewAI v1.14.5 وما بعده — الخطوات أدناه تنطبق بمجرد أن تقوم بالتحديث.

نظرة عامة

الطريقة الموثقة لترطيب تدفق @persist من تنفيذ سابق هي تمرير UUID لذلك التنفيذ كـ inputs.id. الآن، تكشف CrewAI عن حقل مخصص، restore_from_state_id، الذي يقوم بنفس الترطيب دون تحميل حمولة inputs — ودون ربط مفتاح الترطيب بهوية التنفيذ الجديد.

الانتقال

إذا كنت حالياً تبدأ تدفق @persist باستخدام inputs={"id": ...}:

# مهجور
flow = CounterFlow()
flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"})

انتقل إلى restore_from_state_id:

# مدعوم
flow = CounterFlow()
flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv")

تتمتع الوضعيتان بمعاني سلالة مختلفة:

• inputs={"id": <uuid>} (مهجور) — استئناف: تكتب الكتابات تحت المعرف المقدم، مما يمدد نفس تاريخ flow_uuid.
• restore_from_state_id=<uuid> — تفرع: يترطب الحالة من اللقطة، ثم يكتب تحت state.id جديدة. يتم الحفاظ على تاريخ التدفق المصدر.

لأغلب سيناريوهات الإنتاج — إعادة تشغيل تدفق تم تهيئته من حالة سابقة — فإن التفرع هو ما تريده. راجع إتقان حالة التدفق للحصول على النموذج الذهني الكامل.

إذا كنت تبدأ تدفقك عبر واجهة برمجة تطبيقات CrewAI AMP REST، راجع AMP أدناه لهجرة الحمولة المعادلة.

لماذا نقوم بإهمال inputs.id لـ @persist

inputs.id هو حالياً الطريقة الموثقة لاستئناف تدفق @persist من تنفيذ سابق. المشكلة هي أن نفس UUID يقوم بوظيفتين في وقت واحد:

1. يحدد أي لقطة يترطب منها @persist — تحميل الحالة المحفوظة تحت ذلك UUID.
2. يصبح معرف تنفيذ التدفق الجديد (state.id في SDK؛ يظهر كـ flow_id في بعض السياقات) — كل كتابة @persist من هذه البداية أيضاً تقع تحت نفس UUID.

هذه الوظيفة المزدوجة هي السبب الجذري للمشاكل التي يصفها هذا الدليل. لأن UUID المقدم هو أيضاً معرف التنفيذ الجديد، فإن بدايتين تمرران نفس inputs.id ليست تنفيذين متميزين — إنهما تشتركان في معرف، وتشاركان في سجل الاستمرارية، و(على AMP) تشتركان في صف في قائمة التنفيذات. لا توجد طريقة للقول “ترطب من هذه اللقطة، ولكن سجل هذا التشغيل بشكل منفصل” دون تقسيم المسؤوليتين.

restore_from_state_id هو هذا الانقسام. إنه يخبر @persist من أي لقطة يترطب، بينما يترك التنفيذ الجديد حراً لاستلام state.id جديدة. لم يعد مصدر الترطيب والتشغيل المسجل نفس UUID — وهو ما تريده معظم سيناريوهات الإنتاج فعلياً.

جدول إزالة

من المقرر إزالة inputs.id لترطيب @persist في إصدار مستقبلي من CrewAI. لا يوجد قطع صارم فوري — تظل التدفقات الحالية تعمل — ولكن بمجرد أن تقوم بالتحديث إلى v1.14.5 أو ما بعده، يجب أن يستخدم الكود الجديد restore_from_state_id، ويجب أن تهاجر التدفقات الحالية في الفرصة المناسبة التالية.

AMP

إذا كنت تنشر تدفقك إلى CrewAI AMP، فإن الهجرة تمتد إلى الحمولة التي تبدأ بها المرسلة إلى طاقمك المنشور، وتظهر الأعراض المرئية لإعادة استخدام inputs.id على لوحة معلومات النشر. تغطي القسمان الفرعيان أدناه كلاهما.

هجرة حمولة البداية

إذا كنت حالياً تبدأ تدفقاً منشوراً عن طريق تضمين id في inputs:

# مهجور
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  -d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \
  https://your-crew-url.crewai.com/kickoff

نقل UUID إلى حقل restoreFromStateId في المستوى الأعلى:

# مدعوم
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  -d '{
        "inputs": {"topic": "AI Agent Frameworks"},
        "restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv"
      }' \
  https://your-crew-url.crewai.com/kickoff

يجلس restoreFromStateId بجانب inputs في حمولة البداية، وليس داخلها. الآن، يحمل كائن inputs فقط القيم التي تستهلكها تدفقك فعلياً.

ماذا يحدث عند إعادة استخدام inputs.id

عندما تتلقى AMP بداية لتدفق يتطابق inputs.id الخاص به مع تنفيذ موجود، فإنه يحل إلى السجل الموجود بدلاً من إنشاء سجل جديد. من لوحة معلومات النشر سترى:

• حالة التنفيذ — حالة التشغيل الجديد تحل محل حالة التشغيل السابق. يمكن أن تعود تنفيذات مكتملة إلى جارية، أو يمكن أن تتحول تشغيلات مكتملة إلى خطأ إذا فشلت البداية الجديدة — في كلتا الحالتين، لم تعد لوحة المعلومات تعكس التشغيل الأصلي.
• التتبع — تتراكم تتبعات OTel عبر البدايات لأنها تشترك في نفس معرف التنفيذ؛ تتبعات التشغيل السابق إما تُستبدل بـ، أو تُخلط مع، تشغيل الجديد. لم يعد إعادة التشغيل خطوة بخطوة يتوافق مع تنفيذ واحد.
• قائمة التنفيذات — البدايات التي يجب أن تظهر كصفوف منفصلة تتقلص إلى إدخال واحد، مما يخفي التاريخ.

تساعد الهجرة إلى restoreFromStateId في الحفاظ على كل بداية كتنفيذ خاص بها — مع حالتها الخاصة، وتتبعها، وصفها في القائمة — بينما لا تزال ترطب الحالة من تشغيل سابق.

هل تحتاج مساعدة؟

اتصل بفريق الدعم لدينا إذا لم تكن متأكداً من أي وضع يحتاجه تدفقك أو واجهت مشاكل أثناء الهجرة.