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 را نام بده و هر کدام چه زمانی نتیجه می گیرند.
• یک تیم سه عامل (مطالعه، نویسنده، ویرایشگر) که یک خلاصه تولید کند، اجرا کنید.
• سه حالت شکست CrewAI رو شناسایی کن: تندبند سریع، مالیات مدیر-LLM، دست دادن شکننده

مشکل

تیم هایی که چارچوب های چند عامل را اتخاذ می کنند به دیوار یکسان برخورد می کنند. "همکارگری مستقل" در یک دمو عالی به نظر می رسد. سپس یک مشتری یک بگ را فایل می دهد و شما نیاز به تکرار تعیین کننده دارید. یا امور مالی می پرسد که یک تیم LLM- روت شده هزینه هر اجرا است. یا در تماس نیاز به دانستن اینکه کدام عامل در ساعت 3 صبح متوقف شده است.

گروه هاي آزاد و با راه حل هاي LLM به هيچ يك از اين سوال ها پاسخ مي دهند، اما DAG هاي خالص به همه جواب مي دهند، اما شکل اکتشافي اي که يک عامل مغزي به آن نياز دارد را از دست مي دهند.

تقسیم 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.استراتژی اجرا. دنباله دار، سلسله مراتبی، توافق (منظور) شکل اجرا را انتخاب می کند.

ماموران به طور مستقیم با هم نديده اند، ماموران مرجعي کار مي کنند، خدمه کارها را دنبال مي کند، فرآیند تصمیم می گیرد که چه کسی کار بعدی را انتخاب می کند.

Validated againstCrewAI 0.86 (2026-05). نسخه های جدید تر ممکن است انواع فرآیند را تغییر نام یا ترکیب کنند.CrewAI Processes docsقبل از اینکه به شکل خاصی تکیه کند.

ترتیب و مراتب و توافق

• Sequential.وظایف به ترتیب اعلامی اجرا می شوند. محصول وظیفه N به عنوان contextبه کار N+1، کمترین هزینه، قابل پیش بینی ترین.
• Hierarchical.یک مدیر آژانس (مطالبات LLM جداگانه) مسیرهای بین متخصصان.manager_llmconfig یا default. مدیر هر دور کار بعدی را انتخاب می کند و می تواند رد یا مسیر مجدد. زمانی که شما چهار یا بیشتر متخصص دارید استفاده کنید و سفارش واقعاً به محصول قبلی بستگی دارد.
• Consensus.برنامه ریزی شده، در حال حاضر در API عمومی اجرا نشده است. اسناد نام را برای یک فرآیند مبتنی بر رای گیری آینده ذخیره می کنند. امروز به آن اعتماد نکنید.

در هر مرحله ای، قیمت توکن می تواند سه برابر شود. فقط زمانی که به رویتینگ نیاز دارید، هزینه آن را پرداخت کنید.

خدمه ها در مقابل جریان ها

این چارچوبی است که دکترها در سال 2026 با آن روبرو می شوند.

• Crew.خودمختاری مبتنی بر LLM. چارچوب شکل را در زمان اجرا انتخاب می کند. برای: تحقیق، طوفان مغزی، طرح های اول، هر کجا که مسیر بخشی از پاسخ است. سخت برای بازی مجدد. سخت برای آزمایش. ارزان برای نمونه.
• Flow.گرافي که توسط اتفاقات انجام ميده@startاین علامت ورود است.@listen(topic)هر مرحله ساده ای است (می تواند یک خدمه را در داخل صدا کند) مناسب برای: تولید. قابل مشاهده. قابل آزمایش. تعیین کننده.

توصیه تولید دکتران برای سال 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 صریح، پشتیبانی از async، تکرار. زمانی که ابزار دارای حالت (کلائیست، یک کش) یا نیاز به 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.کروآئی ها آداپتورهای اول طرف را میفرستند: SerperDevTool،FileReadTool،DirectoryReadTool،CodeInterpreterTool،RagTool،WebsiteSearchTool. با يه واردات سيمدار

از پيدانتک استفاده ميکننoutput_pydantic=MyModelدر مورد کار. CrewAI پاسخ LLM را در برابر مدل تأیید می کند و یا مجبور می کند یا دوباره تلاش می کند. این را با یکexpected_outputstring. درایورهای متن آزاد برای مسودات خوب هستند؛ درایورهای ساختار یافته چیزی هستند که جریان های زیر جریان می توانند مصرف کنند.

هک های حافظه

CrewAI چهار نوع حافظه را از جعبه خارج می کند. آنها تشکیل می دهند: یک خدمه می تواند هر چهار را به طور همزمان فعال کند.

Validated againstCrewAI 0.86 (2026-05). نسخه های اخیر همه چیز را از طریق یک سیستم متحد هدایت می کند Memoryمدل مفهومی زیر هنوز هم برقرار است، اما سطح کلاس عمومی ممکن است به یک واحد سقوط کندMemoryنقطه ورود در نسخه های جدیدتر؛ چکCrewAI memory docsبرای API فعلی.

• Short-term.بازنده مکالمه در يک بار و در آخرش پاک شده
• Long-term.در طول اجرا ها باقی مانده. در یک ویکتور DB ذخیره شده است (Chroma به طور پیش فرض، قابل تغییر). با شباهت با وظیفه فعلی بازیافت می شود.
• Entity."مشتری ایکس در برنامه شرکت است" توسط شرکت، نه به دلیل شباهت.
• Contextual.زمان جمع آوری، حافظه مربوطه رو در لحظه ای که مامور به آن نیاز داره، باز می کنه، نه قبل از بارش

فعال کردن روی خدمه با memory=Trueحافظه یکی از مکان هایی است که CrewAI در مقابل چارچوب های نازک تر خود را حفظ می کند؛ LangGraph خالص شما را نیاز دارد که هر یک از این موارد را خودتان به صورت سیم کشی کنید.

وقتی تیم های نقش بر اساس نقش مناسب هستند

• سه تا شش مامور با نقش نامگذاری شده و یک جریان کار همکاری، تهیه، بررسی، برنامه ریزی، طوفان مغزی.
• مسیر در حالی که قضاوت LLM در مورد گام بعدی بخشی از ارزش است (در درجه بندي).
• هر جا که تیم خوشحال تر باشهrole + goal + backstoryاز خواندن تعریف نمودار.

وقتی که نمیشن

• DAG های تعیین کننده با ترتیب دقیق. از LangGraph (درسی 13) استفاده کنید. شکل نمودار انتزاع صحیح است. چارچوب نقش CrewAI اصطکاک است.
• بودجه های تاخیر زیر ثانیه. سلسله مراتبی سفر و بازگشت را اضافه می کند. حتی ترتیب به ترتیب پیام هایی که شامل داستان های پس زمینه و خروجی قبلی هستند.
• حلقه های یک عامل. چارچوب را رد کنید؛ یک حلقه عامل (درس 1) به علاوه یک فهرست ابزار کوتاه تر است.

درس 17 (تجاوز های چارچوب عامل) این را در یک ماتریکس بیان می کند. نسخه کوتاه: CrewAI در گوشه "مستند به نقش همکاری" قرار دارد.

شکل وابستگی

مستقل از لانگ چین. پایتون 3.10 تا 3.13. استفاده uv. شمار ستاره ها: ببينcrewAIInc/crewAI(تصاویر از سال 2026 تا 2005). ادغام AWS Bedrock مستند شده است؛ معیار های فروشنده گزارش سرعت قابل توجهی در مقایسه با LangGraph در بار کاری QA را گزارش می دهند، اما روش (دست مجموعه داده، سخت افزار، متریک ارزیابی) منتشر نشده است، بنابراین اعداد فریم ورک- فروشنده را فقط به عنوان جهت داده ای در نظر بگیرید.

جایی که این الگوی اشتباه می شود

• Prompt-bloat from backstories.یک داستان پس زمینه 2000 کلمه برای هر نماینده و یک تیم پنج نماینده بودجه زمینه را قبل از اولین تماس ابزار می سوزاند. داستان پس زمینه را کمتر از 200 کلمه نگه دارید. عبارات را در میان عوامل تکرار کنید؛ سبک خانه را پنج بار تکرار نکنید.
• Manager-LLM token tax.فرآیند سلسله مراتبی قبل از هر تماس تخصصی یک تماس LLM مدیر را اضافه می کند. در یک تیم پنج وظیفه ای که شش تماس LLM به جای پنج است، و تماس مدیر لیست وظایف کامل و همچنین خروجی قبلی را حمل می کند. به ترتیب تغییر دهید مگر اینکه مسیر بستگی به خروجی دارد.
• Brittle handoffs.وظیفه Nexpected_outputاین یک طرح است. وظیفه N+1 آن را به عنوان contextو سعی می کنه سه بخش رو تحلیل کنه.output_pydanticدر Task N بنابراین Task N+1 یک شی تایپ شده را می خواند، نه متن آزاد.
• Crew-as-prod.فرش های آزاد بدون بسته بندی جریان به تولید فرستاده می شوند. تنوع تولید بالا است؛ تکرار غیرممکن است؛ در تماس نمی تواند یک مسابقه بد را با یک مسابقه خوب تشخیص دهد. با یک جریان بسته بندی کنید.

آن را بسازید

code/main.pyنسخه هاي STDlib هر دو شکل رو اجرا ميکنه و يه سه تا عملدار هم هست

شکل:

• Agent،Taskکلاس های داده ای که با سطح CrewAI مطابقت دارند.
• SequentialCrew.kickoff(inputs)وظایف را به ترتیب اعلامیه اجرا می کند، در نتیجه به عنوانcontext. .
• HierarchicalCrew.kickoff(topic)يه مامور مدير اضافه ميکنه که هر دور متخصص بعدي رو انتخاب ميکنه و وقتي تموم ميشه
• Flowبا@startو@listen(topic)دکوراتورها، يک حلقه کوچک از اتفاقات و يک اثر
• tool(name)دکوراتور عکس کريوااي@toolشکل
• Memoryباshort_term،long_term،entityفروشگاه ها؛ شبیه سازی مسخره ای از استفاده از نپپی استفاده می کند.
• پاسخ های جعلی LLM رشته های سخت کد شده هستند که روی کلید نقش اضافه شده است. هیچ شبکه ای نیست. تعیین کننده.

نمایش بتنی: محقق، نویسنده، تیم ویرایشگر در حال تهیه خلاصه ای در مورد "هینرنگ عامل 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در این مقاله، در مورد تیم بدون داستان پس زمینه، جریان بدون موضوعات صریح، سلسله مراتبی با کمتر از سه متخصص، سخت رد می کند.

دام ها

• Backstory as flavor.اون خروجی رو شکل میده، سه نوع رو برای هر عامل امتحان کن، تفاوت واقعی هست، یکی رو انتخاب کن، یخش بده
• Skipping expected_output.بدون قرارداد هر کار، وظایف پایین تر هر کاری که LLM تولید کرده، به دست می آید.
• Memory always-on.مدت طولانی هر اجرا را می نویسد. ویکتور DB رشد می کند. بازیافت سر و صدا می کند. دامنه به وظایف که واقعیت در آن پایدار است می نویسد.
• Manager prompt drift..مدير پيامبندي هاي سلسله مراتبي ضمني است .اگر روت شدن عجيب بشه ، اونو به حالت لفظي بذار و بخوني
• Tool side effects in Crews.يک خدمه ميتونه يه ابزار رو بيشتر از انتظار فرا ببرد.

تمرینات

1. گروه دنباله دار رو به جریان تبدیل کن، نقاط تماس رو بشمار که در آن تغییر کم شده، توجه کن که در کجا قابل خواندن کم شده
2. حافظه ی موجودی را به خدمه اضافه کنید: حقایق مربوط به یک مشتری در طول کک آف باقی می مانند. بررسی بازیافت موجودی درست را می کشاند.
3. یک فرآیند سلسله مراتبی را اجرا کنید که مدیر از مسیر به ویرایشگر انکار می کند تا زمانی که محصول نویسنده حداقل سه پاراگراف داشته باشد.
4. .BaseToolزیر کلاس برای یک جستجو وب (تبه) مقایسه کنید شکل ردیابی با @toolنسخه تزئيني
5. اضافه کردنoutput_pydantic=Briefبه وظیفه ویرایشگر، جایی کهBrief.title،summary،sections. یک بار از JSON اشتباه شکل گرفته شده را در خروجی کار نویسنده انجام دهید؛ رفتار CrewAI را در ردیابی بررسی کنید.
6. مقدمه اسناد کروآئي رو بخوني.crewaiAPI، نسخه از "استدلب" چه تضميناتي رو رد کرد؟
7. به "آژانت اوپس" يا "لانگفوز" (درسه 24) به يه سريال واقعي زنگ بزن

اصطلاحات کلیدی

خواندن بیشتر

• 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.