نحوه استفاده از CrewAI: راهنمای عملی برای روندهای چندعاملۀ کاری
قول بزرگ: اگر تا به حال آرزو کردهاید که بتوانید بهترین همتیمی خود را تکثیر کنید تا پروژهای را سریعتر انجام دهید، CrewAI شما را نزدیک میکند – با هماهنگی چند عامل هوش مصنوعی که برنامهریزی، همکاری و تحویل کار را با هم به عهده میگیرند.
در این راهنمای عملی و راهحلمحور، دقیقا خواهید آموخت چگونه از CrewAI استفاده کنید: از نصب چارچوب و تعریف عاملها گرفته تا ساخت نقشها، ابزارها، وظایف و روندهای ساختیافته چندعامله که نتایج واقعی ارائه میدهند. الگوهایی برای تحقیق، محتوا، تحلیل داده و تولید کد را پوشش خواهیم داد – و چگونگی اجتناب از مشکلات رایجی مانند بنبست عاملها، فزونی دستورات و استفاده بیش از حد از ابزارها.
تمرکز ما: ارائه مسیر مرحلهبهمرحله “همین امروز امتحان کنید” همراه با کد قابل کپی و جایگذاری، بهترین شیوههای آزمودۀ میدان نبرد و چند الگوی کاری که میتوانید تطبیق دهید. چه در حال اتوماسیون تحقیقات بازار باشید و چه ساخت مشخصات محصول از تیکتها، این راه شروع بهکار مفید با CrewAI است.
CrewAI چیست (و چرا متفاوت است)
- CrewAI چارچوبی برای ساخت سیستمهای چندعامله است که هر عامل نقش، هدف، ابزارها و قواعد دارد. سپس چارچوب این عاملها را هماهنگ میکند — تحویل وظایف، به اشتراکگذاری زمینه، و تکرار تا تولید خروجی.
- برخلاف یک دستور ساده برای یک مدل زبان بزرگ، CrewAI ساختار را اجبار میکند: عاملها مشخصاند، وظایف مدولارند، ابزارها مجازند و نتایج قابل بررسیاند.
- دستاورد: روندهای تفکیکشده (تحقیق → ترکیب → نگارش → کنترل کیفیت) که شبیه نحوه کار تیمهای واقعی هستند — فقط سریعتر، مقیاسپذیرتر و قابل بازتولید.
شروع سریع: چطور در ۱۰ دقیقه از CrewAI استفاده کنیم
در ادامه الگوی حداقلی است که شما را از صفر به یک گروه کاری چندعامله فعال میرساند. فرض بر این است که از پایتون استفاده میکنیم.
1) نصب و راهاندازی
pip install crewai langchain-openai python-dotenv
یک فایل .env با کلیدهای ارائهدهنده مدل زبان خود بسازید:
OPENAI_API_KEY=sk-your-key
# یا دیگر ارائهدهندگان پشتیبانیشده
2) تعریف عاملها (نقشها + هدفها + ابزارها)
from crewai import Agent
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
researcher = Agent(
role="Market Researcher",
goal="پیدا کردن بینشهای معتبر و بهروز در مورد بازار هدف و رقبا.",
backstory=(
"شما تحلیلگری دقیق هستید که ادعاها را بررسی، منابع را ارجاع و "
"نشانهها را از منابع معتبر خلاصه میکنید."
),
tools=[], # بعدا ابزارهای جستجو، وبخراش اضافه کنید
llm=llm
)
strategist = Agent(
role="Product Strategist",
goal="ترکیب تحقیقها در یک موقعیتگذاری دقیق و گزینههای نقشه راه.",
backstory="شما وضوح، قابلیت اجرا و نتایج قابل اندازهگیری را اولویت میدهید.",
tools=[],
llm=llm
)
writer = Agent(
role="Content Writer",
goal="تولید یک خلاصه ساختارمند با مثالها و گامهای بعدی.",
backstory="شما به انگلیسی مختصر و قانعکننده مینویسید و راهنماهای سبک را دنبال میکنید.",
tools=[],
llm=llm
)
3) خلق وظایف (ورودیها، خروجیها و معیارهای پذیرش)
from crewai import Task
research_task = Task(
description=(
"تحقیق در بازار نرمافزار مدیریت پروژه کسبوکارهای کوچک و متوسط در آمریکا در سال ۲۰۲۵. "
"شناسایی رقبای اصلی، طبقات قیمت، پروفایل مشتری ایدهآل و سه نیاز برآورده نشده. "
"خروجی به صورت نکتهوار با ۳-۵ منبع ارجاعی باشد."
),
expected_output=(
"خلاصهای به فرمت Markdown با بخشهای: اندازه بازار، بازیگران کلیدی، قیمتگذاری، پروفایل مشتری، "
"نیازهای برآورده نشده، منابع (با لینک)."
),
agent=researcher
)
synthesis_task = Task(
description=(
"استفاده از خلاصۀ تحقیق برای تولید بیانیۀ موقعیتگذاری، ۲-۳ تمایز و "
"یک نقشه راه ۹۰ روزه با نقاط عطف."
),
expected_output="خلاصهای استراتژیک و مختصر (کمتر از ۴۰۰ کلمه).",
agent=strategist
)
writing_task = Task(
description=(
"تبدیل خلاصۀ استراتژی به یک صفحه عمومی شامل عنوان، "
"ارزش پیشنهادی، نکات ویژگی و دعوت به اقدام."
),
expected_output="یک صفحه Markdown مناسب صفحه فرود.",
agent=writer
)
4) هماهنگی گروه (روند + حافظه)
from crewai import Crew
crew = Crew(
agents=[researcher, strategist, writer],
tasks=[research_task, synthesis_task, writing_task],
process="sequential", # تحویل مرتب خروجیها
verbose=True
)
result = crew.kickoff
print(result)
این اولین پایپلاین کاری شماست. عاملها را تعریف کردید، وظایف را متصل کردید و جریان ترتیبی را اجرا نمودید. برای گسترش، ابزار (جستجو، خراش، اجرای کد)، مراحل اعتبارسنجی و موازی اضافه کنید.
یک مدل ذهنی برای پروژههای CrewAI
مثل یک مدیر پروژه فکر کنید:
- نقشها: چه کسی چه کاری انجام میدهد؟ پژوهشگر، تحلیلگر، مهندس، بازبینیکننده.
- قوانین: چه استانداردهایی باید رعایت شود؟ راهنمای سبک، ارجاعات، تستها.
- ابزارها: چه قابلیتهایی مجاز است؟ جستجوی وب، پایگاه داده وکتور، پایتون، APIها.
- وظایف: چگونه مشکل تقسیم میشود؟ ورودیها، خروجیها، معیارهای پذیرش.
- تحویلها: چه چیزی منتقل میشود؟ مستندات، فرادادهها، محدودیتها.
- بازخورد: چه کسی اعتبارسنجی میکند؟ عامل کنترل کیفیت، انسان در حلقه، یا تستها.
با CrewAI، کد شما این مدل عملیاتی را رمزگذاری میکند.
نحوه استفاده از CrewAI برای کار واقعی: 5 الگوی اثباتشده
1) تحقیق → ترکیب → پیشنویس (محتوا و گزارشها)
- عاملها: پژوهشگر، ویراستار، نویسنده، بررسیکننده صحت.
- ابزارها: جستجوی وب، بررسی منبع، راهنمای سبک.
- نکته: اجبار به ارجاع و جدول ادعاها برای جلوگیری از توهمات.
fact_checker = Agent(
role="Fact Checker",
goal="ارزیابی صحت همه ادعاها بر اساس منابع اولیه؛ علامتگذاری ارجاعات ضعیف.",
backstory="شکاک، دقیق، بیطرف.",
llm=llm
)
qa_task = Task(
description="اعتبارسنجی همه جملات واقعی؛ افزودن اصلاحات در متن با برچسب [FIX].",
expected_output="یک پیشنویس اصلاحشده با خلاصه اصلاحات.",
agent=fact_checker
)
2) مشخصات محصول از تیکتها (مهندسی)
- عاملها: دستهبند تیکتها، نویسنده مشخصات، بازبین، نویسنده تست.
- ابزارها: API ردیاب مسائل، زمینه کد با تعبیهها، تولیدکننده تست واحد.
- نکته: اضافه کردن چکلیست خودکار "تعریف انجام".
3) داده → بینش → روایت (تحلیل)
- عاملها: گردآورنده داده (پایتون)، تحلیلگر، داستانگو.
- ابزارها: Pandas، SQL، نمودارسازی، اجرای نوتبوک.
- نکته: استفاده از عامل مجهز به ابزار با اجرای
python برای تحلیلهای قابل تأیید.
4) تولید کد با حفاظها
- عاملها: برنامهریز، کدزن، بررسیکننده سبک، تستر، بازبین.
- ابزارها: خواندن مخزن، اجرای تست واحد، فرمتکننده، اسکنر امنیتی.
- نکته: الزام بازبین به استناد به تستهایی که صحت را اثبات میکنند.
5) توالیهای ایمیل مشتری در مقیاس
- عاملها: بخشبند، نویسنده متن، شخصیساز، کنترل کیفیت.
- ابزارها: API مدیریت ارتباط با مشتری، قالبها، راهنمای لحن برند.
- نکته: افزودن ابزار بررسی ایمیل برگشتی/اسپم و اجباری کردن نسخههای A/B.
افزودن ابزارها: به عاملها قابلیت واقعی بدهید
CrewAI زمانی میدرخشد که عاملها بتوانند از ابزارها استفاده کنند. مثال: دادن جستجوی وب و خواننده URL به پژوهشگر.
from langchain_community.tools import DuckDuckGoSearchRun
from langchain_community.document_loaders import WebBaseLoader
search = DuckDuckGoSearchRun
def web_search_tool(query: str):
return search.run(query)
def read_url_tool(url: str):
loader = WebBaseLoader(url)
docs = loader.load
return "\n\n".join([d.page_content[:2000] for d in docs])
researcher.tools = [web_search_tool, read_url_tool]
بهترین روشها:
- حداقل امتیاز: فقط ابزارهایی که عامل واقعا نیاز دارد را متصل کنید.
- رعایت ساختار: ابزارها باید قطعی و دارای نوع باشند؛ در صورت امکان، متن مختصر و ساختارمند (JSON/Markdown) بدهند.
- کنترل هزینه: خروجی ابزار را کوتاه نگه دارید؛ قبل از تحویل خلاصه کنید.
طراحی وظایف موفق
وظایف خوب طراحی شده موفقیت سیستمهای چندعامله را تضمین میکنند.
- صریح باشید: “جدولی به فرمت markdown با ستونهای X, Y, Z برگردان.”
- معیارهای پذیرش را تعریف کنید: “شامل ۳ ارجاع به منابع اولیه باشد.”
- محدودیت تعیین کنید: تعداد کلمه، محدودیت زمانی یا مرحلهای برای کاهش انحراف.
- مثالها را درج کنید: یک مشخصۀ کوچک از فرمت خروجی مورد نظر ارائه دهید.
- برچسبهای حافظه اضافه کنید: از عناوین/کلیدهای سازگار در وظایف برای تحویلهای آسان استفاده کنید.
نمونه قالب وظیفه:
Task(
description=(
"خلاصه ۵ مطالعه اخیر درباره بهرهوری کار از راه دور (۲۰۲۳–۲۰۲۵) با "
"روششناسی، حجم نمونه و یافتههای کلیدی."
),
expected_output=(
"Markdown با بخشهای H2 برای هر مطالعه، جدول مقایسه نهایی و لینکها."
),
agent=researcher
)
حالتهای هماهنگی: ترتیبی در مقابل موازی در مقابل ترکیبی
- ترتیبی: تحویل مطمئن؛ کندتر ولی سادهتر برای فهمیدن.
- موازی: چند عامل همزمان کار میکنند (مثلاً ۳ پژوهشگر)؛ بعدا ترکیب نتیجه.
- ترکیبی: تحقیق پخششده به صورت موازی → ترکیب و کنترل کیفیت متمرکز.
مثال ترکیبی:
r1 = Agent(role="Researcher A", goal="تمرکز بر قیمتگذاری", backstory="", llm=llm)
r2 = Agent(role="Researcher B", goal="تمرکز بر ویژگیها", backstory="", llm=llm)
# وظایف موازی برای r1, r2؛ وظیفه ترکیبی دنبال میکند.
نکته: هنگام ترکیب، به ترکیبکننده دستور بدهید که تکراریها را حذف، تعارضها را حل و منبع قویتر را ارجاع دهد.
حفاظت و کنترل کیفیت: عاملها را قابل اعتماد نگه دارید
- داوران: اضافه کردن بازبین یا بررسیکننده صحت با قدرت وتو مشخص.
- چکلیستها: انطباق (حریم خصوصی، امنیت، لحن برند) را به عنوان چکلیستی که عامل کنترل کیفیت علامت میزند رمزگذاری کنید.
- خودانتقادی: از عاملها بخواهید بخشی کوتاه "چه چیزهایی ممکن است از دست داده باشم" اضافه کنند.
- قطعی بودن: برای عاملهای کنترل کیفیت دمای پایینتر استفاده کنید.
qa = Agent(
role="QA Reviewer",
goal="اطمینان از مطابقت خروجیها با معیارهای پذیرش و راهنمای سبک.",
backstory="شما سختگیر و دقیق هستید.",
llm=llm
)
مهندسی درخواست برای عاملهای CrewAI
دستورات عاملهای شما شرح شغل کوتاهی هستند. آنها را مختصر نگه دارید.
- دستور نقش: شما کی هستید، چه چیزی را بهینه میکنید.
- دستور هدف: وضعیت نهایی مورد انتظار.
- محدودیتها: تعداد کلمه، فرمت، لحن، مراجع.
- ابزارها: نامها، زمان استفاده، و خروجی مورد انتظار.
- مثالها: ۱-۲ نمونه کوتاه و واقعی.
نمونه:
researcher = Agent(
role="تحقیقگر تحلیلی",
goal=(
"تحویل خلاصههای فشرده، دقیق با ۳-۵ ارجاع معتبر و نوت ریسک."
),
backstory=(
"شما ادعاها را بررسی، منابع اولیه را ترجیح و عدم قطعیت را علامتگذاری میکنید."
),
llm=llm
)
قابلیت مشاهده: ببینید عاملها چه کردند (و چرا)
لاگهای کامل را فعال و مستندات را ذخیره کنید:
- هر درخواست، خروجی و فراخوان ابزارهای هر وظیفه را ذخیره کنید.
- یک فایل ثبت اجرا با فراداده (مدل، دما، ابزارها) نگه دارید.
- دفترچه یادداشت برای یادداشتهای موقت نگه دارید؛ این به عیبیابی و بررسی کمک میکند.
الگو:
crew = Crew(..., verbose=True, output_log_file="runs/2025-crew.log")
نکات هزینه، تاخیر و قابلیت اطمینان
- دستهبندی: وظایف مستقل را به صورت موازی اجرا کنید؛ سطح همزمانی را برای جلوگیری از محدودیتهای نرخ کنترل کنید.
- خلاصهسازی: مستندات میانی را فشرده کنید تا مصرف توکن کاهش یابد.
- ذخیرهسازی: مراحل پایدار (مثلاً تعاریف بازار) را با پایگاه وکتور کش کنید.
- برگردانها: یک مدل پشتیبان یا سیاست تکرار برای فراخوانهای نامطمئن فراهم کنید.
- انسان در حلقه: در مراحل پرخطر درگاههای تایید اختیاری قرار دهید.
اشتباهات رایج (و چگونگی رفع آنها)
- اشتباه: وظایف مبهم → خروجیهای سرگردان.
- رفع: معیارهای پذیرش صریح و مثالها اضافه کنید.
- اشتباه: ابزارهای زیاد → حواسپرتی و هزینه بالا.
- رفع: فقط ابزارهای لازم و خاص وظیفه را داشته باشید.
- اشتباه: حلقههای بینهایت یا تکرار بیش از حد.
- رفع: محدودیتهای مرحله/زمان و بند "اگر معیارها برآورده شد توقف کن" اضافه کنید.
- اشتباه: از دست دادن زمینه در بین عاملها.
- رفع: از اشیای تحویل ساختارمند (JSON) و عناوین ثابت استفاده کنید.
- اشتباه: کنترل کیفیت بهصورت افراطی در انتها.
- رفع: کنترل کیفیت را به عنوان عامل درجه یک با قدرت وتو لحاظ کنید.
مثال جامع: تولید خلاصۀ رقابتی
هدف: تولید خلاصه رقابتی مقایسه سه ابزار برای پروفایل هدف.
عاملها:
- تحلیلگر پرسونای مشتری → تعریف نقاط درد و کارهای انجام شدنی.
- پژوهشگر → جمعآوری دادهها و ارجاعات.
- ترکیبکننده → ساخت جدول مقایسه و ارائه بینشها.
- نویسنده → تولید خلاصۀ نهایی.
- کنترل کیفیت → اعتبارسنجی منابع و وضوح.
قالب:
persona = Agent(role="Persona Analyst", goal="تعریف ICP و JTBD.", llm=llm)
researcher = Agent(role="Researcher", goal="جمعآوری دادههای معتبر.", llm=llm)
synth = Agent(role="Synthesizer", goal="مقایسه و تفسیر.", llm=llm)
writer = Agent(role="Writer", goal="ایجاد خلاصه اجرایی آماده.", llm=llm)
qa = Agent(role="QA", goal="اعتبارسنجی ادعاها و وضوح.", llm=llm)
persona_task = Task(description="تعریف ICP و JTBD برای رهبران RevOps در SaaS.", agent=persona,
expected_output="نکات کلیدی + نقاط درد + معیارهای موفقیت.")
research_task = Task(description="جمعآوری قیمت، ویژگیها، و بررسیها برای ۳ ابزار.", agent=researcher,
expected_output="جدول + ۵ ارجاع.")
synth_task = Task(description="ساخت ماتریس مقایسه و ۳ بینش برتر.", agent=synth,
expected_output="جدول Markdown + بینشها.")
write_task = Task(description="پیشنویس خلاصۀ یک صفحه با توصیهها.", agent=writer,
expected_output="خلاصۀ اجرایی به فرمت Markdown.")
qa_task = Task(description="بررسی دقت و خوانایی؛ رفع مشکلات.", agent=qa,
expected_output="خلاصۀ پاک و اعتبارسنجی شده.")
crew = Crew(agents=[persona, researcher, synth, writer, qa],
tasks=[persona_task, research_task, synth_task, write_task, qa_task],
process="sequential", verbose=True)
print(crew.kickoff)
چه زمانی از CrewAI استفاده کنیم و کی از یک دستور واحد؟
از CrewAI استفاده کنید وقتی:
- کار به صورت طبیعی به نقشها یا مراحل تقسیم میشود.
- نیاز به ردیابی، کنترل کیفیت یا استفاده از ابزار دارید.
- شما در حال ساخت یک پایپلاین قابل استفاده مجدد هستید، نه یک کار یکباره.
از یک دستور واحد استفاده کنید وقتی:
- کار کوتاه، ذهنی و بدون نیاز به ابزار خارجی است.
- سرعت از ساختار مهمتر است.
راستی: سریعتر پیشنویس کنید با پنل جانبی هوش مصنوعی
اگر از روندهای چندعامله برای تحقیق، طرحریزی و نگارش محتوا استفاده میکنید، بد نیست بدانید پنل جانبی هوش مصنوعی مثل Sider.ai کنار مرورگر و اسناد شما میتواند صفحات را خلاصه، طرحها را ایجاد و پیشنویسها را در زمان واقعی اصلاح کند. این جایگزین هماهنگی CrewAI نیست، اما میتواند بخشهای دستی — جمعآوری قطعات، بازنویسی بخشها یا بررسی لحن — را سریعتر انجام دهد پیش از اینکه محتوا را به گروه خود تحویل دهید. گامهای عملی بعدی
- CrewAI را نصب کرده و مثال شروع سریع را اجرا کنید.
- یک روند واقعی انتخاب کنید (تحقیق → پیشنویس → کنترل کیفیت) و رمزگذاری کنید.
- یک ابزار را بهتدریج اضافه و تأثیر آن بر کیفیت خروجی و هزینه را بسنجید.
- یک عامل کنترل کیفیت با معیارهای پذیرش صریح معرفی کنید.
- برای سرعت به مدل هماهنگی ترکیبی بروید.
نکات کلیدی
- CrewAI پروژههای پیچیده را به روندهای چندعامله مدولار تبدیل میکند.
- موفقیت به نقشهای دقیق، وظایف واضح و استفاده منظم از ابزارها وابسته است.
- حفاظتها (کنترل کیفیت، چکلیستها، محدودیتها) هزینه را کاهش داده و کیفیت را افزایش میدهند.
- از کوچک شروع کنید، سپس با تحقیق موازی و جریانهای ترکیبی مقیاس دهید.
چکلیست کوچک: چگونه موثر از CrewAI استفاده کنیم
- نقشها، اهداف و ابزارها را صریح تعریف کنید.
- وظایف را با معیارهای پذیرش و مثالها بنویسید.
- برای اطمینان «ترتیبی»، برای سرعت «ترکیبی» انتخاب کنید.
- کنترل کیفیت را زود اضافه کنید؛ به آن قدرت وتو بدهید.
- همه چیز را لاگ نگه دارید و مستندات را برای بازرسی ذخیره کنید.
- هزینه را با خلاصهها، ذخیره و دستهبندی بهینه کنید.
سوالات متداول
س1: CrewAI چیست و چگونه آن را برای روندهای چندعامله استفاده کنم؟
CrewAI چارچوبی برای هماهنگی چند عامل هوش مصنوعی با نقشها، وظایف و ابزارهاست. شما عاملها را تعریف میکنید، وظایف با معیارهای پذیرش میسازید و گروهی را اجرا میکنید که تحویلها را مدیریت میکند تا خروجی نهایی تولید شود.
سوال ۲: چگونه میتوانم ابزارهایی مانند جستجوی وب را به عوامل CrewAI اضافه کنم؟
توابع ابزار را به یک عامل متصل کنید و دستور دهید که چه زمانی از آنها استفاده کند. خروجیها را به صورت ساختاریافته و کوتاه (به عنوان مثال JSON یا markdown) نگه دارید تا هزینه را کنترل کرده و تحویلها را بهبود بخشید.
سوال ۳: چه زمانی باید از CrewAI به جای یک اعلان LLM تکی استفاده کنم؟
زمانی از CrewAI استفاده کنید که یک کار به مراحلی تقسیم میشود، نیاز به استفاده از ابزار یا QA دارد، یا به خطوط لوله تکرارپذیر نیاز است. از یک اعلان تکی برای کارهای سریع و ذهنی که نیازی به ساختار ندارند استفاده کنید.
سوال ۴: چگونه میتوانم از توهم (Hallucination) در خروجیهای CrewAI جلوگیری کنم؟
یک عامل Fact‑Checker یا QA با قدرت وتو اضافه کنید، استناد به منابع اصلی را الزامی کنید، دمای (Temperature) پایین برای QA تنظیم کنید، و معیارهای پذیرش مانند جدول ادعاها را مشخص کنید.
سوال ۵: آیا CrewAI میتواند وظایف را به صورت موازی برای افزایش سرعت انجام دهد؟
بله. از عوامل موازی برای وظایف مستقل (به عنوان مثال، محققان متعدد) و سپس یک وظیفه ترکیبکننده (Synthesizer) برای ادغام نتایج استفاده کنید. ارکستراسیون هیبریدی سرعت و قابلیت اطمینان را متعادل میکند.