الانتقال إلى المحتوى الرئيسي
يشرح هذا الدليل كيفية استخدام التعليقات التوضيحية للإشارة بشكل صحيح إلى الوكلاء والمهام والمكونات الأخرى في ملف crew.py كلاسيكي.
المشاريع الجديدة التي تُنشأ عبر crewai create crew <name> هي JSON-first وتستخدم crew.jsonc مع agents/*.jsonc. استخدم هذا الدليل عند العمل في مشروع كلاسيكي أُنشئ عبر crewai create crew <name> --classic، أو عند ترحيل مشروع Python/YAML موجود، أو عندما تحتاج تحكمًا عبر decorators في Python.

مقدمة

تُستخدم التعليقات التوضيحية في إطار عمل CrewAI لتزيين الفئات والطرق، مما يوفر بيانات وصفية ووظائف للمكونات المختلفة في طاقمك. في مشاريع Python/YAML الكلاسيكية، تنظم الكود الذي يحمّل config/agents.yaml و config/tasks.yaml ويعيد كائن Crew.

التعليقات التوضيحية المتاحة

يوفر إطار عمل CrewAI التعليقات التوضيحية التالية:
  • @CrewBase: تُستخدم لتزيين فئة الطاقم الرئيسية.
  • @agent: تزين الطرق التي تعرّف وتُرجع كائنات Agent.
  • @task: تزين الطرق التي تعرّف وتُرجع كائنات Task.
  • @crew: تزين الطريقة التي تنشئ وتُرجع كائن Crew.
  • @llm: تزين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة.
  • @tool: تزين الطرق التي تهيئ وتُرجع كائنات الأدوات.
  • @callback: تُستخدم لتعريف طرق الاستدعاء الراجع.
  • @output_json: تُستخدم للطرق التي تُخرج بيانات JSON.
  • @output_pydantic: تُستخدم للطرق التي تُخرج نماذج Pydantic.
  • @cache_handler: تُستخدم لتعريف طرق معالجة التخزين المؤقت.

أمثلة الاستخدام

لنمر عبر أمثلة لكيفية استخدام هذه التعليقات التوضيحية:

1. فئة الطاقم الأساسية

@CrewBase
class LinkedinProfileCrew():
    """LinkedinProfile crew"""
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'
تُستخدم التعليقة التوضيحية @CrewBase لتزيين فئة الطاقم الرئيسية. تحتوي هذه الفئة عادةً على الإعدادات والطرق لإنشاء الوكلاء والمهام والطاقم نفسه.
@CrewBase تفعل أكثر من مجرد تسجيل الفئة:
  • تمهيد الإعدادات: تبحث عن agents_config و tasks_config (القيمة الافتراضية config/agents.yaml و config/tasks.yaml) بجانب ملف الفئة، وتحملها عند الإنشاء، وتتراجع بأمان إلى قواميس فارغة إذا كانت الملفات مفقودة.
  • تنسيق المزخرفات: تحتفظ بمراجع محفوظة لكل طريقة مُعلّمة بـ @agent أو @task أو @before_kickoff أو @after_kickoff بحيث يتم إنشاؤها مرة واحدة لكل طاقم وتُنفذ بترتيب الإعلان.
  • ربط الخطافات: تربط تلقائياً خطافات التشغيل المحفوظة بكائن Crew المُرجع من طريقة @crew، مما يجعلها تعمل قبل وبعد .kickoff().
  • تكامل MCP: عندما تعرّف الفئة mcp_server_params، ينشئ get_mcp_tools() بكسل محول MCP server، ويملأ الأدوات المُعلنة، ويوقف خطاف ما بعد التشغيل الداخلي المحول. راجع نظرة عامة على MCP لتفاصيل إعداد المحول.

2. تعريف الأداة

@tool
def myLinkedInProfileTool(self):
    return LinkedInProfileTool()
تُستخدم التعليقة التوضيحية @tool لتزيين الطرق التي تُرجع كائنات أدوات. يمكن للوكلاء استخدام هذه الأدوات لأداء مهام محددة.

3. تعريف LLM

@llm
def groq_llm(self):
    api_key = os.getenv('api_key')
    return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768")
تُستخدم التعليقة التوضيحية @llm لتزيين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة. تستخدم هذه النماذج من قبل الوكلاء لمهام معالجة اللغة الطبيعية.

4. تعريف الوكيل

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config['researcher']
    )
تُستخدم التعليقة التوضيحية @agent لتزيين الطرق التي تعرّف وتُرجع كائنات Agent.

5. تعريف المهمة

@task
def research_task(self) -> Task:
    return Task(
        config=self.tasks_config['research_linkedin_task'],
        agent=self.researcher()
    )
تُستخدم التعليقة التوضيحية @task لتزيين الطرق التي تعرّف وتُرجع كائنات Task. تحدد هذه الطرق إعداد المهمة والوكيل المسؤول عنها.

6. إنشاء الطاقم

@crew
def crew(self) -> Crew:
    """Creates the LinkedinProfile crew"""
    return Crew(
        agents=self.agents,
        tasks=self.tasks,
        process=Process.sequential,
        verbose=True
    )
تُستخدم التعليقة التوضيحية @crew لتزيين الطريقة التي تنشئ وتُرجع كائن Crew. تجمع هذه الطريقة جميع المكونات (الوكلاء والمهام) في طاقم وظيفي.

إعداد YAML الكلاسيكي

في المشاريع الكلاسيكية، تُخزن إعدادات الوكلاء عادةً في ملف YAML. إليك مثالاً على كيفية ظهور ملف agents.yaml لوكيل الباحث:
researcher:
    role: >
        LinkedIn Profile Senior Data Researcher
    goal: >
        Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
        Generate a Dall-E image based on domain {domain}
    backstory: >
        You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
        Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
        professional information clearly and concisely.
    allow_delegation: False
    verbose: True
    llm: groq_llm
    tools:
        - myLinkedInProfileTool
        - mySerperDevTool
        - myDallETool
يتوافق إعداد YAML هذا مع وكيل الباحث المُعرّف في فئة LinkedinProfileCrew. يحدد الإعداد دور الوكيل وهدفه وخلفيته وخصائص أخرى مثل LLM والأدوات التي يستخدمها. لاحظ كيف يتوافق llm و tools في ملف YAML مع الطرق المزينة بـ @llm و @tool في فئة Python.

أفضل الممارسات

  • تسمية متسقة: استخدم اصطلاحات تسمية واضحة ومتسقة لطرقك. على سبيل المثال، يمكن تسمية طرق الوكلاء بأسماء أدوارهم (مثل researcher، reporting_analyst).
  • متغيرات البيئة: استخدم متغيرات البيئة للمعلومات الحساسة مثل مفاتيح API.
  • المرونة: صمم طاقمك ليكون مرناً بالسماح بإضافة أو إزالة الوكلاء والمهام بسهولة.
  • توافق YAML-الكود: في المشاريع الكلاسيكية، تأكد من أن الأسماء والهياكل في ملفات YAML تتوافق بشكل صحيح مع الطرق المزينة في كود Python الخاص بك.
باتباع هذه الإرشادات واستخدام التعليقات التوضيحية بشكل صحيح، يمكنك الحفاظ على أطقم كلاسيكية منظمة وسهلة الصيانة. للـ crews الجديدة، استخدم بنية JSON-first في Crews.