CrewAI چیست؟ آموزش ساخت سیستم چندعاملی با Python و API درواره

فرض کنید می‌خواهید سیستمی بسازید که برای معرفی یک محصول جدید، گزارش تحلیل بازار تولید کند. یک مدل زبانی می‌تواند تمام کار را در یک درخواست انجام دهد؛ اما در پروژه‌های پیچیده‌تر بهتر است مسئولیت‌ها تفکیک شوند:

• یک Agent اطلاعات اولیه را سازمان‌دهی کند.
• یک Agent بازار و رقبا را تحلیل کند.
• یک Agent نتیجه را بازبینی و به گزارش نهایی تبدیل کند.

CrewAI فریم‌ورکی برای طراحی چنین سیستم‌هایی است. در CrewAI می‌توانید چند عامل هوش مصنوعی با نقش‌ها، اهداف، ابزارها و وظایف متفاوت تعریف کنید و آن‌ها را داخل یک گردش کار هماهنگ قرار دهید.

در این مقاله یک پروژه عملی می‌سازیم که شامل سه Agent است:

1. عامل پژوهش
2. عامل تحلیل کسب‌وکار
3. عامل ویراستاری و کنترل کیفیت

این Agentها با Python و CrewAI ساخته می‌شوند و برای دسترسی به مدل هوش مصنوعی از API درواره استفاده می‌کنند.

CrewAI چیست؟

CrewAI یک فریم‌ورک متن‌باز مبتنی بر Python برای ساخت، هماهنگ‌سازی و اجرای AI Agentها و سیستم‌های چندعاملی است.

در این فریم‌ورک می‌توان برای هر Agent موارد زیر را تعریف کرد:

• نقش
• هدف
• سابقه یا شخصیت کاری
• مدل هوش مصنوعی
• ابزارهای قابل‌استفاده
• محدودیت تعداد مراحل
• امکان واگذاری کار
• حافظه
• قوانین و Guardrailها

سپس چند Agent در قالب یک Crew کنار یکدیگر قرار می‌گیرند و وظایف مشخصی را به‌صورت متوالی، سلسله‌مراتبی یا در یک Flow اجرا می‌کنند.

مستندات رسمی CrewAI آن را بستری برای طراحی Agentها، هماهنگ‌سازی Crewها و ساخت Flowهای دارای Guardrail، حافظه، دانش و Observability معرفی می‌کند.

آیا CrewAI خودش مدل هوش مصنوعی است؟

خیر.

CrewAI یک مدل زبانی مانند GPT، Claude، Gemini، DeepSeek یا Qwen نیست. این فریم‌ورک اجرای مدل‌ها، ابزارها و مراحل مختلف را هماهنگ می‌کند.

معماری کلی به این شکل است:

کاربر یا نرم‌افزار
        ↓
CrewAI
        ↓
Agentها و Taskها
        ↓
API مدل هوش مصنوعی
        ↓
مدل انتخاب‌شده
        ↓
نتیجه و اقدامات بعدی

بنابراین برای اجرای Agentهای CrewAI همچنان به یک مدل محلی یا API مدل هوش مصنوعی نیاز دارید.

سیستم چندعاملی چیست؟

در یک سیستم تک‌عاملی، یک Agent مسئول دریافت هدف، تصمیم‌گیری، استفاده از ابزارها و تولید پاسخ است.

در سیستم چندعاملی، مسئولیت میان چند Agent تقسیم می‌شود. هر Agent می‌تواند تخصص، دستور، ابزار و معیار موفقیت متفاوتی داشته باشد.

برای مثال، در یک سیستم تولید گزارش:

این تقسیم مسئولیت زمانی مفید است که مراحل کار واقعاً متفاوت باشند. اگر وظیفه فقط خلاصه‌سازی یک پاراگراف است، ساخت سه Agent معمولاً هزینه و پیچیدگی غیرضروری ایجاد می‌کند.

مفاهیم اصلی CrewAI

Agent

Agent یک واحد دارای نقش، هدف و رفتار مشخص است.

مستندات CrewAI، Agent را مانند یک عضو متخصص تیم با مهارت‌ها و مسئولیت‌های مشخص توصیف می‌کند.

نمونه:

from crewai import Agent

researcher = Agent(
    role="پژوهشگر بازار",
    goal="استخراج اطلاعات قابل‌استفاده برای تحلیل بازار",
    backstory=(
        "شما یک پژوهشگر دقیق هستید که ادعاها را "
        "از داده‌های واقعی جدا می‌کنید."
    ),
)

Task

Task وظیفه مشخصی است که یک Agent باید انجام دهد.

هر Task معمولاً شامل این موارد است:

• شرح کار
• خروجی موردانتظار
• Agent مسئول
• Context وظایف قبلی
• ابزارهای مجاز
• Guardrail
• قالب خروجی

براساس مستندات رسمی، Task یک مأموریت مشخص برای Agent است و باید اطلاعات لازم برای اجرا و خروجی موردانتظار را تعریف کند.

Crew

Crew مجموعه‌ای از Agentها و Taskها است که برای رسیدن به یک نتیجه مشترک همکاری می‌کنند.

Crew تعیین می‌کند:

• چه Agentهایی عضو تیم هستند.
• چه Taskهایی اجرا می‌شوند.
• ترتیب اجرای Taskها چیست.
• خروجی‌ها چگونه منتقل می‌شوند.
• فرایند اجرا Sequential است یا Hierarchical.

Process

Process روش هماهنگی Taskها را مشخص می‌کند.

دو الگوی رایج عبارت‌اند از:

Sequential

وظایف به‌ترتیب اجرا می‌شوند:

پژوهش
↓
تحلیل
↓
ویرایش نهایی

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

Hierarchical

یک Agent مدیر، وظایف را میان Agentهای دیگر تقسیم و نتیجه‌ها را هماهنگ می‌کند.

این روش انعطاف بیشتری دارد، اما تعداد فراخوانی مدل، هزینه و پیچیدگی کنترل را افزایش می‌دهد.

Flow

Flow برای طراحی گردش‌کارهای دارای State، شرط، رویداد و مسیرهای مختلف استفاده می‌شود.

برای مثال:

دریافت درخواست
      ↓
اعتبارسنجی
      ↓
تحلیل اولیه
      ↓
آیا داده کافی است؟
  ↙               ↘
خیر                بله
↓                   ↓
دریافت اطلاعات      تولید گزارش

Flow زمانی مفید است که فرایند فقط یک فهرست خطی از Taskها نباشد و به Branch، Retry، State یا مرحله تأیید نیاز داشته باشد.

Tool

Tool تابع یا سرویسی است که Agent می‌تواند هنگام انجام وظیفه استفاده کند.

نمونه Toolها:

• جست‌وجو در پایگاه داده
• خواندن اطلاعات محصول
• بررسی وضعیت سفارش
• فراخوانی REST API
• اجرای محاسبه
• جست‌وجو در اسناد
• ثبت درخواست در CRM

CrewAI مجموعه‌ای از ابزارهای آماده و امکان ساخت Tool اختصاصی را فراهم می‌کند.

تفاوت CrewAI با LangChain و LangGraph

انتخاب فریم‌ورک باید بر اساس معماری مسئله انجام شود، نه صرفاً محبوبیت ابزار.

اگر فرایند شما نقش‌های مشخصی مانند پژوهشگر، تحلیل‌گر و ویراستار دارد، CrewAI مدل ذهنی ساده و مناسبی ارائه می‌دهد.

اگر کنترل دقیق State، Branch، Resume و گردش‌کار طولانی اهمیت بیشتری دارد، یک Graph یا Workflow Engine ممکن است مناسب‌تر باشد.

CrewAI چه کاربردهایی دارد؟

تولید و کنترل محتوای چندمرحله‌ای

یک Agent تحقیق می‌کند، Agent دوم پیش‌نویس می‌نویسد و Agent سوم محتوا را ارزیابی می‌کند.

تحلیل بازار

Agentهای جداگانه می‌توانند اطلاعات محصول، رقبا، مخاطبان و ریسک‌ها را تحلیل کنند.

پشتیبانی مشتری

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

تحلیل اسناد

Agentها می‌توانند استخراج اطلاعات، مقایسه سند، تشخیص تناقض و تهیه گزارش را تقسیم کنند.

توسعه نرم‌افزار

عامل‌های برنامه‌نویس، بازبین کد و تولیدکننده تست می‌توانند روی یک Task مشترک کار کنند.

اتوماسیون فروش

یک Agent سرنخ را تحلیل می‌کند، Agent دیگر پیشنهاد مناسب را انتخاب می‌کند و Agent سوم پیش‌نویس پیام را می‌سازد.

چرا CrewAI را به API درواره متصل کنیم؟

با اتصال CrewAI به درواره می‌توانید:

• از یک API Key برای مدل‌های مختلف استفاده کنید.
• مدل مناسب هر Agent را انتخاب کنید.
• هزینه را به‌صورت ریالی مدیریت کنید.
• شناسه مدل را بدون تغییر معماری Crew عوض کنید.
• Agentهای سریع و اقتصادی را با Agentهای تحلیلی‌تر ترکیب کنید.
• مصرف مدل‌ها را از یک داشبورد بررسی کنید.
• از API سازگار با OpenAI استفاده کنید.

آدرس پایه API درواره:

https://api.darvareh.ir/v1

پیش‌نیازهای پروژه

برای اجرای پروژه به موارد زیر نیاز دارید:

• Python
• ابزار مدیریت پکیج uv
• یک حساب درواره
• کلید API درواره
• شناسه یک مدل متنی
• آشنایی مقدماتی با Python

نصب uv و CrewAI

در Linux و macOS می‌توانید uv را با دستور رسمی نصب کنید:

curl -LsSf https://astral.sh/uv/install.sh | sh

در Windows PowerShell:

powershell -ExecutionPolicy ByPass -c \
  "irm https://astral.sh/uv/install.ps1 | iex"

نصب CrewAI CLI:

uv tool install crewai

بررسی نصب:

crewai --version

مستندات فعلی CrewAI استفاده از uv و CLI رسمی را برای نصب و ساخت پروژه پیشنهاد می‌کند.

ساخت پروژه ساده CrewAI

پوشه پروژه را ایجاد کنید:

mkdir darvareh-crewai
cd darvareh-crewai

پروژه Python را مقداردهی کنید:

uv init

وابستگی‌ها را نصب کنید:

uv add crewai python-dotenv pydantic

ساختار ساده پروژه:

darvareh-crewai/
├── .env
├── main.py
└── pyproject.toml

تنظیم متغیرهای محیطی

فایل .env را ایجاد کنید:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL=YOUR_MODEL_ID
DARVAREH_BASE_URL=https://api.darvareh.ir/v1

شناسه مدل را از فهرست فعلی مدل‌های درواره انتخاب کنید.

کلید API نباید مستقیماً داخل کد قرار گیرد یا در Repository عمومی Commit شود.

اتصال CrewAI به API درواره

CrewAI کلاس LLM را برای تنظیم مدل ارائه می‌کند. در این کلاس می‌توان نام مدل، کلید API، آدرس پایه و تنظیمات تولید را تعیین کرد.

فایل main.py:

import os

from crewai import LLM
from dotenv import load_dotenv


load_dotenv()

api_key = os.environ["DARVAREH_API_KEY"]
model_id = os.environ["DARVAREH_MODEL"]
base_url = os.getenv(
    "DARVAREH_BASE_URL",
    "https://api.darvareh.ir/v1",
)

llm = LLM(
    model=f"openai/{model_id}",
    api_key=api_key,
    base_url=base_url,
    temperature=0.2,
    max_tokens=1500,
)

پیشوند openai/ در این مثال مسیر سازگار با OpenAI را برای لایه اتصال CrewAI مشخص می‌کند. مقدار model_id باید همان شناسه‌ای باشد که API درواره برای مدل انتخابی می‌پذیرد.

CrewAI از اتصال به Providerهای مختلف، آدرس سفارشی و پیاده‌سازی Custom LLM پشتیبانی می‌کند.

پروژه عملی: ساخت تیم تحلیل بازار

در این پروژه سه Agent می‌سازیم:

Agent پژوهشگر

اطلاعات ورودی را سازمان‌دهی می‌کند و واقعیت‌ها را از فرضیات جدا می‌سازد.

Agent تحلیل‌گر

بر اساس خروجی پژوهشگر، فرصت‌ها، ریسک‌ها، مخاطبان و پیشنهاد ورود به بازار را تحلیل می‌کند.

Agent ویراستار

گزارش را از نظر ساختار، شفافیت و ادعاهای بدون پشتوانه بررسی می‌کند.

کد کامل پروژه چندعاملی

محتوای main.py را با کد زیر جایگزین کنید:

import os

from crewai import (
    Agent,
    Crew,
    LLM,
    Process,
    Task,
)
from dotenv import load_dotenv


load_dotenv()

api_key = os.environ["DARVAREH_API_KEY"]
model_id = os.environ["DARVAREH_MODEL"]
base_url = os.getenv(
    "DARVAREH_BASE_URL",
    "https://api.darvareh.ir/v1",
)

llm = LLM(
    model=f"openai/{model_id}",
    api_key=api_key,
    base_url=base_url,
    temperature=0.2,
    max_tokens=1800,
)

researcher = Agent(
    role="پژوهشگر ارشد بازار",
    goal=(
        "تبدیل اطلاعات خام محصول و بازار به یک مجموعه "
        "واقعیت منظم، دقیق و قابل‌تحلیل"
    ),
    backstory=(
        "شما پژوهشگری دقیق هستید. میان داده، فرض، "
        "ادعا و نتیجه‌گیری تفاوت قائل می‌شوید. "
        "اگر اطلاعات کافی وجود نداشته باشد، آن را "
        "به‌صراحت اعلام می‌کنید."
    ),
    llm=llm,
    verbose=True,
    allow_delegation=False,
    max_iter=4,
)

analyst = Agent(
    role="تحلیل‌گر محصول و کسب‌وکار",
    goal=(
        "تحلیل فرصت بازار، مخاطب، مزیت رقابتی، "
        "ریسک‌ها و مسیر ورود محصول به بازار"
    ),
    backstory=(
        "شما تحلیل‌گر محصول هستید و پیشنهادها را "
        "بر اساس شواهد ارائه می‌کنید. از ساختن عدد، "
        "آمار یا نام منبع خودداری می‌کنید."
    ),
    llm=llm,
    verbose=True,
    allow_delegation=False,
    max_iter=4,
)

editor = Agent(
    role="ویراستار و ارزیاب گزارش",
    goal=(
        "تولید یک گزارش نهایی روشن، اجرایی و "
        "فاقد ادعای بدون پشتوانه"
    ),
    backstory=(
        "شما مسئول کنترل کیفیت گزارش‌های مدیریتی هستید. "
        "تناقض‌ها، تکرارها و نتیجه‌گیری‌های ضعیف را "
        "اصلاح می‌کنید و محدودیت داده‌ها را پنهان نمی‌کنید."
    ),
    llm=llm,
    verbose=True,
    allow_delegation=False,
    max_iter=3,
)

research_task = Task(
    description=(
        "اطلاعات زیر را درباره محصول بررسی و سازمان‌دهی کن.\n\n"
        "نام محصول: {product_name}\n"
        "مخاطب هدف: {target_audience}\n"
        "اطلاعات موجود:\n{known_facts}\n\n"
        "وظایف:\n"
        "1. واقعیت‌های صریح را استخراج کن.\n"
        "2. فرضیات را جداگانه مشخص کن.\n"
        "3. اطلاعات ناقص را فهرست کن.\n"
        "4. از افزودن آمار یا منبع ساختگی خودداری کن.\n"
        "5. خروجی را به زبان فارسی بنویس."
    ),
    expected_output=(
        "گزارشی شامل واقعیت‌های تأییدشده، فرضیات، "
        "اطلاعات ناقص و پرسش‌های موردنیاز برای تحلیل"
    ),
    agent=researcher,
)

analysis_task = Task(
    description=(
        "با استفاده از خروجی پژوهش، محصول را تحلیل کن.\n\n"
        "بخش‌های لازم:\n"
        "1. مسئله‌ای که محصول حل می‌کند\n"
        "2. بخش‌های اصلی مخاطبان\n"
        "3. ارزش پیشنهادی\n"
        "4. جایگزین‌ها و رقابت احتمالی\n"
        "5. فرصت‌های بازار\n"
        "6. ریسک‌های محصول و اجرا\n"
        "7. پیشنهاد MVP\n"
        "8. شاخص‌های سنجش موفقیت\n\n"
        "تحلیل باید فقط بر داده‌های ارائه‌شده و "
        "استنتاج‌های مشخص تکیه کند."
    ),
    expected_output=(
        "تحلیل کسب‌وکار ساختاریافته با فرصت‌ها، "
        "ریسک‌ها، MVP و شاخص‌های موفقیت"
    ),
    agent=analyst,
    context=[research_task],
)

editor_task = Task(
    description=(
        "خروجی پژوهش و تحلیل را به یک گزارش نهایی "
        "برای مدیر محصول تبدیل کن.\n\n"
        "قواعد:\n"
        "- گزارش به زبان فارسی روان باشد.\n"
        "- ادعاهای بدون پشتوانه حذف یا مشخص شوند.\n"
        "- محدودیت اطلاعات در بخش جداگانه بیاید.\n"
        "- پیشنهادها قابل‌اجرا و اولویت‌بندی‌شده باشند.\n"
        "- گزارش حداکثر ۱۲۰۰ کلمه باشد.\n\n"
        "ساختار نهایی:\n"
        "1. خلاصه مدیریتی\n"
        "2. مسئله و مخاطب\n"
        "3. ارزش پیشنهادی\n"
        "4. فرصت‌ها\n"
        "5. ریسک‌ها\n"
        "6. MVP پیشنهادی\n"
        "7. شاخص‌های موفقیت\n"
        "8. گام‌های بعدی\n"
        "9. محدودیت داده‌ها"
    ),
    expected_output=(
        "یک گزارش مدیریتی فارسی، دقیق و آماده ارائه"
    ),
    agent=editor,
    context=[
        research_task,
        analysis_task,
    ],
)

market_crew = Crew(
    agents=[
        researcher,
        analyst,
        editor,
    ],
    tasks=[
        research_task,
        analysis_task,
        editor_task,
    ],
    process=Process.sequential,
    verbose=True,
)

result = market_crew.kickoff(
    inputs={
        "product_name": (
            "دستیار هوشمند پشتیبانی مشتری"
        ),
        "target_audience": (
            "فروشگاه‌های اینترنتی و شرکت‌های SaaS ایرانی"
        ),
        "known_facts": """
- محصول به پیام‌های مشتریان پاسخ پیشنهادی می‌دهد.
- به پایگاه دانش شرکت متصل می‌شود.
- در صورت اطمینان پایین، درخواست را به اپراتور منتقل می‌کند.
- نسخه ابری و نصب اختصاصی سازمانی در نظر گرفته شده است.
- محصول هنوز مشتری پولی ندارد.
- تیم توسعه چهار نفره است.
- هدف نسخه اولیه، کاهش زمان پاسخ‌گویی به تیکت‌ها است.
""".strip(),
    }
)

print("\n" + "=" * 60)
print("گزارش نهایی")
print("=" * 60)
print(result.raw)

اجرای Crew

دستور زیر را اجرا کنید:

uv run python main.py

CrewAI Taskها را به‌ترتیب زیر اجرا می‌کند:

Research Task
      ↓
Research Output
      ↓
Analysis Task
      ↓
Analysis Output
      ↓
Editor Task
      ↓
Final Report

در پایان، گزارش نهایی از result.raw خوانده و چاپ می‌شود.

Context میان Taskها چگونه کار می‌کند؟

در این قسمت:

context=[research_task]

خروجی Task پژوهش در اختیار Task تحلیل قرار می‌گیرد.

برای Task ویراستاری نیز دو خروجی قبلی ارسال می‌شوند:

context=[
    research_task,
    analysis_task,
]

این ساختار کمک می‌کند هر Agent فقط اطلاعات مرتبط با مسئولیت خود را دریافت کند.

بااین‌حال، Context هر مرحله باعث افزایش ورودی مدل و هزینه می‌شود. بهتر است خروجی Taskها کوتاه، ساختاریافته و مرتبط باقی بماند.

ساخت Tool اختصاصی در CrewAI

اکنون یک Tool ساده می‌سازیم که اطلاعات داخلی محصول را برمی‌گرداند.

from crewai.tools import tool


PRODUCTS = {
    "support-assistant": {
        "name": "دستیار پشتیبانی",
        "plan": "enterprise",
        "channels": [
            "web",
            "ticket",
            "telegram",
        ],
        "status": "pilot",
    }
}


@tool("get_product_information")
def get_product_information(
    product_id: str,
) -> str:
    """
    اطلاعات محصول را با شناسه آن دریافت می‌کند.
    """
    product = PRODUCTS.get(product_id)

    if product is None:
        return "محصول پیدا نشد."

    return str(product)

سپس Tool را به Agent بدهید:

researcher = Agent(
    role="پژوهشگر ارشد بازار",
    goal="تحلیل اطلاعات محصول",
    backstory="پژوهشگر دقیق محصول",
    llm=llm,
    tools=[get_product_information],
    verbose=True,
)

Agent اکنون می‌تواند در صورت نیاز، Tool را با شناسه محصول فراخوانی کند.

اتصال CrewAI به REST API واقعی

Tool می‌تواند به‌جای داده ثابت، یک سرویس داخلی را فراخوانی کند:

import os

import httpx
from crewai.tools import tool


@tool("get_order_status")
def get_order_status(order_id: str) -> str:
    """
    وضعیت سفارش را از API داخلی دریافت می‌کند.
    """
    base_url = os.environ["STORE_API_URL"]
    service_token = os.environ["STORE_SERVICE_TOKEN"]

    response = httpx.get(
        f"{base_url}/orders/{order_id}",
        headers={
            "Authorization": (
                f"Bearer {service_token}"
            ),
        },
        timeout=10,
    )

    response.raise_for_status()

    data = response.json()

    return (
        f"شماره سفارش: {data['id']}\n"
        f"وضعیت: {data['status']}\n"
        f"کد پیگیری: {data.get('tracking_code')}"
    )

در نسخه عملی باید بررسی شود کاربر مجاز به مشاهده همان سفارش است. مدل نباید بتواند صرفاً با حدس‌زدن شماره سفارش، اطلاعات مشتریان دیگر را دریافت کند.

خروجی ساختاریافته با Pydantic

برای استفاده نرم‌افزاری از نتیجه، متن Markdown همیشه بهترین گزینه نیست. می‌توان خروجی Task را با مدل Pydantic اعتبارسنجی کرد.

from pydantic import BaseModel, Field


class MarketReport(BaseModel):
    executive_summary: str

    opportunities: list[str] = Field(
        min_length=1,
    )

    risks: list[str] = Field(
        min_length=1,
    )

    mvp_features: list[str] = Field(
        min_length=1,
    )

    success_metrics: list[str] = Field(
        min_length=1,
    )

    next_steps: list[str] = Field(
        min_length=1,
    )

سپس آن را به Task نهایی اضافه کنید:

editor_task = Task(
    description="گزارش نهایی را تولید کن.",
    expected_output=(
        "گزارش ساختاریافته تحلیل بازار"
    ),
    agent=editor,
    context=[
        research_task,
        analysis_task,
    ],
    output_pydantic=MarketReport,
)

پس از اجرا می‌توانید خروجی ساختاریافته را دریافت کنید:

result = market_crew.kickoff(
    inputs={
        "product_name": "محصول نمونه",
        "target_audience": "شرکت‌های SaaS",
        "known_facts": "اطلاعات محصول",
    }
)

report = result.pydantic

if report:
    print(report.model_dump_json(indent=2))

این روش برای اتصال نتیجه CrewAI به API، پایگاه داده یا رابط مدیریتی مناسب‌تر است.

استفاده از مدل متفاوت برای هر Agent

همه Agentها لازم نیست از یک مدل استفاده کنند.

برای مثال:

• پژوهشگر از یک مدل سریع و اقتصادی استفاده کند.
• تحلیل‌گر از مدل قوی‌تر استفاده کند.
• ویراستار دوباره از مدل کم‌هزینه‌تر استفاده کند.

fast_llm = LLM(
    model=f"openai/{os.environ['FAST_MODEL_ID']}",
    api_key=api_key,
    base_url=base_url,
    temperature=0.1,
)

reasoning_llm = LLM(
    model=f"openai/{os.environ['REASONING_MODEL_ID']}",
    api_key=api_key,
    base_url=base_url,
    temperature=0.2,
)

اتصال Agentها:

researcher = Agent(
    role="پژوهشگر",
    goal="استخراج اطلاعات",
    backstory="پژوهشگر دقیق",
    llm=fast_llm,
)

analyst = Agent(
    role="تحلیل‌گر",
    goal="تحلیل عمیق",
    backstory="تحلیل‌گر ارشد",
    llm=reasoning_llm,
)

editor = Agent(
    role="ویراستار",
    goal="کنترل کیفیت",
    backstory="ویراستار حرفه‌ای",
    llm=fast_llm,
)

این معماری می‌تواند ترکیب بهتری از کیفیت، سرعت و هزینه ایجاد کند.

Process ترتیبی یا سلسله‌مراتبی؟

فرایند ترتیبی

process=Process.sequential

مزایا:

• رفتار قابل‌پیش‌بینی‌تر
• Debug ساده‌تر
• هزینه قابل‌کنترل‌تر
• ترتیب روشن Taskها

فرایند سلسله‌مراتبی

در این روش یک Manager Agent تصمیم می‌گیرد کارها چگونه تقسیم شوند.

مزایا:

• انعطاف بیشتر
• امکان واگذاری پویا
• مناسب‌تر برای اهداف باز

محدودیت‌ها:

• فراخوانی بیشتر مدل
• هزینه بالاتر
• رفتار کمتر قابل‌پیش‌بینی
• احتمال ایجاد Loop
• Debug دشوارتر

برای نسخه اول یک محصول، معمولاً بهتر است با Process ترتیبی شروع کنید.

چه زمانی چند Agent انتخاب مناسبی نیست؟

استفاده از چند Agent همیشه کیفیت را افزایش نمی‌دهد.

CrewAI ممکن است انتخاب نامناسبی باشد اگر:

• مسئله با یک درخواست ساده حل می‌شود.
• مراحل کار تفاوت تخصصی ندارند.
• Latency بسیار مهم است.
• هزینه باید حداقل باشد.
• خروجی کاملاً قطعی نیاز دارید.
• گردش‌کار با چند تابع معمولی قابل‌پیاده‌سازی است.

برای مثال، طبقه‌بندی یک تیکت در یکی از پنج دسته معمولاً به سه Agent نیاز ندارد. یک درخواست دارای Structured Output احتمالاً سریع‌تر، ارزان‌تر و قابل‌ارزیابی‌تر است.

چگونه تصمیم بگیریم یک Agent یا چند Agent؟

پیش از انتخاب معماری، این پرسش‌ها را پاسخ دهید:

1. آیا مسئله واقعاً چند نقش تخصصی دارد؟
2. آیا خروجی یک مرحله ورودی مرحله دیگری است؟
3. آیا هر مرحله معیار موفقیت متفاوتی دارد؟
4. آیا یک مدل واحد با Prompt مناسب کافی نیست؟
5. آیا افزایش هزینه و زمان پاسخ قابل‌قبول است؟
6. آیا می‌توان مراحل را مستقل ارزیابی کرد؟
7. آیا Agentها به ابزارهای متفاوت نیاز دارند؟

اگر بیشتر پاسخ‌ها منفی هستند، معماری تک‌عاملی یا Workflow ساده احتمالاً مناسب‌تر است.

مدیریت هزینه CrewAI

در سیستم چندعاملی، یک درخواست کاربر ممکن است چند فراخوانی مدل ایجاد کند.

اگر سه Agent هرکدام دو بار مدل را فراخوانی کنند، یک اجرای Crew می‌تواند حداقل شش درخواست API داشته باشد. در حالت Delegation، Retry یا ابزارهای چندمرحله‌ای این تعداد بیشتر می‌شود.

برای کنترل هزینه:

• تعداد Agentها را محدود کنید.
• max_iter تعیین کنید.
• Delegation را فقط در صورت نیاز فعال کنید.
• خروجی هر Task را کوتاه نگه دارید.
• مدل را متناسب با وظیفه انتخاب کنید.
• History غیرضروری را ارسال نکنید.
• مصرف هر Agent را جداگانه ثبت کنید.
• نتیجه‌های ثابت را Cache کنید.
• پیش از اجرا بودجه Token تعریف کنید.
• روی Dataset واقعی ارزیابی انجام دهید.

ارزیابی سیستم چندعاملی

فقط کیفیت متن نهایی را بررسی نکنید. هر مرحله باید معیار مستقل داشته باشد.

برای پروژه تحلیل بازار می‌توان این معیارها را تعریف کرد:

Agent پژوهش

• چند واقعیت به‌درستی استخراج شده است؟
• چند ادعای ساختگی تولید شده است؟
• آیا اطلاعات ناقص شناسایی شده‌اند؟

Agent تحلیل

• آیا نتیجه‌ها از اطلاعات ورودی قابل استنتاج‌اند؟
• آیا فرصت و ریسک از یکدیگر تفکیک شده‌اند؟
• آیا پیشنهاد MVP قابل‌اجرا است؟

Agent ویراستار

• آیا تناقض‌ها حذف شده‌اند؟
• آیا محدودیت داده‌ها مشخص است؟
• آیا گزارش از حداکثر طول عبور نکرده است؟
• آیا ساختار خروجی رعایت شده است؟

کل Crew

• زمان کل اجرا
• هزینه کل
• تعداد فراخوانی مدل
• تعداد Retry
• نرخ خروجی معتبر
• میزان رضایت ارزیاب انسانی

کنترل خطا و Retry

خطاهای رایج در CrewAI عبارت‌اند از:

• Timeout مدل
• Rate Limit
• شناسه مدل نامعتبر
• خطای Tool
• خروجی ناسازگار با Schema
• پایان‌نیافتن Agent Loop
• Context بیش از حد طولانی
• پاسخ خالی

در محیط Production بهتر است:

• برای Toolها Timeout تعیین کنید.
• Retry محدود با Backoff داشته باشید.
• تعداد مراحل Agent محدود شود.
• خطاهای موقت و دائمی تفکیک شوند.
• Task ناموفق قابل‌اجرای مجدد باشد.
• اجرای هر Crew یک شناسه یکتا داشته باشد.
• نتیجه مراحل قبلی ذخیره شود.
• درخواست‌های تکراری Idempotent باشند.

Human-in-the-Loop

برای عملیات حساس، Agent نباید مستقیماً اقدام نهایی را اجرا کند.

الگوی مناسب:

Agent پیشنهاد می‌دهد
        ↓
Policy بررسی می‌کند
        ↓
تأیید انسانی دریافت می‌شود
        ↓
Tool عملیات را اجرا می‌کند
        ↓
نتیجه ثبت می‌شود

عملیاتی مانند بازپرداخت، لغو قرارداد، حذف اطلاعات، ارسال پیام رسمی یا تغییر دسترسی بهتر است مرحله تأیید داشته باشند.

Guardrail چیست؟

Guardrail قانونی است که خروجی Task را پیش از پذیرش بررسی می‌کند.

Guardrail می‌تواند کنترل کند:

• خروجی خالی نباشد.
• فیلدهای اجباری وجود داشته باشند.
• طول پاسخ از حد مشخص بیشتر نباشد.
• ادعای بدون منبع وجود نداشته باشد.
• مقدار عددی در بازه مجاز باشد.
• قالب JSON معتبر باشد.

مستندات معماری Production در CrewAI نیز استفاده از Task Guardrail برای اعتبارسنجی خروجی پیش از پذیرش را توصیه می‌کند.

ذخیره لاگ و Observability

برای هر اجرای Crew این اطلاعات را ثبت کنید:

• شناسه اجرا
• نام Crew
• نسخه Prompt
• نسخه Agent
• شناسه مدل هر Agent
• زمان شروع و پایان
• خروجی هر Task
• Tool Callها
• خطاها و Retryها
• مصرف Token
• هزینه
• نتیجه Guardrail
• تأیید یا رد انسانی

بدون Observability، تشخیص اینکه کدام Agent باعث کاهش کیفیت یا افزایش هزینه شده دشوار خواهد بود.

CrewAI یک Event System نیز برای مشاهده و واکنش به رویدادهای اجرای Crew ارائه می‌کند.

تبدیل CrewAI به API

برای استفاده از Crew داخل وب‌سایت یا نرم‌افزار می‌توانید آن را پشت FastAPI قرار دهید.

نمونه ساده:

from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class MarketRequest(BaseModel):
    product_name: str
    target_audience: str
    known_facts: str


@app.post("/market-report")
def create_market_report(
    request: MarketRequest,
):
    result = market_crew.kickoff(
        inputs={
            "product_name": request.product_name,
            "target_audience": request.target_audience,
            "known_facts": request.known_facts,
        }
    )

    return {
        "report": result.raw,
    }

اجرای Agent ممکن است طولانی باشد. برای کارهای سنگین بهتر است:

1. درخواست ثبت شود.
2. شناسه Job برگردد.
3. Worker اجرای Crew را انجام دهد.
4. وضعیت در پایگاه داده ذخیره شود.
5. Client وضعیت Job را بررسی کند یا Webhook دریافت کند.

اشتباهات رایج هنگام استفاده از CrewAI

ساخت Agentهای متعدد بدون مسئولیت متفاوت

نام‌های متفاوت به‌تنهایی Agentها را تخصصی نمی‌کنند. هر Agent باید هدف، داده، ابزار یا معیار موفقیت متفاوتی داشته باشد.

استفاده از Crew برای وظیفه ساده

چند Agent هزینه و Latency را افزایش می‌دهند. ابتدا نسخه تک‌درخواستی را آزمایش کنید.

فعال‌کردن Delegation بدون محدودیت

واگذاری نامحدود می‌تواند به Loop و فراخوانی‌های پیش‌بینی‌نشده منجر شود.

دادن تمام ابزارها به تمام Agentها

هر Agent فقط باید به ابزارهای موردنیاز وظیفه خود دسترسی داشته باشد.

تعریف خروجی مبهم

عبارت «یک گزارش خوب بنویس» قابل‌اندازه‌گیری نیست. ساختار، طول، بخش‌ها و معیار پذیرش را مشخص کنید.

نداشتن خروجی ساختاریافته

اگر نرم‌افزار باید از نتیجه استفاده کند، خروجی آزاد Markdown ممکن است کافی نباشد. از Pydantic یا Schema استفاده کنید.

اعتماد کامل به Agent

Agent ممکن است اشتباه کند، Tool نامناسب انتخاب کند یا نتیجه نادرست تولید کند. قوانین قطعی را در کد و Policy نگه دارید.

استفاده از یک مدل برای همه نقش‌ها

مدل اقتصادی ممکن است برای استخراج کافی باشد، اما تحلیل پیچیده به مدل دیگری نیاز داشته باشد.

نداشتن Dataset ارزیابی

بدون نمونه‌های ثابت نمی‌توان اثر تغییر Prompt، مدل یا تعداد Agentها را اندازه‌گیری کرد.

چک‌لیست CrewAI برای محیط Production

• مسئله واقعاً به چند Agent نیاز دارد.
• نقش هر Agent مشخص و غیرتکراری است.
• تعداد Agentها حداقل نگه داشته شده است.
• برای هر Agent مدل مناسب انتخاب شده است.
• max_iter محدود شده است.
• Toolها ورودی معتبر و Timeout دارند.
• عملیات حساس نیازمند تأیید هستند.
• خروجی Taskها Schema یا Guardrail دارند.
• مصرف و هزینه هر Agent ثبت می‌شود.
• اجرای Crew دارای Request ID است.
• خطا و Retry کنترل شده است.
• Promptها نسخه‌بندی می‌شوند.
• مدل‌ها روی داده واقعی فارسی ارزیابی شده‌اند.
• نتیجه نهایی پیش از اقدام قطعی اعتبارسنجی می‌شود.
• کلید API فقط در Backend نگهداری می‌شود.

پرسش‌های متداول

CrewAI چیست؟

CrewAI یک فریم‌ورک Python برای ساخت و هماهنگ‌سازی AI Agentها، Taskها، Crewها و Flowهای چندمرحله‌ای است.

آیا CrewAI متن‌باز است؟

بله. کد اصلی CrewAI به‌صورت عمومی توسعه داده می‌شود و مخزن رسمی آن در GitHub در دسترس است.

آیا CrewAI رایگان است؟

فریم‌ورک متن‌باز CrewAI قابل‌استفاده است؛ اما اجرای مدل‌های هوش مصنوعی، سرویس‌های جانبی یا امکانات پلتفرم تجاری ممکن است هزینه داشته باشد.

تفاوت Agent و Task چیست؟

Agent عضو متخصص تیم است، درحالی‌که Task مأموریت مشخصی است که به Agent واگذار می‌شود.

تفاوت Crew و Flow چیست؟

Crew مجموعه‌ای از Agentها و Taskها برای همکاری روی یک هدف است. Flow گردش‌کار دارای State، رویداد، شرط و مسیرهای اجرایی مختلف را مدیریت می‌کند.

آیا هر پروژه هوش مصنوعی به چند Agent نیاز دارد؟

خیر. بسیاری از وظایف با یک درخواست مدل، Structured Output یا یک Workflow ساده بهتر اجرا می‌شوند.

آیا می‌توان CrewAI را به مدل‌های مختلف متصل کرد؟

بله. CrewAI از Providerهای مختلف، APIهای سازگار و Custom LLM پشتیبانی می‌کند.

آیا CrewAI با API درواره کار می‌کند؟

با تنظیم base_url روی آدرس API درواره و استفاده از کلید و شناسه مدل مناسب، می‌توان CrewAI را به مسیر OpenAI-compatible درواره متصل کرد:

https://api.darvareh.ir/v1

آیا می‌توان برای هر Agent مدل متفاوتی انتخاب کرد؟

بله. هر Agent می‌تواند LLM مستقل داشته باشد. این قابلیت برای بهینه‌سازی کیفیت، سرعت و هزینه مفید است.

آیا CrewAI برای فارسی مناسب است؟

کیفیت فارسی بیشتر به مدل انتخاب‌شده، Prompt، داده ورودی و ارزیابی شما بستگی دارد. بهتر است چند مدل را روی نمونه‌های واقعی فارسی مقایسه کنید.

آیا CrewAI برای محیط Production مناسب است؟

CrewAI می‌تواند در محصول واقعی استفاده شود، اما باید محدودیت مراحل، Guardrail، مدیریت خطا، Observability، کنترل Toolها، هزینه و ارزیابی به معماری اضافه شوند.

جمع‌بندی

CrewAI یک فریم‌ورک کاربردی برای ساخت تیم‌هایی از Agentهای تخصصی است. در این معماری می‌توان مسئله‌ای پیچیده را میان چند نقش تقسیم کرد و نتیجه هر مرحله را به مرحله بعدی انتقال داد.

در این آموزش یاد گرفتیم چگونه:

1. Agent، Task، Crew، Process و Flow را تعریف کنیم.
2. CrewAI را با Python نصب کنیم.
3. کلاس LLM را برای API درواره تنظیم کنیم.
4. یک تیم سه‌عاملی پژوهش، تحلیل و ویراستاری بسازیم.
5. Context را میان Taskها منتقل کنیم.
6. Tool اختصاصی تعریف کنیم.
7. خروجی را با Pydantic ساختاریافته کنیم.
8. برای هر Agent مدل متفاوت انتخاب کنیم.
9. هزینه و تعداد فراخوانی‌ها را کنترل کنیم.
10. سیستم را برای API و محیط Production آماده کنیم.

پیش از ساخت چند Agent، ابتدا بررسی کنید آیا مسئله با یک درخواست مدل یا Workflow ساده حل می‌شود. اگر مراحل واقعاً نقش‌ها، ابزارها و معیارهای متفاوت دارند، CrewAI می‌تواند ساختار مناسبی برای هماهنگ‌کردن آن‌ها فراهم کند.

برای دریافت کلید API، مشاهده مدل‌های فعلی و اتصال CrewAI به مدل‌های مختلف می‌توانید از مستندات API درواره شروع کنید.

مقالات مرتبط

• AI Agent چیست؟ راهنمای کامل عامل هوش مصنوعی
• آموزش ساخت AI Agent با Python و FastAPI
• هماهنگ‌سازی AI Agentها چیست؟
• مقایسه SDKهای ساخت AI Agent
• آموزش LangGraph و ساخت Agent دارای State
• LangChain چیست؟
• Tool Calling چیست؟
• API سازگار با OpenAI چیست؟

منابع

• مستندات رسمی CrewAI
• نصب CrewAI
• Agentها در CrewAI
• Taskها در CrewAI
• تنظیم LLM در CrewAI
• اتصال CrewAI به مدل‌های مختلف
• Custom LLM در CrewAI
• مخزن رسمی CrewAI در GitHub
• مستندات API درواره

این مقاله صرفاً با هدف آموزش و اطلاع‌رسانی تهیه شده است. پیش از استفاده عملی، مستندات رسمی سرویس‌ها و صفحه سلب مسئولیت را مطالعه کنید.