From 3d95afca4195cc538d24a2f1a07043d9142d93a7 Mon Sep 17 00:00:00 2001 From: Tiago Freire Date: Tue, 12 May 2026 14:10:32 -0300 Subject: [PATCH] =?UTF-8?q?Docs:=20`inputs.id`=20=E2=86=92=20`restoreFromS?= =?UTF-8?q?tateId`=20migration=20guide=20(#5779)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Add a new docs page at `docs/en/guides/flows/inputs-id-deprecation.mdx` that explains the deprecation of `inputs.id` as a `@persist` hydration mechanism and walks users through migrating to `restoreFromStateId` (available in CrewAI **v1.14.5 and later**). - Wire the page into `docs.json` next to `mastering-flow-state` in all 13 version blocks across all 4 languages (52 nav inserts). - Add translations for `ar`, `ko`, `pt-BR` --- .../ar/guides/flows/inputs-id-deprecation.mdx | 102 ++++++++++++ docs/docs.json | 156 ++++++++++++------ .../en/guides/flows/inputs-id-deprecation.mdx | 143 ++++++++++++++++ .../ko/guides/flows/inputs-id-deprecation.mdx | 125 ++++++++++++++ .../guides/flows/inputs-id-deprecation.mdx | 142 ++++++++++++++++ 5 files changed, 616 insertions(+), 52 deletions(-) create mode 100644 docs/ar/guides/flows/inputs-id-deprecation.mdx create mode 100644 docs/en/guides/flows/inputs-id-deprecation.mdx create mode 100644 docs/ko/guides/flows/inputs-id-deprecation.mdx create mode 100644 docs/pt-BR/guides/flows/inputs-id-deprecation.mdx diff --git a/docs/ar/guides/flows/inputs-id-deprecation.mdx b/docs/ar/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..3e29b2baf --- /dev/null +++ b/docs/ar/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,102 @@ +--- +title: "الانتقال من inputs.id إلى restore_from_state_id" +description: "نقل تدفقات @persist من ترطيب inputs.id المهجور إلى حقل restore_from_state_id المدعوم" +icon: "arrow-right-arrow-left" +--- + + + تمرير `id` داخل `inputs` لترطيب تدفق `@persist` هو **مهجور** ومقرر إزالته في إصدار مستقبلي. البديل، `restore_from_state_id`، متاح في CrewAI **v1.14.5 وما بعده** — الخطوات أدناه تنطبق بمجرد أن تقوم بالتحديث. + + +## نظرة عامة + +الطريقة الموثقة لترطيب تدفق `@persist` من تنفيذ سابق هي تمرير UUID لذلك التنفيذ كـ `inputs.id`. الآن، تكشف CrewAI عن حقل مخصص، `restore_from_state_id`، الذي يقوم بنفس الترطيب دون تحميل حمولة `inputs` — ودون ربط مفتاح الترطيب بهوية التنفيذ الجديد. + +## الانتقال + +إذا كنت حالياً تبدأ تدفق `@persist` باستخدام `inputs={"id": ...}`: + +```python +# مهجور +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +انتقل إلى `restore_from_state_id`: + +```python +# مدعوم +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +تتمتع الوضعيتان بمعاني سلالة مختلفة: + +- `inputs={"id": }` (مهجور) — **استئناف**: تكتب الكتابات تحت المعرف المقدم، مما يمدد نفس تاريخ `flow_uuid`. +- `restore_from_state_id=` — **تفرع**: يترطب الحالة من اللقطة، ثم يكتب تحت `state.id` جديدة. يتم الحفاظ على تاريخ التدفق المصدر. + +لأغلب سيناريوهات الإنتاج — إعادة تشغيل تدفق تم تهيئته من حالة سابقة — فإن التفرع هو ما تريده. راجع [إتقان حالة التدفق](/ar/guides/flows/mastering-flow-state) للحصول على النموذج الذهني الكامل. + +إذا كنت تبدأ تدفقك عبر واجهة برمجة تطبيقات CrewAI AMP REST، راجع [AMP](#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`: + +```bash +# مهجور +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` في المستوى الأعلى: + +```bash +# مدعوم +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` في الحفاظ على كل بداية كتنفيذ خاص بها — مع حالتها الخاصة، وتتبعها، وصفها في القائمة — بينما لا تزال ترطب الحالة من تشغيل سابق. + + + اتصل بفريق الدعم لدينا إذا لم تكن متأكداً من أي وضع يحتاجه تدفقك أو واجهت مشاكل أثناء الهجرة. + \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index edd9a19ba..e3c129d25 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -114,7 +114,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -597,7 +598,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -1079,7 +1081,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -1558,7 +1561,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -2040,7 +2044,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -2522,7 +2527,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -3004,7 +3010,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -3486,7 +3493,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -3966,7 +3974,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -4446,7 +4455,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -4927,7 +4937,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -5409,7 +5420,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -5889,7 +5901,8 @@ "icon": "code-branch", "pages": [ "en/guides/flows/first-flow", - "en/guides/flows/mastering-flow-state" + "en/guides/flows/mastering-flow-state", + "en/guides/flows/inputs-id-deprecation" ] }, { @@ -6402,7 +6415,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -6862,7 +6876,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -7322,7 +7337,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -7781,7 +7797,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -8241,7 +8258,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -8701,7 +8719,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -9161,7 +9180,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -9621,7 +9641,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -10080,7 +10101,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -10539,7 +10561,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -10998,7 +11021,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -11456,7 +11480,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -11914,7 +11939,8 @@ "icon": "code-branch", "pages": [ "pt-BR/guides/flows/first-flow", - "pt-BR/guides/flows/mastering-flow-state" + "pt-BR/guides/flows/mastering-flow-state", + "pt-BR/guides/flows/inputs-id-deprecation" ] }, { @@ -12403,7 +12429,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -12875,7 +12902,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -13347,7 +13375,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -13819,7 +13848,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -14292,7 +14322,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -14765,7 +14796,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -15238,7 +15270,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -15711,7 +15744,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -16183,7 +16217,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -16655,7 +16690,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -17127,7 +17163,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -17598,7 +17635,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -18069,7 +18107,8 @@ "icon": "code-branch", "pages": [ "ko/guides/flows/first-flow", - "ko/guides/flows/mastering-flow-state" + "ko/guides/flows/mastering-flow-state", + "ko/guides/flows/inputs-id-deprecation" ] }, { @@ -18571,7 +18610,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -19043,7 +19083,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -19515,7 +19556,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -19987,7 +20029,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -20460,7 +20503,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -20933,7 +20977,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -21406,7 +21451,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -21879,7 +21925,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -22351,7 +22398,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -22823,7 +22871,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -23295,7 +23344,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -23766,7 +23816,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { @@ -24237,7 +24288,8 @@ "icon": "code-branch", "pages": [ "ar/guides/flows/first-flow", - "ar/guides/flows/mastering-flow-state" + "ar/guides/flows/mastering-flow-state", + "ar/guides/flows/inputs-id-deprecation" ] }, { diff --git a/docs/en/guides/flows/inputs-id-deprecation.mdx b/docs/en/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..2798c21a5 --- /dev/null +++ b/docs/en/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,143 @@ +--- +title: "Migrating from inputs.id to restore_from_state_id" +description: "Move @persist flows off the deprecated inputs.id hydration onto the supported restore_from_state_id field" +icon: "arrow-right-arrow-left" +--- + + + Passing `id` inside `inputs` to hydrate a `@persist` flow is **deprecated** and + scheduled for removal in a future release. The replacement, `restore_from_state_id`, + is available in CrewAI **v1.14.5 and later** — the steps below apply once you + upgrade. + + +## Overview + +The documented way to hydrate a `@persist` flow from a previous execution is to pass +that execution's UUID as `inputs.id`. CrewAI now exposes a dedicated field, +`restore_from_state_id`, that performs the same hydration without overloading the +`inputs` payload — and without coupling the hydration key to the new execution's +identity. + +## Migration + +If you currently kickoff a `@persist` flow with `inputs={"id": ...}`: + +```python +# Deprecated +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +Switch to `restore_from_state_id`: + +```python +# Supported +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +The two modes have different lineage semantics: + +- `inputs={"id": }` (deprecated) — **resume**: writes land under the supplied + id, extending the same `flow_uuid` history. +- `restore_from_state_id=` — **fork**: hydrates state from the snapshot, then + writes under a fresh `state.id`. The source flow's history is preserved. + +For most production scenarios — re-running a flow seeded from a previous state — fork +is what you want. See [Mastering Flow State](/en/guides/flows/mastering-flow-state) +for the full mental model. + +If you kickoff your flow over the CrewAI AMP REST API, see [AMP](#amp) below for the +equivalent payload migration. + +## Why we are deprecating `inputs.id` for `@persist` + +`inputs.id` is currently the documented way to resume a `@persist` flow from a +previous execution. The problem is that the same UUID does two jobs at once: + +1. **It selects which snapshot `@persist` hydrates from** — load the state saved + under that UUID. +2. **It becomes the new execution's Flow Execution ID** (`state.id` in the SDK; + surfaced as `flow_id` in some contexts) — every `@persist` write from this + kickoff also lands under that same UUID. + +This dual role is the root cause of the issues this guide describes. Because the +supplied UUID is also the new execution's id, two kickoffs that pass the same +`inputs.id` are not two distinct executions — they share an id, share a persistence +record, and (on AMP) share a row in the executions list. There is no way to say +"hydrate from this snapshot, but record this run separately" without splitting the +two responsibilities. + +`restore_from_state_id` is that split. It tells `@persist` which snapshot to hydrate +from, while leaving the new execution free to receive a fresh `state.id`. The +hydration source and the recorded run are no longer the same UUID — which is what +most production scenarios actually want. + +## Removal timeline + +`inputs.id` for `@persist` hydration is scheduled for removal in a future release of +CrewAI. There is no immediate hard cut-off — existing flows continue to work — but +once you upgrade to v1.14.5 or later, new code should use `restore_from_state_id`, and +existing flows should migrate at the next convenient opportunity. + +## AMP + +If you deploy your flow to CrewAI AMP, the migration extends to the kickoff payload +sent to your deployed crew, and the visible symptoms of reusing `inputs.id` show up +on the deployment dashboard. The two subsections below cover both. + +### Migrating the kickoff payload + +If you currently kickoff a deployed flow by embedding `id` in `inputs`: + +```bash +# Deprecated +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 +``` + +Move the UUID to the top-level `restoreFromStateId` field: + +```bash +# Supported +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` sits next to `inputs` in the kickoff payload, not inside it. The +`inputs` object now only carries values your flow actually consumes. + +### What happens when `inputs.id` is reused + +When AMP receives a kickoff for a flow whose `inputs.id` matches an existing +execution, it resolves to the existing record rather than creating a new one. From +the deployment dashboard you'll see: + +- **Execution status** — the new run's status overwrites the previous run's. A + finished execution can flip back to `running`, or a `completed` run can flip to + `error` if the new kickoff fails — either way the dashboard no longer reflects + the original run. +- **Traces** — OTel traces stack across kickoffs because they share the same + execution id; the previous run's traces are either replaced by, or mixed with, + the new run's. A step-by-step replay no longer corresponds to a single execution. +- **Executions list** — kickoffs that should appear as separate rows collapse into + a single entry, hiding history. + +Migrating to `restoreFromStateId` keeps every kickoff as its own execution — with +its own status, traces, and row in the list — while still hydrating state from a +previous run. + + + Contact our support team if you're unsure which mode your flow needs or hit issues + during the migration. + diff --git a/docs/ko/guides/flows/inputs-id-deprecation.mdx b/docs/ko/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..226db332f --- /dev/null +++ b/docs/ko/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,125 @@ +--- +title: "inputs.id에서 restore_from_state_id로 마이그레이션" +description: "더 이상 지원되지 않는 inputs.id 하이드레이션에서 지원되는 restore_from_state_id 필드로 @persist 흐름을 이동" +icon: "arrow-right-arrow-left" +--- + + + `inputs` 내에서 `id`를 전달하여 `@persist` 흐름을 하이드레이트하는 것은 **더 이상 지원되지 않으며** + 향후 릴리스에서 제거될 예정입니다. 대체품인 `restore_from_state_id`는 CrewAI **v1.14.5 이상**에서 사용할 수 있으며, + 아래 단계는 업그레이드 후 적용됩니다. + + +## 개요 + +이전 실행에서 `@persist` 흐름을 하이드레이트하는 문서화된 방법은 +해당 실행의 UUID를 `inputs.id`로 전달하는 것입니다. CrewAI는 이제 +`inputs` 페이로드를 과부하하지 않고 동일한 하이드레이션을 수행하는 전용 필드인 +`restore_from_state_id`를 제공합니다 — 그리고 하이드레이션 키를 새로운 실행의 +정체성과 결합하지 않습니다. + +## 마이그레이션 + +현재 `inputs={"id": ...}`로 `@persist` 흐름을 시작하는 경우: + +```python +# 더 이상 지원되지 않음 +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +`restore_from_state_id`로 전환하십시오: + +```python +# 지원됨 +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +두 모드는 서로 다른 계보 의미론을 가지고 있습니다: + +- `inputs={"id": }` (더 이상 지원되지 않음) — **재개**: 제공된 + id 아래에 기록이 작성되어 동일한 `flow_uuid` 이력이 확장됩니다. +- `restore_from_state_id=` — **분기**: 스냅샷에서 상태를 하이드레이트한 후 + 새로운 `state.id` 아래에 기록합니다. 원본 흐름의 이력은 보존됩니다. + +대부분의 프로덕션 시나리오에서는 — 이전 상태에서 시드된 흐름을 다시 실행하는 경우 — 분기가 +필요합니다. 전체 정신 모델은 [Flow State 마스터링](/ko/guides/flows/mastering-flow-state)을 참조하십시오. + +CrewAI AMP REST API를 통해 흐름을 시작하는 경우, 아래 [AMP](#amp)에서 +동일한 페이로드 마이그레이션을 참조하십시오. + +## 왜 `@persist`에 대해 `inputs.id`를 더 이상 지원하지 않습니까? + +`inputs.id`는 현재 이전 실행에서 `@persist` 흐름을 재개하는 문서화된 방법입니다. 문제는 +동일한 UUID가 두 가지 작업을 동시에 수행한다는 것입니다: + +1. **어떤 스냅샷에서 `@persist`가 하이드레이트되는지를 선택합니다** — 해당 UUID 아래에 저장된 상태를 로드합니다. +2. **새 실행의 흐름 실행 ID가 됩니다** (`state.id`는 SDK에서; 일부 컨텍스트에서는 `flow_id`로 표시됨) — 이 + 시작에서의 모든 `@persist` 기록도 동일한 UUID 아래에 작성됩니다. + +이 이중 역할이 이 가이드에서 설명하는 문제의 근본 원인입니다. 제공된 UUID가 새 실행의 id이기도 하므로, +동일한 `inputs.id`를 전달하는 두 번의 시작은 두 개의 별도 실행이 아닙니다 — 그들은 id를 공유하고, +지속성 기록을 공유하며, (AMP에서) 실행 목록에서 행을 공유합니다. "이 스냅샷에서 하이드레이트하지만, +이 실행을 별도로 기록하십시오"라고 말할 방법이 없습니다. + +`restore_from_state_id`가 그 분리입니다. 이는 `@persist`에 어떤 스냅샷에서 하이드레이트할지를 알려주며, +새 실행이 새로운 `state.id`를 받을 수 있도록 합니다. 하이드레이션 소스와 기록된 실행은 더 이상 동일한 UUID가 아닙니다 — 이는 대부분의 프로덕션 시나리오에서 실제로 원하는 것입니다. + +## 제거 일정 + +`@persist` 하이드레이션을 위한 `inputs.id`는 CrewAI의 향후 릴리스에서 제거될 예정입니다. 즉각적인 강제 종료는 없으며 — 기존 흐름은 계속 작동합니다 — 하지만 v1.14.5 이상으로 업그레이드하면, +새 코드에서는 `restore_from_state_id`를 사용해야 하며, 기존 흐름은 다음 편리한 기회에 마이그레이션해야 합니다. + +## AMP + +흐름을 CrewAI AMP에 배포하는 경우, 마이그레이션은 배포된 팀에 전송되는 시작 페이로드로 확장되며, +`inputs.id`를 재사용하는 가시적인 증상은 배포 대시보드에 나타납니다. 아래 두 개의 하위 섹션이 이를 다룹니다. + +### 시작 페이로드 마이그레이션 + +현재 `inputs`에 `id`를 포함하여 배포된 흐름을 시작하는 경우: + +```bash +# 더 이상 지원되지 않음 +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` 필드로 이동하십시오: + +```bash +# 지원됨 +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 추적이 시작 간에 쌓이기 때문에 동일한 실행 id를 공유합니다; 이전 실행의 추적은 + 새로운 실행의 추적과 교체되거나 혼합됩니다. 단계별 재생은 더 이상 단일 실행에 해당하지 않습니다. +- **실행 목록** — 별도의 행으로 나타나야 할 시작이 단일 항목으로 축소되어 이력을 숨깁니다. + +`restoreFromStateId`로 마이그레이션하면 모든 시작이 자체 실행으로 유지됩니다 — 각자의 상태, 추적 및 목록의 행을 가지며 — 여전히 이전 실행에서 상태를 하이드레이트합니다. + + + 흐름이 어떤 모드가 필요한지 확실하지 않거나 마이그레이션 중 문제가 발생하면 지원 팀에 문의하십시오. + \ No newline at end of file diff --git a/docs/pt-BR/guides/flows/inputs-id-deprecation.mdx b/docs/pt-BR/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..3e17d5640 --- /dev/null +++ b/docs/pt-BR/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,142 @@ +--- +title: "Migrando de inputs.id para restore_from_state_id" +description: "Mover fluxos @persist da hidratação obsoleta inputs.id para o campo suportado restore_from_state_id" +icon: "arrow-right-arrow-left" +--- + + + Passar `id` dentro de `inputs` para hidratar um fluxo `@persist` é **obsoleto** e + programado para remoção em uma versão futura. A substituição, `restore_from_state_id`, + está disponível no CrewAI **v1.14.5 e posterior** — os passos abaixo se aplicam uma vez que você + faça a atualização. + + +## Visão Geral + +A maneira documentada de hidratar um fluxo `@persist` de uma execução anterior é passar +o UUID dessa execução como `inputs.id`. O CrewAI agora expõe um campo dedicado, +`restore_from_state_id`, que realiza a mesma hidratação sem sobrecarregar a +carga útil de `inputs` — e sem acoplar a chave de hidratação à identidade da nova execução. + +## Migração + +Se você atualmente inicia um fluxo `@persist` com `inputs={"id": ...}`: + +```python +# Obsoleto +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +Mude para `restore_from_state_id`: + +```python +# Suportado +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +Os dois modos têm semânticas de linhagem diferentes: + +- `inputs={"id": }` (obsoleto) — **retomar**: as gravações são feitas sob o id fornecido, + estendendo a mesma história de `flow_uuid`. +- `restore_from_state_id=` — **dividir**: hidrata o estado a partir de um snapshot, então + grava sob um novo `state.id`. A história do fluxo de origem é preservada. + +Para a maioria dos cenários de produção — reexecutar um fluxo hidratado de um estado anterior — criar um fork +é o que você deseja. Veja [Dominando o Estado do Fluxo](/pt-BR/guides/flows/mastering-flow-state) +para o modelo mental completo. + +Se você iniciar seu fluxo pela API REST do CrewAI AMP, veja [AMP](#amp) abaixo para a +migração equivalente da carga útil. + +## Por que estamos descontinuando `inputs.id` para `@persist`? + +`inputs.id` é atualmente a maneira documentada de retomar um fluxo `@persist` de uma +execução anterior. O problema é que o mesmo UUID faz duas funções ao mesmo tempo: + +1. **Seleciona qual snapshot o `@persist` usa para hidratar** — carrega o estado salvo + sob aquele UUID. +2. **Torna-se o ID de Execução do Fluxo da nova execução** (`state.id` no SDK; + apresentado como `flow_id` em alguns contextos) — cada gravação `@persist` a partir desta + inicialização também cai sob aquele mesmo UUID. + +Esse papel duplo é a causa raiz dos problemas que este guia descreve. Como o +UUID fornecido também é o id da nova execução, duas inicializações que passam o mesmo +`inputs.id` não são duas execuções distintas — elas compartilham um id, compartilham um registro +de persistência e (no AMP) compartilham uma linha na lista de execuções. Não há como dizer +"hidratar a partir deste snapshot, mas registrar esta execução separadamente" sem dividir as +duas responsabilidades. + +`restore_from_state_id` é essa divisão. Ele informa ao `@persist` de qual snapshot hidratar, +enquanto deixa a nova execução livre para receber um novo `state.id`. A +fonte de hidratação e a execução registrada não são mais o mesmo UUID — que é o que +a maioria dos cenários de produção realmente deseja. + +## Cronograma de remoção + +`inputs.id` para hidratação `@persist` está programado para remoção em uma versão futura do +CrewAI. Não há um corte imediato — fluxos existentes continuam a funcionar — mas +uma vez que você atualize para v1.14.5 ou posterior, novo código deve usar `restore_from_state_id`, e +fluxos existentes devem migrar na próxima oportunidade conveniente. + +## AMP + +Se você implantar seu fluxo no CrewAI AMP, a migração se estende à carga útil de inicialização +enviada para sua Crew implantada, e os sintomas visíveis de reutilização de `inputs.id` aparecem +no painel de controle de implantação. As duas subseções abaixo cobrem ambos. + +### Migrando a carga útil de inicialização + +Se você atualmente inicia um fluxo implantado incorporando `id` em `inputs`: + +```bash +# Obsoleto +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 +``` + +Mova o UUID para o campo `restoreFromStateId` de nível superior: + +```bash +# Suportado +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` fica ao lado de `inputs` na carga útil de inicialização, não dentro dela. O +objeto `inputs` agora carrega apenas valores que seu fluxo realmente consome. + +### O que acontece quando `inputs.id` é reutilizado + +Quando o AMP recebe um kickoff para um fluxo cujo `inputs.id` corresponde a uma execução +existente, ele resolve para o registro existente em vez de criar um novo. A partir +do painel de controle de implantação, você verá: + +- **Status da execução** — o status da nova execução sobrescreve o status da execução anterior. Uma + execução finalizada pode voltar para `running`, ou uma execução `completed` pode mudar para + `error` se a nova inicialização falhar — de qualquer forma, o painel não reflete mais + a execução original. +- **Rastros** — Os OTel traces se acumulam entre as inicializações porque compartilham o mesmo + id de execução; os traces da execução anterior são substituídos ou misturados + com os da nova execução. Uma reprodução passo a passo não corresponde mais a uma única execução. +- **Lista de execuções** — kickoffs que deveriam aparecer como linhas separadas colapsam em + uma única entrada, ocultando o histórico. + +Migrar para `restoreFromStateId` mantém cada kickoff como sua própria execução — com +seu próprio status, traces e entrada na lista — enquanto ainda hidrata o estado de uma +execução anterior. + + + Entre em contato com nossa equipe de suporte se você não tiver certeza de qual modo seu fluxo precisa ou se encontrar problemas + durante a migração. +