ایجنت در CrewAI چیست و از چه اجزایی ساخته میشود؟
در CrewAI، «ایجنت» یک شیء پایتون از کلاس Agent است که یک مدل زبانی را با شخصیت، هدف و ابزارهای مشخص احاطه میکند. سه پارامتر اول — role، goal و backstory — همگی رشتهٔ متنی هستند و CrewAI آنها را در ساخت دستورالعمل سیستم (system prompt) ایجنت ترکیب میکند؛ یعنی هر کلمهای اینجا مینویسید، مستقیماً رفتار مدل را شکل میدهد. پارامتر چهارم یعنی llm تعیین میکند مغز این شخصیت چه مدلی باشد و پارامتر tools فهرست ابزارهای قابلفراخوانی او را میدهد. به همین ترکیب سهتایی است که اصطلاح «نقشهای ایجنت در CrewAI» گفته میشود — هستهٔ شخصیت هر عضو تیم.
| پارامتر | نوع/پیشفرض | کارکرد در رفتار ایجنت |
|---|---|---|
| role | str — الزامی | شغل و تخصص ایجنت؛ بخش اصلی هویت در system prompt |
| goal | str — الزامی | هدف فردی که تصمیمگیریها را جهت میدهد |
| backstory | str — الزامی | زمینه و شخصیت؛ لحن و معیارهای کیفیت را میسازد |
| llm | Union[str, LLM, Any] — پیشفرض OPENAI_MODEL_NAME یا gpt-4 | مدل زبانی پشت ایجنت؛ هر ایجنت میتواند مدل مستقل داشته باشد |
| tools | List[BaseTool] — پیشفرض فهرست خالی | ابزارهایی مثل جستوجوی وب یا خواندن فایل |
| max_iter | int — پیشفرض ۲۰ | سقف تکرارهای فکر-عمل؛ اهرم کنترل هزینه |
| allow_delegation | bool — پیشفرض false | اجازهٔ واگذاری کار به ایجنتهای دیگر |
| max_rpm | Optional[int] — پیشفرض None | سقف درخواست در دقیقه برای جلوگیری از خطای 429 |
| verbose | bool — پیشفرض false | لاگ تفصیلی برای دیباگ |
- role را مثل عنوان شغلی دقیق بنویسید: «تحلیلگر دادهٔ بازار ایران» بهتر از «دستیار» است.
- goal باید قابلارزیابی باشد: عدد، تعداد یا معیار قبولی داخلش باشد.
- backstory لحن و خط قرمزها را تعیین میکند: «فقط از دادهٔ تأییدشده» یا «جملات کوتاه فنی».
- به هر ایجنت مدل متناسب با سنگینی نقش بدهید — همهٔ نقشها مدل گران نمیخواهند.
اگر همین حالا فقط یک چیز از این بخش یادتان بماند، این باشد: ایجنت در CrewAI یک «پرامپت زنده» است، نه یک آبجکت تزئینی. سه رشتهٔ متنی شما به همراه پرسش تسک، پشتصحنه به POST /v1/chat/completions روی مدل انتخابی تبدیل میشوند — همان endpoint ای که در بخش بعد با APX24 تست میکنیم.
تشبیه ملموس: هر ایجنت یک عضو اتاق خبر است
حالا شاید بپرسید چرا «نویسندهٔ فنی» و «بازبین» را یکی نکنیم؟ در اتاق خبر هم نویسنده و ویراستار جدایند، چون چشمِ تازه خطاها را میبیند. در سیستم چند-ایجنتی هم ایجنت بازبینی که خروجی را از صفر میخواند، خطاهایی را میگیرد که همان ایجنت نویسنده در تکرارهای خودش نمیبیند. جداسازی نقشها فقط شکوه معماری نیست؛ اثر عملی روی کیفیت دارد.
چطور CrewAI را به APX24 وصل کنیم؟ (گامبهگام)
خبر خوب این است که APX24 با فرمت استاندارد OpenAI کاملاً سازگار است — طبق مستندات رسمی آن، فقط base_url و کلید عوض میشود. پس CrewAI که خودش اتصال به ارائهدهندگان مختلف را از طریق قالب provider/model-id مدیریت میکند، بدون هیچ واسطهای به APX24 وصل میشود. سه چیز لازم دارید: کلید API، آدرس https://api.apx24.ir/v1 و شناسهٔ مدل.
- 1
کلید API بسازید
در پنل APX24 از مسیر کلیدهای API یک کلید بسازید و در متغیر محیطی نگه دارید؛ هرگز در کد هاردکد نکنید.
- 2
CrewAI را نصب کنید
طبق مستندات رسمی، CrewAI به پایتون >=3.10 و <3.14 نیاز دارد؛ نصب با uv توصیهشده است و pip هم رایج است.
- 3
اتصال را با curl تست کنید
قبل از ساخت تیم، endpoint را با یک درخواست خام آزمایش کنید تا مطمئن شوید کلید و شناسهٔ مدل درستاند.
- 4
کلاس LLM را پیکربندی کنید
در CrewAI یک شیء LLM با قالب provider/model-id بسازید و base_url را به APX24 بدهید؛ این شیء را به هر ایجنتی که میخواهید پاس بدهید.
چطور role، goal و backstory مؤثر بنویسیم؟ (مثال کامل)
کیفیت متن نقشها مستقیماً روی هزینه و کیفیت خروجی اثر میگذارد، چون این متنها در هر تکرارِ هر ایجنت دوباره و دوباره به مدل ارسال میشوند. در مثال زیر یک تیم دونفرهٔ واقعی میسازیم: پژوهشگر یافته جمع میکند و نویسنده همان یافتهها را به مقالهٔ کوتاه تبدیل میکند. به اتصال دو تسک با پارامتر context دقت کنید — این دقیقاً همان لحظهای است که «تیم» معنا پیدا میکند.
ترتیب اجرای نقشها: sequential یا hierarchical؟
پارامتر process تعیین میکند نقشها چطور با هم کار کنند. در sequential، تسکها بهترتیب فهرست اجرا میشوند — ساده، ارزان و قابلپیشبینی. در hierarchical، یک ایجنت مدیر کار را بین ایجنتها تخصیص میدهد و نتیجه را قبل از ادامه اعتبارسنجی میکند؛ طبق مستندات، این فرایند بدون manager_llm یا manager_agent اجرا نمیشود (S3).
| مورد | ترتیب اجرا | ایجنت مدیر | هزینهٔ توکن | کنترل روی جریان | مناسب برای |
|---|---|---|---|---|---|
| Process.sequential | خطی: تسک ۱ → تسک ۲ → ... | نیاز ندارد | کمتر — بدون رفتوبرگشت مدیریتی | کامل — شما ترتیب را نوشتهاید | گردشکارهای مشخص مثل پژوهش→نگارش→بازبینی |
| Process.hierarchical | پویا: مدیر تخصیص میدهد | الزامی: manager_llm یا manager_agent | بیشتر — مذاکرات مدیر اضافه میشود | بیشتر به مدل مدیر واگذار است | مسئلههای باز که تقسیم کار از قبل روشن نیست |
اشتباهات و خطاهای رایج در تعریف نقشها (و رفع آنها)
بخش عمدهٔ باگهای تیمهای چند-ایجنتی در دو دسته جمع میشوند: تصور غلط دربارهٔ «چرایی» نقشها و خطاهای سمت اتصال. اگر این چهار مورد را از قبل بشناسید، ساعتها دیباگ صرفهجویی میکنید؛ هر دو خطای زیر از پرسشهای پرتکرار تیم پشتیبانی هر سرویس API هستند.
انتخاب مدل APX24 برای هر نقش و مدیریت هزینه (به تومان)
دو معیار انتخاب مدل برای هر نقش را با هم بشناسید: «تناوب اجرا» و «سنگینی وظیفه». ایجنتی که صدها بار در روز خلاصهسازی میکند باید روی مدل اقتصادی باشد؛ ایجنتی که هفتهای چند بار گزارش استراتژیک تحلیل میکند میتواند مدل قدرتمند بخرد. قیمتهای جدول زیر مستقیماً از صفحهٔ رسمی APX24 در تاریخ 2026-11-01 استخراج شدهاند؛ ارزیابی کیفیت/سرعت تحلیل تحریریه است، نه benchmark رسمی.
جمعبندی سریع: کارتهای حافظه و مسیر بعدی
- ابزارها (Tools) — اتصال ایجنت به جستوجو، فایل و APIهای بیرونی.
- تسکهای پیشرفته — expected_output ساختاریافته با Pydantic و خروجی JSON.
- حافظه (Memory) — یادآوری گفتوگوها و موجودیتها بین اجراها.
- Flows — وقتی از همکاری آزاد تیم به گراف دقیق کاری نیاز دارید.
- پایش هزینه — داشبورد مصرف APX24 و مقایسهٔ usage_metrics هر نسخه از تیم.




