نظرة عامة على الوكيل
في إطار عمل CrewAI، الـAgent هو وحدة مستقلة يمكنها:
- أداء مهام محددة
- اتخاذ قرارات بناءً على دوره وهدفه
- استخدام الأدوات لتحقيق الأهداف
- التواصل والتعاون مع وكلاء آخرين
- الاحتفاظ بذاكرة التفاعلات
- تفويض المهام عند السماح بذلك
يتضمن CrewAI AMP منشئ وكلاء مرئي يبسّط إنشاء وتهيئة الوكلاء بدون كتابة كود. صمم وكلاءك بصريًا واختبرهم في الوقت الفعلي.
يُمكّن منشئ الوكلاء المرئي من:

- تهيئة وكلاء بديهية بواجهات نماذج
- اختبار والتحقق في الوقت الفعلي
- مكتبة قوالب مع أنواع وكلاء مهيأة مسبقًا
- تخصيص سهل لخصائص وسلوكيات الوكيل
خصائص الوكيل
إنشاء الوكلاء
هناك طريقتان شائعتان لإنشاء الوكلاء في CrewAI: باستخدام تهيئة JSONC (الموصى بها للـ crews الجديدة) أو تعريفهم مباشرة في الكود.تهيئة JSONC (موصى بها)
المشاريع الجديدة التي تُنشأ عبرcrewai create crew <name> تستخدم تهيئة JSON-first. يُعرّف كل Agent في agents/<agent_name>.jsonc، ويحدد crew.jsonc أي Agents تدخل في الـ crew.
agents/researcher.jsonc
{placeholder} داخل role أو goal أو backstory. ضع القيم الافتراضية في inputs داخل crew.jsonc؛ وسيطلب crewai run أي قيم ناقصة. يمكن وضع حقول السلوك مثل verbose و allow_delegation و max_iter و memory و cache و planning_config في المستوى الأعلى أو داخل settings.
يدعم JSONC التعليقات والفواصل النهائية. إذا وُجد
agents/<name>.jsonc و agents/<name>.json معًا، يستخدم CrewAI ملف JSONC.تهيئة YAML الكلاسيكية
المشاريع الكلاسيكية التي تُنشأ عبرcrewai create crew <name> --classic تستخدم config/agents.yaml وفئة @CrewBase في crew.py.
تظل تهيئة YAML مدعومة للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تفضل تعريف الوكلاء من خلال فئة @CrewBase.
بعد إنشاء مشروع كلاسيكي، انتقل إلى ملف src/<project_name>/config/agents.yaml وعدّل القالب ليتوافق مع متطلباتك.
ستُستبدل المتغيرات في ملفات YAML (مثل
{topic}) بقيم من مدخلاتك عند تشغيل الطاقم:Code
agents.yaml
CrewBase:
Code
يجب أن تتطابق الأسماء المستخدمة في ملفات YAML (
agents.yaml) مع أسماء
الطرق في كود Python.تعريف مباشر في الكود
يمكنك إنشاء الوكلاء مباشرة في الكود بإنشاء فئةAgent. إليك مثالًا شاملًا يوضح جميع المعاملات المتاحة:
Code
وكيل بحث أساسي
Code
وكيل تطوير الكود
Code
وكيل تحليل طويل المدى
Code
تفاصيل المعاملات
المعاملات الحرجة
roleوgoalوbackstoryمطلوبة وتشكّل سلوك الوكيلllmيحدد نموذج اللغة المستخدم (افتراضي: GPT-4 من OpenAI)
الذاكرة والسياق
memory: تفعيل للحفاظ على سجل المحادثةrespect_context_window: يمنع مشاكل حد الرموزknowledge_sources: إضافة قواعد معرفة خاصة بالمجال
التحكم في التنفيذ
max_iter: الحد الأقصى للمحاولات قبل تقديم أفضل إجابةmax_execution_time: المهلة بالثوانيmax_rpm: تحديد معدل استدعاءات APImax_retry_limit: إعادات المحاولة عند الخطأ
تنفيذ الكود
allow_code_execution(مهجور): كان يُمكّن تنفيذ الكود المدمج عبرCodeInterpreterTool.code_execution_mode(مهجور): كان يتحكم في وضع التنفيذ ("safe"لـ Docker،"unsafe"للتنفيذ المباشر).
الميزات المتقدمة
multimodal: تفعيل القدرات متعددة الوسائط لمعالجة النص والمحتوى المرئيreasoning: تمكين الوكيل من التأمل وإنشاء خطط قبل تنفيذ المهامinject_date: حقن التاريخ الحالي تلقائيًا في أمر الوكيل
القوالب
system_template: يحدد السلوك الأساسي للوكيلprompt_template: ينظم تنسيق الإدخالresponse_template: ينسّق استجابات الوكيل
عند استخدام القوالب المخصصة، تأكد من تعريف كل من
system_template و
prompt_template. response_template اختياري لكن يُوصى به
لتنسيق مخرجات متسق.أدوات الوكيل
يمكن تجهيز الوكلاء بأدوات متنوعة لتعزيز قدراتهم. يدعم CrewAI أدوات من: إليك كيفية إضافة أدوات لوكيل:Code
التفاعل المباشر مع الوكيل عبر kickoff()
يمكن استخدام الوكلاء مباشرة بدون المرور بمهمة أو سير عمل طاقم باستخدام طريقة kickoff(). يوفر هذا طريقة أبسط للتفاعل مع وكيل عندما لا تحتاج إلى إمكانيات تنسيق الطاقم الكاملة.
Code
ترقية الوكلاء من الإصدارات السابقة
أزال الإصدار 1.15.29CrewAgentExecutor وغيّر طريقة تعامل كل وكيل مع نتائج الأدوات الكبيرة والمحادثات الطويلة واستدعاءات الأدوات المتكررة. تنطبق هذه التغييرات على الوكلاء داخل crew وداخل Flow وعند استدعائهم عبر kickoff(). والاستثناء هو خطوات الخطة لدى الوكيل الذي يخطّط: فلا تُؤجَّل نتائج أدواتها، ولا تُلخَّص محادثتها، ويبدأ عدّ الاستدعاءات المتكررة من جديد في كل خطوة. إذا كنت تنتقل من 1.15.28 أو أقدم، فراجع كل تغيير أدناه.
إزالة CrewAgentExecutor
AgentExecutor هو منفّذ الوكلاء الوحيد. وهو الافتراضي منذ 1.14.5، لذا فإن الوكيل الذي لم يضبط executor_class قط كان يعمل عليه بالفعل.
- يفشل التحقق من
executor_class=CrewAgentExecutor، أو من السلسلة"CrewAgentExecutor"في ملف إعداد، بالرسالةCrewAgentExecutor has been removed. Use crewai.agents.agent_executor.AgentExecutor.احذف هذا الإعداد. - لم تعد مسارات الاستيراد هذه موجودة:
crewai.agents.crew_agent_executor، وcrewai.agents.CrewAgentExecutor، والوحدةcrewai.experimental.agent_executor، وcrewai.experimental.AgentExecutor، وcrewai.experimental.CrewAgentExecutorFlow. استورد المنفّذ منcrewai.agents:
Code
تأجيل نتائج الأدوات الكبيرة جدًا
عندما يعيد استدعاء أداة أصلي نتيجة أكبر من 25% من نافذة سياق النموذج، لم يعد الوكيل يتلقى النتيجة كاملة. بل يتلقى معاينة قصيرة ومرجعًا إلى ملف مؤقت، ويقرأ الباقي على أجزاء باستخدام الأداةRead a deferred tool result (يراها النموذج باسم read_a_deferred_tool_result)، والتي يضيفها CrewAI إلى الوكيل عند الحاجة.
- لا تُؤجَّل أبدًا استدعاءات الأدوات الفاشلة، ولا الأدوات التي تحمل
result_as_answer=True، ولا استدعاءات الأدوات النصية (ReAct). - يُحفظ الملف في مجلد خاص داخل مجلد الملفات المؤقتة للنظام. ولا يمكن قراءته إلا أثناء التشغيل الذي أنتجه، ويُحذف عند انتهاء تلك المهمة أو استدعاء
kickoff().
Code
تلخيص السياق قبل أن يتجاوز الحد
معrespect_context_window=True (الافتراضي)، أصبح الوكيل يقيس كل طلب قبل إرساله. وعندما يكون الطلب أكبر من نافذة سياق النموذج، يلخّص CrewAI المحادثة السابقة أولًا بدلًا من انتظار رفض المزوّد للطلب. وقد يفقد الملخص تفاصيل مثل الاقتباسات الحرفية.
اضبط respect_context_window=False لتعطيل التلخيص. عندها يوقف الطلب الطويل جدًا التشغيل بـ SystemExit("Context length exceeded and user opted not to summarize..."). وSystemExit ليس صنفًا فرعيًا من Exception، لذا لا تلتقطه الكتلة except Exception.
الاستدعاءات المتكررة للأدوات توقف المهمة
عندما يستدعي الوكيل الأداة نفسها بالوسائط نفسها ويحصل على النتيجة نفسها خمس مرات في تشغيل واحد، يوقف CrewAI المهمة بالخطأToolExecutionFailedError مع رسالة تفيد بأن الوكيل called '<tool>' with the same arguments 5 times and got the same result each time.
- يشمل العدّ المهمة كلها أو استدعاء
kickoff()كله، لا الاستدعاءات المتتالية فقط، ويشمل النتائج التي أجاب عنها التخزين المؤقت للأدوات. - يحدث الإيقاف أيًا كانت قيمة
tool_failure_policy، ولا يعيدmax_retry_limitالمحاولة. - حد الخمس مرات ثابت. لا يوجد إعداد لتغييره أو تعطيله.
كيف يُحدَّد حجم نافذة السياق
يُقاس كل من التأجيل والتلخيص مقابل نافذة السياق التي يستخدمها CrewAI للنموذج: 85% من النافذة المدرجة في كتالوج نماذج LiteLLM المضمّن في الحزمة. ويستخدم النموذج غير الموجود في الكتالوج قيمة افتراضية من المزوّد. وبالنسبة لنماذج OpenAI وAzure وBedrock والنماذج المتوافقة مع OpenAI (مثل OpenRouter) والنماذج الموجّهة عبر LiteLLM، تبلغ هذه القيمة 8,192 رمزًا، فيستخدم CrewAI القيمة 6,963 بعد تطبيق نسبة 85%، وتبدأ الميزتان أبكر بكثير مما تستدعيه النافذة الحقيقية للنموذج. ويستخدم الصنف الفرعي المخصص منBaseLLM الذي لا يعيد تعريف get_context_window_size() القيمة 4,096. لمعرفة الحجم الذي يستخدمه CrewAI، استدعِ get_context_window_size() على الـ LLM. يُنشأ الـ LLM كما يُنشأ عند التشغيل، لذا يجب ضبط مفتاح API الخاص بالمزوّد:
Code
اعتبارات مهمة وأفضل الممارسات
الأمان وتنفيذ الكود
تحسين الأداء
- استخدم
respect_context_window: trueلمنع مشاكل حد الرموز - عيّن
max_rpmمناسبًا لتجنب تحديد المعدل - فعّل
cache: trueلتحسين الأداء للمهام المتكررة - اضبط
max_iterوmax_retry_limitبناءً على تعقيد المهمة
إدارة الذاكرة والسياق
- استفد من
knowledge_sourcesللمعلومات الخاصة بالمجال - هيّئ
embedderعند استخدام نماذج تضمين مخصصة - استخدم القوالب المخصصة للتحكم الدقيق في سلوك الوكيل
التعاون بين الوكلاء
- فعّل
allow_delegation: trueعندما يحتاج الوكلاء للعمل معًا - استخدم
step_callbackلمراقبة وتسجيل تفاعلات الوكلاء - فكّر في استخدام نماذج LLM مختلفة لأغراض مختلفة
توافق النموذج
- عيّن
use_system_prompt: falseللنماذج القديمة التي لا تدعم رسائل النظام - تأكد من أن
llmالمختار يدعم الميزات التي تحتاجها
