نظرة عامة
المخرَج المحفوظ (artifact) هو ملف له اسم ينتجه Crew أو Agent أو Flow: تقرير HTML أو مستند markdown أو رسم بياني أو ملف PDF أو CSV. لكل مخرَجidentifier. وعند الحفظ بنفس الـ identifier مرة أخرى في التشغيل نفسه تُنشأ نسخة جديدة (v1، v2، …).
محليًا، تُكتب المخرجات على القرص. وعلى CrewAI AMP تظهر بجانب التشغيل، حيث يمكن للآخرين معاينتها وتنزيلها ومشاركتها.
هذه الميزة اختيارية. يمكنك حفظ ناتج Task أو Agent، أو السماح للـ Agents بحفظ الملفات عبر أداة، أو الحفظ من كودك.
حفظ مخرَج Task أو Agent
اضبطartifact على الـ Task. عند انتهاء الـ Task يُحفظ ناتجها النهائي كمخرَج. لا يوجد استدعاء أداة ولا رموز إضافية، لذلك لا يمكن للنموذج أن ينسى الحفظ.
crew.jsonc:
دع CrewAI يختار الاسم
مرّرartifact=True لتتجاوز التفاصيل. يملؤها CrewAI كما يلي:
- يأتي
identifierوtitleمن اسم الـ Task (أو وصفها). داخل Flow يأتيان من اسم دالة الـ Flow. وفي غير ذلك يأتيان من role الـ Agent. - يأتي
kindمن الناتج:htmlإذا بدأ بـ<!doctype htmlأو<html، وsvgإذا بدأ بـ<svg، وjsonإذا كان كائن JSON أو قائمة، وmarkdownلأي شيء آخر.
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 أو كودك أن يرسل الرابط:
${outputs.write_report.artifact.url}.
السماح للـ Agents بحفظ المخرجات
اضبطartifacts=True على الـ Crew لمنح كل Agent أداة save_artifact، أو على Agent واحد لمنحه الأداة وحده.
identifier وtitle وkind، ومعها إما content (نص) أو file_path (ملف أنشأه الـ Agent، مثل صورة PNG لرسم بياني). وتُرجع JSON:
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 لقراءة مخرَج حفظه التشغيل. تُرجع الدالة بايتات أحدث نسخة، أو النسخة التي تطلبها:
- تقرأ
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:
artifact_id في كل مرة حتى يتمكن الطرف المستقبِل من تجاهل النسخ المكررة. الدالة load اختيارية: بدونها تُطلق load_artifact الخطأ NotImplementedError.