Phase 14: Agent Engineering

فرق العملاء القائمة على الأدوار الأدوار والمهام والعمليات

Type: Learn + Build

Languages: Python (stdlib)

Prerequisites: Phase 14 · 12 (Workflow Patterns), Phase 14 · 14 (Actor Model)

Time: ~75 minutes

أهداف التعلم

• اسم أربعة أسباب أساسية من CrewAI (الوكيل، المهمة، الطاقم، العملية) وما يملك كل واحد.
• تمييز بين التسلسل والهيئرية والعملية المخطط لها للتوافق؛ اختر واحد لكل عبء عمل.
• تمييز الطواقم (المستندة إلى الأدوار الذاتية) عن التدفقات (التحديدات القائمة على الأحداث) ، وشرح توصية الإنتاج الخاصة بالدكتور.
• أدوات الأسلاك مع @toolالمُزخرف وBaseToolالفرعية؛ الاعتبار حول الخروج المهيكل مقابل النص الحر.
• أسمائ أنواع الذاكرة الأربعة CrewAI ومتى كل منها يدفع.
• تنفيذ فريق من ثلاث عملاء (المباحث، الكاتب، المحرر) الذي ينتج تقريراً.
• اكتشاف ثلاثة أساليب فشل كرو آي: التفجير السريع، ضريبة المدير-LLM، التسليمات الهشة.

المشكلة

أفراد الفريق الذين يتبنون إطاريات متعددة الوكلاء يضربون نفس الجدار. "التعاون الذاتي" يبدو رائعاً في عرض تجريبي. ثم يقوم العميل بتقديم خطأ وتحتاج إلى إعادة التعبير المحددة. أو يسأل المالي كم يكلف طاقم مدير LLM في كل جولة. أو على المكالمة يحتاج إلى معرفة أي وكيل توقف في الثالثة صباحاً.

الطاقم المتحررة التي تتبع طريق القانون لا تجيب على أي من هذه التفاصيل بشكل نظيف

إن تقسيم CrewAI صادق بشأن التجارة. طاقم للعمل التعاوني، القائم على الأدوار، الاستكشافية. تدفقات للإنتاج القائم على الأحداث، المملوكة بالرموز، قابلة للتدقيق. نفس الإطار، شكلين، اختيار لكل سطح.

المفهوم

أربعة بدائيات

سطح الطاقم صغير، تذكر هذا والباقي هو محفوف

• Agent. role + goal + backstory + tools + (optional) llm. القصة الخلفية تحمل الحمل. إنها تشكل النغمة، الحكم، عندما يتوقف الوكيل. الأدوات هي الوظائف التي يمكن للوكيل أن يدعو (أكثر أدناه).
• Task. description + expected_output + agent + (optional) context + (optional) output_pydanticوحدة عمل قابلة لإعادة الاستخدامexpected_outputهو العقدcontextيُدرج المهام التي يتم نقل نتائجها إلى الأعلى. output_pydanticيفرض شكل مهيكلي
• Crew.حاوية، يمتلك قائمةagents، قائمةtasks،process، و اختياري memory+ verbose+ manager_llmالإعدادات
• Process.استراتيجية التنفيذ: تسلسل، Hierarchical، Consensus (مخطط) يختار شكل الجولة.

العملاء لا يراهم بعضهم البعض مباشرة، المهام هي عملاء مرجعية، الطاقم يقوم بتسلسل المهام، العملية تقرر من يختار المهمة التالية، هذا هو النموذج العقلي بأكمله.

Validated againstCrewAI 0.86 (2026-05). الإصدارات الحديثة قد تُعيد تسمية أو دمج أنواع العملية. تحقق من CrewAI Processes docsقبل الاعتماد على شكل معين

التسلسل مقابل الهيراخرية مقابل الإجماع

• Sequential.المهام تتم بالترتيب الذي أعلنت به.contextأقل تكلفة، أكثر قابلية للتنبؤ، استخدم عندما يتم تحديد الطلب.
• Hierarchical.وكيل مدير (مكالمة LLM منفصلة) الطرق بين المتخصصين. CrewAI يولد المدير إما منmanager_llmإعداد أو افتراض. يختار المدير المهمة التالية في كل جولة ويمكن رفض أو إعادة توجيه. استخدم عندما يكون لديك أربعة أو أكثر من المتخصصين والطلب يعتمد حقا على الناتج السابق.
• Consensus.المخطط، غير تنفيذ حاليا في API العام. الأدلة تحفظ الاسم لعملية مستقبلية القائمة على التصويت. لا تعتمد عليه اليوم.

يضيف التسلسل الهرمي مكالمة LLM لكل جولة (المدير) فوق كل مكالمة متخصصة. يمكن أن تتضاعف تكلفة الوهم في رحلة خمس خطوات. دفعها فقط عندما تحتاج إلى التوجيه.

الطواقم مقابل التدفقات

هذا هو الإطار الذي يقود به الأطباء في عام 2026.

• Crew.الذاتية القائمة على ماجستير في التدريس. الإطار يختار الشكل في وقت التشغيل. جيد للبحث، ومعاصفة الأفكار، المسودات الأولى، أينما كان المسار جزءا من الإجابة. صعب التلاعب. صعب الاختبار. رخيص للنموذج الأول.
• Flow.الرسم البياني القائم على الأحداث التي تملكها@startيُعَلِّمُ الدخول.@listen(topic)يُرمز خطوة تنطلق عندما تنشر خطوة أخرى هذا الموضوع. كل خطوة هي Python بسيطة (يمكن دعوة طاقم داخلياً). جيد ل: الإنتاج. قابل للملاحظة. قابل للتحقق. تحديد.

توصية الطلاب في عام 2026: البدء بتدفق.Crew.kickoff()تدخل الطرق من داخل التدفق عندما تكسب الحكم الذاتي تكلفته التدفق يعطيك المسار المراجعة الطاقم يعطيك الاستكشاف

تكامل الأدوات

ثلاثة طرق لإعطاء العميل أداة اختر أسهل أداة تناسبك

1. @tool decorator.تصبح الوظائف النقية أدوات. التوقيع هو النظام؛ وثيقة القاعدة هو وصف LLM يرى. أفضل للمساعدين مرة واحدة.

```python

from crewai.tools import tool

@tool("Search the web")

def search(query: str) -> str:

"""Return top results for the query."""

return run_search(query)

```

1. BaseTool subclass.أداة على أساس الفئة مع مخطط args صريح، دعم التزام المزامن، محاولات إعادة. استخدم عندما يكون لدى الأداة حالة (عميل، مخزن مخزن) أو تحتاج إلى args مهيكلة.

```python

from crewai.tools import BaseTool

from pydantic import BaseModel

class SearchArgs(BaseModel):

query: str

limit: int = 10

class SearchTool(BaseTool):

name = "web_search"

description = "Search the web and return top results."

args_schema = SearchArgs

def _run(self, query: str, limit: int = 10) -> str:

return self.client.search(query, limit=limit)

```

1. Built-in toolkits.جهاز CrewAI يُرسل مُعدّلات الطرف الأول: SerperDevTool،FileReadTool،DirectoryReadTool،CodeInterpreterTool،RagTool،WebsiteSearchTool-مُتواصلة مع إحدى الواردات

المخرجات المهيكلة تستخدم Pydantic.output_pydantic=MyModelعلى المهمة. CrewAI تؤكد استجابة LLM ضد النموذج وإما الإكراه أو محاولات إعادة.expected_outputالخروج من النص الحر جيد للمخططات؛ الخروج المهيكلة هي ما يمكن أن تستغله التدفقات التدريبية.

مضادات الذاكرة

يُخرج جهاز CrewAI أربعة أنواع من الذاكرة من الصندوق، وهي تكوّن: يمكن للطاقم تمكين الأربعة في وقت واحد.

Validated againstCrewAI 0.86 (2026-05). الإصدارات الأخيرة تسير كل شيء من خلال نظام موحد Memoryالنموذج المفاهيمي أدناه لا يزال قائماً، ولكن سطح الطبقة العامة قد ينهار إلى واحد Memoryنقطة دخول في الإصدارات الأخيرة .CrewAI memory docsلل API الحالية.

• Short-term.حافز محادثة في غضون جولة واحدة تم مسحها في النهاية
• Long-term.استمر عبر الجرائد. مخزن في DB المتجه (Chroma من قبل الافتراض، قابل للتبادل). يتم استرداده من خلال التشابه مع المهمة الحالية.
• Entity." العميل X في خطة الشركة " يُحدد من قبل الكيان وليس من خلال التشابه.
• Contextual.يسترد وقت التجميع، يستخرج الذاكرة ذات الصلة في اللحظة التي يحتاجها العميل، وليس قبل التحميل.

أجهز على الطاقم مع memory=Trueأو حسب النوع. مدعوم من قبل مزود التوابل التي تقوم بتكوينها (الديفالتيات إلى OpenAI ، قابل للتبادل إلى المحلي). الذاكرة هي واحدة من الأماكن التي تستحق CrewAI احتفاظها ضد الإطارات الرقيقة.

عندما تتلائم فرق المهام

• ثلاثة إلى ستة عملاء مع أدوار معينة وتدفق عمل تعاوني، صياغة، مراجعة، تخطيط، استفجار أفكار.
• التوجيه حيث تقرير الجامعة القانونية حول الخطوة التالية هو جزء من القيمة (الهيراركية).
• أي مكان يُسعد الفريق فيه القراءةrole + goal + backstoryمن قراءة تعريف الرسم البياني.

عندما لا يفعلون

• استخدام لنجراف (درس 13) شكل الرسم البياني هو مجردة صحيحة؛ إطار دور CrewAI هو الاحتكاك.
• ميزانيات التأخير الفرعية الثانية. الهيروقية تضيف رحلات ذهابًا وإيابًا. حتى التسلسل يسلسل الطلبات التي تشمل القصص الخلفية والخروج السابقة.
• حلقات وكيل واحد. تخطي الإطار؛ حلقة وكيل (درس 1) زائد سجل الأدوات هو أقصر.

الدرس 17 (تجارة الإطار العميل) يوضح هذا في المصفوفة. النسخة القصيرة: CrewAI يجلس في الزاوية "المتعاونية القائمة على الدور".

شكل الاعتماد

مستقل عن لانغ تشين. بايثون 3.10 إلى 3.13. استخدامات uv. العد النجم: انظرcrewAIInc/crewAI(تصوير مفاجئ اعتبارًا من 2026-05). يتم توثيق تكامل AWS Bedrock؛ تقرير مقارنات البائعين عن تسريع كبير مقابل LangGraph على أحمال العمل في QA ، ولكن لا يتم نشر المنهج (مجموعة البيانات والجهازات والأجهزة ومقاييس التقييم) ، لذلك تعامل أرقام الإطار-البائعين كإرشاد فقط.

حيث يذهب هذا النمط خطأ

• Prompt-bloat from backstories.قصة خلفية 2000 كلمة لكل وكيل وطاقم من خمسة عملاء تحرق ميزانية السياق قبل أول مكالمة أداة. احتفظ بالقصص الخلفية تحت 200 كلمة. استعمل عبارات عبر العملاء؛ لا تكرر نمط المنزل خمس مرات.
• Manager-LLM token tax.عملية الهرمية تضيف مكالمة مدير LLM قبل كل مكالمة متخصصة. على طاقم من خمسة مهام هو ستة مكالمات LLM بدلا من خمسة، والكالم مدير يحمل قائمة المهام الكاملة بالإضافة إلى المخرجات السابقة. الانتقال إلى التسلسل ما لم يعتمد التوجيه على المخرج.
• Brittle handoffs.المهمة N expected_outputهي "خطاط". المهمة N+1 تقرأها على أنها contextويحاول تحليل ثلاثة أقسام، وقدمت الهيئة أربعة، وذلك من خلال إعلانات العميل المتدفق عليها،output_pydanticعلى المهمة N لذلك المهمة N + 1 تقرأ كائنًا مكتوبًا ، وليس نصًا حرًا.
• Crew-as-prod.الطاقم الحر يتم شحنه إلى الإنتاج دون غلاف التدفق. تغيرات الإنتاج مرتفعة؛ لا يمكن إعادة تشغيلها؛ لا يمكن التمييز بين الجولة السيئة مقابل الجولة الجيدة. غلف مع التدفق.

بناءها

code/main.pyيطبق نسخة ستدليب من كلا الشكلين بالإضافة إلى طاقم من ثلاثة عملاء

الشكل:

• Agent،Taskفصول البيانات تتطابق مع سطح جهاز الطيران.
• SequentialCrew.kickoff(inputs)يدير المهام بالترتيب الإعلاني، وتقوم بتصفيف المخرجات على النحوcontext. . .
• HierarchicalCrew.kickoff(topic)يضيف مدير وكيل يختار المتخصص التالي في كل جولة، يتوقف عند "مكتمل".
• Flowمع@startو@listen(topic)المزخرفات، حلقة صغيرة من الحدث، وآثر.
• tool(name)المُزخرف يُعكس كروآاي@toolالشكل
• Memoryمعshort_term،long_term،entityالمتاجر؛ التشابه المهزوم يستخدم المثالي.
• ردود القانون الاختراعي هي سلسلة مشفرة صلبة مع إغلاق الرول بالإضافة إلى المضيف الإدخالي لا شبكة.

التجربة الملموسة: الباحث، الكاتب، طاقم المحرر ينتج قصة عن "هندسة العملاء 2026". الباحث يسحب المصادر (التهزئة). مصادر الكاتب. يضيق المحرر. نفس طاقم يمر من خلال تدفق لإظهار الشكل التحديدي.

إشغله

bashCopypython3 code/main.py

تغطية البصمات: خروجيات الطاقم المتسلسلة من خلال context، طاقم سلسلي مع اختيارات المدير (الباحث، الكاتب، المحرر، ثم "فعل") ، تدفق على نفس الخطوات الثلاثة مع مواضيع صريحة (researched،drafted،edited), مكالمات الأداة المُتوجّهة عبر @toolوذاكرة طويلة الأجل على قيد الحياة على الرغم من ركلتين.

و تَتَعَدّى أثر الطاقم سائلًا، يمكن للمدير في المبدأ إعادة التَنظُّم. تَتَعَدّى أثر التدفق. هذا الخيار هو الدروس.

استخدمها

• CrewAI Flowحتى عندما يكون التدفق خطوة واحدة التي تدعوCrew.kickoff()-تدفق يمنح الحدود المراجعة
• CrewAI Crew (Sequential)للعمل التعاوني الموضح، وخاصة المخططات الأولى وخطوط المراجعة.
• CrewAI Crew (Hierarchical)عندما يعتمد التوجيه على الخروج و لديك أربعة أو أكثر من المتخصصين.
• LangGraph(الدرس 13) للآلات الحكومية الصريحة، سير سيرته الذاتية الدائمة، التنظيم الصارم.
• AutoGen v0.4(الدرس 14) لتحقيق التوافق مع نموذج الممثل وعزل الأخطاء.
• OpenAI Agents SDK(دروس 16) للمنتجات الأولى من OpenAI مع المرافق والحواجز.
• Claude Agent SDK(الدرس 17) للمنتجات الأولى من كلود مع السباقات والمحلات التجارية.

أرسله

outputs/skill-crew-or-flow.mdيختار فريق ضد التدفق للمهمة ويقوم بتنفيذ الحد الأدنى. يرفض هارد على مواضيع فريق دون خلفية، تدفق دون موضوع واضح، hierarchical مع أقل من ثلاثة متخصصين.

الفخاخ

• Backstory as flavor.إنه يشكّل الخروج، اختبر ثلاثة خيارات لكل وكيل، الخيار حقيقي، اختر واحد، ثم تجمده.
• Skipping expected_output.بدون عقد لكل مهمة، المهام المتدفقة تتحمل ما ينتجته الهيئة
• Memory always-on.المدى الطويل يكتب كل مرة، ويتزايد الجهاز المتجه إلى النقل، ويتزايد الضجيج، ويتم إعادة التأثير، ويتم إعادة التأثير إلى المهام التي لا تزال موجودة.
• Manager prompt drift.إن أصبح التوجيه غريبًا، فلترميه في وضع اللفظ وتقرأ
• Tool side effects in Crews.يمكن للطاقم استدعاء أداة أكثر من المتوقع.

التمارين

1. حول طاقم التسلسل إلى تدفق، عد نقاط التواصل حيث ينخفض التغيرات، لاحظ حيث انخفض القراءة.
2. إضافة ذاكرة الكيانات إلى الطاقم: الحقائق حول العميل تستمر على الرغم من الركضات. التحقق من استرداد يسحب الكيان الصحيح.
3. تنفيذ عملية Hierarchical حيث يرفض المدير توجيه إلى المحرر حتى يكون إنتاج الكاتب ثلاثة فقرات على الأقل. تتبع محاولة إعادة.
4. سلكيBaseToolفئة فرعية للبحث على شبكة الإنترنت. مقارنة شكل البحث مقابل@toolإصدار ديكورات
5. إضافةoutput_pydantic=Briefإلى مهمة المحرر، حيث Brief- نعمtitle،summary،sections. جعل مصدر مهمة الكاتب JSON غير مصمم مرة واحدة؛ التحقق من سلوك CrewAI في التتبع.
6. اقرأ مقدمة وثائق "كرو آي" و احملي اللعبة إلى الواقعcrewaiأي ضمانات تخطى نسخة (ستدليب) ؟
7. أرسلي العميل أو (لانغفوز) إلى عملية حقيقية، أي آثار فاتت في إصدار (ستدليب) ؟

الشروط الرئيسية

المزيد من القراءة

• CrewAI docs introduction: المفاهيم والمسار الإنتاجي الموصى به
• CrewAI Flows guide: شكل مدفوع بالحدث@start،@listen
• CrewAI tools reference: @tool،BaseTool، أدوات متكاملة
• CrewAI memory: قصير الأجل، طويل الأجل، الكيان، السياقي
• Anthropic, Building Effective Agents: عندما يساعد العامل المتعدد و عندما لا
• LangGraph overview: البديل من آلة الدولة

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.