الانتقال إلى المحتوى الرئيسي

نظرة عامة

المخرَج المحفوظ (artifact) هو ملف له اسم ينتجه Crew أو Agent أو Flow: تقرير HTML أو مستند markdown أو رسم بياني أو ملف PDF أو CSV. لكل مخرَج identifier. وعند الحفظ بنفس الـ identifier مرة أخرى في التشغيل نفسه تُنشأ نسخة جديدة (v1، v2، …). محليًا، تُكتب المخرجات على القرص. وعلى CrewAI AMP تظهر بجانب التشغيل، حيث يمكن للآخرين معاينتها وتنزيلها ومشاركتها. هذه الميزة اختيارية. يمكنك حفظ ناتج Task أو Agent، أو السماح للـ Agents بحفظ الملفات عبر أداة، أو الحفظ من كودك.

حفظ مخرَج Task أو Agent

اضبط artifact على الـ Task. عند انتهاء الـ Task يُحفظ ناتجها النهائي كمخرَج. لا يوجد استدعاء أداة ولا رموز إضافية، لذلك لا يمكن للنموذج أن ينسى الحفظ.
في Crew بصيغة JSON، أضفه إلى الـ Task في crew.jsonc:

دع CrewAI يختار الاسم

مرّر artifact=True لتتجاوز التفاصيل. يملؤها CrewAI كما يلي:
  • يأتي identifier وtitle من اسم الـ Task (أو وصفها). داخل Flow يأتيان من اسم دالة الـ Flow. وفي غير ذلك يأتيان من role الـ Agent.
  • يأتي kind من الناتج: html إذا بدأ بـ <!doctype html أو <html، وsvg إذا بدأ بـ <svg، وjson إذا كان كائن JSON أو قائمة، وmarkdown لأي شيء آخر.
يبقى الاسم نفسه عند تشغيل الـ Task نفسها أو دالة الـ Flow نفسها مرة أخرى، لذلك تنشئ إعادة التشغيل النسخة التالية وليس مخرَجًا جديدًا.

Agent منفرد

يقبل Agent.kickoff الوسيط artifact نفسه، على شكل Artifact أو True:
ويقبله أيضًا kickoff_async وakickoff.

الـ Flows التصريحية

في تعريف Flow، اضبط artifact تحت with في خطوة call: agent:
يسمّي artifact: true المخرَج باسم الدالة، وهنا يكون write-report. استخدم كائنًا مثل {identifier: weekly-report, title: Weekly report, kind: html} لتحدد التفاصيل بنفسك. لتعطي الـ Agent مخرَجًا حفظه التشغيل سابقًا، أدرجه تحت input_files. كل عنصر هو مرجع يُحمَّل عند تشغيل الخطوة:
بدون version تُستخدم أحدث نسخة. إذا لم يكن المخرَج موجودًا تفشل الخطوة قبل تشغيل الـ Agent. تتطلب ملفات الإدخال crewai[file-processing].

حفظ ملف يكتبه الـ Agent

لرسم بياني أو ملف PDF أو أي ملف آخر تكتبه أدوات الـ Agent على القرص، اضبط file_path على مكان الملف. يحفظ CrewAI ذلك الملف بدلًا من الناتج النصي. تتطلب الأنواع image وpdf وfile وجود file_path.
  • أخبر الـ Agent أين يكتب الملف، مثلًا في وصف الـ Task.
  • في الـ Task تُملأ {placeholders} في file_path من مدخلات الـ kickoff، كما في output_file. وفي تعريف Flow استخدم تعبيرات ${...} مثل output/${state.quarter}.png.
  • يجب أن يكون الملف داخل مجلد العمل. تُرفض المسارات خارجه، لذلك احفظ الرسوم البيانية وملفات PDF في مجلد المشروع.

استخدام المخرَج المحفوظ

النسخة المحفوظة موجودة في artifact على الناتج، لذلك يمكن لدالة callback أو خطوة لاحقة في الـ Flow أو كودك أن يرسل الرابط:
في تعريف Flow، اقرأه باستخدام ${outputs.write_report.artifact.url}.

السماح للـ Agents بحفظ المخرجات

اضبط artifacts=True على الـ Crew لمنح كل Agent أداة save_artifact، أو على Agent واحد لمنحه الأداة وحده.
تأخذ الأداة identifier وtitle وkind، ومعها إما content (نص) أو file_path (ملف أنشأه الـ Agent، مثل صورة PNG لرسم بياني). وتُرجع JSON:
يمكن لـ Task لاحقة استخدام الـ url، مثلًا لنشره في Slack أو إرفاقه برسالة بريد إلكتروني.

الحفظ من الكود

استدعِ save_artifact من أي كود Python، مثل خطوة في Flow. لا حاجة إلى Agent.
مرّر content (من نوع str أو bytes) أو file_path، وليس الاثنين معًا. تُرجع الدالة SavedArtifact يحتوي على id وidentifier وtitle وkind وversion وcontent_type وsize وurl وshare_url.

قراءة مخرَج محفوظ

استدعِ load_artifact لقراءة مخرَج حفظه التشغيل. تُرجع الدالة بايتات أحدث نسخة، أو النسخة التي تطلبها:
يهم هذا أكثر ما يهم في Flow يتوقف لانتظار ملاحظات بشرية. قد يُستأنف الـ Flow لاحقًا على جهاز آخر، حيث لم تعد الملفات المكتوبة قبل التوقف موجودة، لكن مخرجاته تبقى محفوظة. يقرأ التشغيل المستأنف التقرير مرة أخرى، ويراجعه، ثم يحفظ النسخة التالية.
  • تقرأ load_artifact من التشغيل الحالي، وهو نفس التشغيل الذي يكمله الـ Flow المستأنف.
  • إذا لم يطابق أي مخرَج أو نسخة، تُطلق ArtifactNotFoundError.

المعرّفات والنسخ

  • يجب أن يطابق identifier النمط [a-z0-9][a-z0-9_.-]{0,63}، مثل q3-report.
  • ينتمي المخرَج إلى تشغيل واحد. الـ Crews داخل Flow تشترك في تشغيل الـ Flow، لذلك تُجمع كل مخرجاتها معًا.
  • الحفظ بنفس الـ identifier مرة أخرى في التشغيل ينشئ النسخة التالية. وهذا يناسب الـ Flows التي يشارك فيها إنسان وتعيد إنشاء التقرير بعد الملاحظات.

الأنواع

مكان تخزين المخرجات

محليًا، تُحفظ المخرجات في:
يكون url عنوانًا من نوع file:// ويكون share_url فارغًا. على CrewAI AMP، تسجّل المنصة الـ store الخاص بها عند بدء التشغيل، فيرفع الكود نفسه المخرجات إلى التشغيل. لا يتغير شيء في الـ Crew.

حالات الفشل

فشل حفظ المخرَج لا يُفشل التشغيل أبدًا:
  • تُرجع أداة save_artifact نص الخطأ إلى الـ Agent.
  • تسجّل Task(artifact=...) وkickoff(artifact=...) تحذيرًا، ويكتمل التشغيل رغم ذلك. ويشمل هذا file_path غير موجود.
  • استدعاء save_artifact من كودك يرفع الخطأ، لتقرر أنت ما تفعله.

الأحداث

كل عملية حفظ تُطلق ArtifactCreatedEvent على event bus، ويحتوي على id وidentifier وversion وtitle وkind وcontent_type وsize وurl.
راجع مستمعو الأحداث.

مخازن مخصصة

لإرسال المخرجات إلى مكان آخر، أنشئ صنفًا فرعيًا من ArtifactStore وسجّله قبل الـ kickoff:
إذا كان الـ store يعيد محاولة الرفع، فأرسل نفس artifact_id في كل مرة حتى يتمكن الطرف المستقبِل من تجاهل النسخ المكررة. الدالة load اختيارية: بدونها تُطلق load_artifact الخطأ NotImplementedError.