گلوگاه واقعی ساخت ایجنت هوش مصنوعی (AI Agent) کدنویسی نیست؛ تصمیمات معماریِ پیش از کدنویسی است. مرز بین «مسیر ثابت» (ورکفلو) و «مسیر پویا» (ایجنت) مهم‌ترین انتخابی است که یک تیم انجام میدهد، و اکثر تیم‌ها آن را اشتباه می‌زنند — نه در کد، بلکه روی کاغذ.
ایجنت هوش مصنوعی چیست و چه فرقی با چت‌بات و ورکفلو دارد؟#
ایجنت هوش مصنوعی ترکیب سه جزء است: مدل زبانی، حلقهی تصمیم و دسترسی به ابزار. چت‌بات فقط متن تولید میکند. ورکفلو مسیر از پیش‌نوشته‌شده را اجرا میکند و مدل در هر گام تنها محتوا میسازد. ایجنت اما خودش در هر گام تصمیم می‌گیرد کدام ابزار، با چه پارامترهایی و به چه ترتیبی اجرا شوند.
تصویر عملی این تفاوت: یک ورکفلو «جستجوی وب ← خلاصه‌سازی ← ارسال ایمیل» دارد. سه گام ثابت، سه ابزار مشخص، ترتیب از پیش تعیین‌شده. مدل فقط در هر گام محتوا تولید میکند.
ایجنت همان سه ابزار را دارد، اما خودش تصمیم می‌گیرد آیا به جستجو نیاز هست یا خیر، آیا خلاصه‌سازی لازم است یا نه، و آیا اصلاً ایمیل بفرستد. ترتیب اجرا وابسته به نتیجهی گام قبلی است.
اصطلاح «agentic» بدون تعریف فنی، برچسب بازاریابی است نه معماری. اگر محصولی فقط یک prompt با چند ابزار دارد و حلقهی تصمیم ندارد، ایجنت نیست. این مرز را قبل از انتخاب فریمورک مشخص کنید.
معماری ایجنت: اجزای حلقهی اجرا و نقش هرکدام#
حلقهی اجرا (agent loop) چهار جزء اصلی دارد: موتور استدلال، حافظه، مجموعه ابزارها و لایهی کنترل. حذف یا ضعف هرکدام از این چهار جزء، ایجنت را به یک چت‌بات با ابزار تبدیل میکند؛ چیزی که ادعای ایجنت بودن دارد اما رفتار ایجنت ندارد.
موتور استدلال همان مدل زبانی است که در هر گام تصمیم بعدی را می‌گیرد. حافظه دو لایه دارد: context window به‌عنوان حافظهی کوتاه‌مدت و پایگاه داده‌ی برداری (vector database) به‌عنوان حافظهی بلندمدت. ابزارها توابع قابل فراخوانی با schema مشخص‌اند. لایهی کنترل سقف تکرار، محدودیتهای ایمنی (guardrails) و انسان در حلقه (human-in-the-loop) را مدیریت میکند.
الگوی ReAct — Reasoning و Acting در یک حلقه#
ReAct (Reasoning + Acting) الگویی است که در آن مدل فکر میکند، ابزار صدا میزند، نتیجه را می‌بیند و دوباره فکر میکند. Andrew Ng در الگوهای طراحی ایجنت، ReAct را به‌عنوان نمونه‌ی عملی الگوی Tool Use معرفی میکند.
Chain of Thought (CoT) فقط استدلال گام‌به‌گام در متن است بدون اقدام. ReAct استدلال را با اقدام ترکیب میکند. CoT یک تکنیک prompt است؛ ReAct یک الگوی معماری حلقهی اجراست. تفاوت این دو، تفاوت یک دستورالعمل نوشتاری با یک سیستم اجرایی است.
شبه‌کد ساده‌ی حلقهی اجرا:
while not done and steps < max_iterations:
thought = llm.reason(context, tools)
if thought.action == "finish": done = true
else:
result = execute(thought.tool, thought.params)
context.append(result)
الگوی Reflexion — اجرای مجدد با بازخورد#
Reflexion الگویی است که در آن ایجنت پس از شکست در یک گام، بازخورد را تحلیل میکند و دوباره تلاش میکند. تفاوتش با ReAct در این است که ReAct در همان حلقه ادامه میدهد، اما Reflexion یک لایهی ارزیابی جداگانه دارد که خروجی را قبل از پذیرش بررسی میکند.
این الگو در پروژه‌های عملی معمولاً با یک مدل کوچک‌تر به‌عنوان evaluator پیاده میشود. هزینه‌ی اضافه دارد، اما برای تسک‌هایی که خروجی‌شان باید از نظر صحت بررسی شود، ارزشش را دارد. اگر تسک شما خطای خروجی‌اش فاحش نیست، این لایه اضافهکاری است.
مشکل context window در حلقه‌های طولانی و راه‌حل خلاصه‌سازی ترحیمی#
هر گام حلقه، نتیجهی ابزار را به context اضافه میکند. بعد از چند گام، context window پر میشود. راه‌حل رایج: خلاصه‌سازی ترحیمی (progressive summarization) — یعنی context قدیمی خلاصه شود و context جدید کامل بماند.
این کار یک تصمیم معماری است، نه یک تکنیک پیاده‌سازی. اگر هر گام 2000 توکن اضافه میکند و context window شما 8K است، بعد از سه تا چهار گام به مرز می‌رسید. قبل از کدنویسی این عدد را محاسبه کنید. اگر نمی‌کنید، بعداً با باگ‌های مرموزِ «ایجنت جواب عجیب میدهد» روبه‌رو می‌شوید.
چگونه یک ایجنت هوش مصنوعی بسازم؟ گام‌های عملی#
ساخت ایجنت پنج گام اصلی دارد: تعریف مرز تسک، انتخاب مدل و ابزارها، پیاده‌سازی حلقهی اجرا با سقف تکرار، افزودن لاگ و guardrails، و تست با سناریوهای شکست. بدون سقف تکرار، ایجنت در حلقه گیر میکند و هزینه‌ی اجرا بی‌سقف میشود.
- مرز تسک را مشخص کنید — چه کاری ایجنت باید انجام دهد و چه کاری نه. این مرز را مکتوب کنید.
- ابزارها را با schema دقیق تعریف کنید — فراخوانی تابع (function calling) با پارامترهای type-checked. هر ابزار باید توضیح داشته باشد که مدل بفهمد کی آن را صدا بزند.
- حلقهی اجرا را پیاده کنید — max iterations را از ابتدا تنظیم کنید. LangChain به‌صورت پیش‌فرض 15 را قرار میدهد؛ در عمل بسته به پیچیدگی تسک اعداد 5 تا 15 رایج‌اند.
- لاگ سطح tool call و fallback پیام‌رسان اضافه کنید. بدون لاگ، شکست خاموش غیرقابل‌عیب‌یابی است.
- با سناریوهای شکست تست کنید — ابزار اشتباه، ورودی ناکافی، حلقهی بیپایان.
از prompt تا ایجنت — چه زمانی یک prompt خوب کافی است و چه زمانی به حلقه نیاز دارید#
اگر تسک شما یک فراخوانی API با یک prompt دقیق حل میشود، ایجنت لازم نیست. حلقهی اجرا فقط زمانی وارد میشود که ترتیب ابزارها وابسته به نتیجهی گام قبلی باشد.
سیگنال ساده: اگر می‌توانید مسیر اجرا را روی کاغذ بنویسید (گام 1، گام 2، گام 3)، ورکفلو کافی است. اگر نمی‌توانید و بستگی به خروجی گام قبلی دارد، ایجنت لازم است. این آزمون کاغذی، بیش از هر فیلتر دیگری، از over-engineering جلوگیری میکند.
الگوی شکست خاموش (silent failure) و چگونگی تشخیص آن#
شکست خاموش یعنی ایجنت ابزار اشتباه را با پارامتر اشتباه صدا میزند، خروجی نادرست می‌گیرد، و بدون هیچ خطای آشکاری ادامه میدهد. کاربر فقط نتیجهی نهایی غلط را می‌بیند.
راه تشخیص: لاگ هر tool call با نام ابزار، پارامترها و خروجی. بدون این لاگ، عیب‌یابی ایجنت عملاً غیرممکن است. این الگو در مستندات رسمی فریمورک‌ها کمتر برجسته شده، اما در پروژه‌های عملی پرتکرارترین منبع debug است. سؤال «چرا ایجنت جواب غلط داد؟» بدون لاگ tool call، بی‌پاسخ می‌ماند.
مقایسه فریمورک‌های ایجنت: LangChain، CrewAI، AutoGen و LangGraph#
LangChain برای ایجنت تک‌ابزاری با اکوسیستم گسترده ابزار مناسب است، AutoGen برای گفتگوی چندایجنتی (multi-agent) طراحی شده، CrewAI برای تسکهای نقش‌محور و LangGraph برای گراف‌های اجرای قابل‌کنترل. انتخاب فریمورک قبل از تعریف معماری حلقه، رایج‌ترین و پرهزینه‌ترین اشتباه در شروع پروژه است.
| فریمورک | مدل اجرای حلقه | پشتیبانی multi-agent | منحنی یادگیری |
|---|---|---|---|
| LangChain | حلقهی خطی با ابزار | محدود (LangGraph جدا) | متوسط |
| AutoGen | گفتگوی چندایجنتی | اصلی | سربال |
| LangGraph | گراف اجرای قابل‌کنترل | میانجی | سربال |
| CrewAI | نقش‌محور با تسک | اصلی | آسان |
| LlamaIndex | تمرکز بر RAG و بازیابی | محدود | متوسط |
کدام فریمورک برای کدام نوع پروژه مناسب است؟#
ایجنت تک‌ابزاری با چند ابزار ساده: LangChain یا حتی کدنویسی مستقیم روی API. سیستم چندایجنتی با نقشهای مشخص: AutoGen یا CrewAI. حلقهی اجرای پیچیده با شرط و انشعاب: LangGraph.
اگر فقط بازیابی‌محور (RAG) می‌خواهید و ایجنت عمومی لازم ندارید، LlamaIndex مناسب‌تر است. LangChain را به‌عنوان فریمورک ایجنت عمومی در نظر بگیرید، نه به‌عنوان فریمورک RAG. این تفکیک، از انتخاب‌های اشتباهِ رایج جلوگیری میکند.
اشتباه رایج — انتخاب فریمورک قبل از تعریف معماری حلقه#
این اشتباه در پروژه‌های عملی بسیار رایج است: توسعه‌دهنده اول LangChain نصب میکند، بعد فکر میکند ایجنتش چه حلقه‌ای دارد. نتیجه: وابستگی به انتزاعات فریمورک و از دست دادن کنترل روی رفتار واقعی ایجنت.
ترتیب درست: معماری حلقه را روی کاغذ بنویسید، سقف تکرار را تعیین کنید، ابزارها را مشخص کنید. بعد ببینید کدام فریمورک این معماری را راحت‌تر پیاده میکند. گاهی کدنویسی مستقیم ساده‌تر از هر فریمورکی است — و در پروژه‌های تک‌ابزاری، تقریباً همیشه.
هزینه‌ی اجرای ایجنت: مدل مصرف توکن و بهینه‌سازی#
هر گام reasoning در حلقهی اجرا یک فراخوانی API است. ایجنتی که 10 بار ابزار صدا بزند، تقریباً 10 برابر یک پاسخ چت‌باتی هزینه دارد (در عمل بیشتر، چون context در هر گام انباشته میشود). سقف تکرار و انتخاب مدل سبک‌تر برای گام‌های ساده، مهم‌ترین اهرم‌های کاهش هزینه‌اند.
فرمول ساده: هزینه ≈ تعداد گام حلقه × میانگین توکن ورودی و خروجی × نرخ مدل. این عدد را قبل از شروع پروژه محاسبه کنید. اگر خروجی‌اش غیرواقعی است، معماری را بازنگری کنید — نه مدل را.
استراتژی مدل‌های چندسطحی — مدل سبک برای گام‌های ساده، مدل قوی برای تصمیم‌های بحرانی#
در حلقهی اجرا، همه گام‌ها به یک مدل قوی نیاز ندارند. گام‌های ساده مثل «آیا این ابزار لازم است؟» را با مدل سبک‌تر و ارزان‌تر انجام دهید. فقط تصمیم‌های بحرانی را به مدل گران‌تر بسپارید.
این الگو در پروژه‌های عملی هزینه را به‌طور محسوسی کاهش میدهد. شرطش این است که حلقهی اجرا را طوری طراحی کنید که بتوانید در هر گام مدل متفاوت انتخاب کنید. اگر حلقهی اجرا یک مدل ثابت دارد، این اهرم را از دست داده‌اید.
خلاصه‌سازی context برای کاهش توکن ورودی در گام‌های بعدی#
context window در هر گام بزرگ‌تر میشود. خلاصه‌سازی ترحیمی یعنی context قدیمی را فشرده کنید و فقط بخش‌های مرتبط را کامل نگه دارید. این کار توکن ورودی را در گام‌های بعدی کاهش میدهد.
الگوی «ایجنت با محدودیت گام» به‌عنوان ابزار کنترل هزینه عمل میکند. اگر تسک در 5 گام حل نشد، احتمالاً معماری مشکل دارد، نه مدل. ادامه دادن با مدل گران‌تر، مشکل معماری را حل نمی‌کند.
چه زمانی از ایجنت استفاده نکنیم؟#
اگر تسک شما مسیر اجرای ثابت و از پیش‌تعریف‌شده دارد، خروجی‌اش باید قطعی (deterministic) باشد، یا با یک prompt خوب و یک فراخوانی API حل میشود، ایجنت اضافهکاری است. over-engineering رایج‌ترین اشتباه در پروژه‌های ایجنتی است و هزینه‌اش نه فقط در توسعه، بلکه در نگهداری و عیب‌یابی هم حس میشود.
مرز ساده: اگر «تصمیم» مدل فقط انتخاب بین چند گزینه‌ی مشخص است، ورکفلو کافی است. ایجنت وقتی لازم است که مدل خودش باید بفهمد اصلاً کدام ابزار لازم است و به چه ترتیبی اجرا شوند.
سیگنال‌هایی که می‌گویند ایجنت لازم نیست#
- مسیر اجرا از پیش مشخص است و تغییر نمی‌کند
- خروجی باید deterministic و قابل‌تکرار باشد
- تسک با یک prompt دقیق و یک فراخوانی API حل میشود
- ابزارها ثابت‌اند و ترتیبشان همیشه یکسان است
سیگنال‌هایی که واقعاً ایجنت می‌خواهند#
- تعداد و نوع ابزار لازم، وابسته به ورودی کاربر است
- ترتیب اجرا وابسته به نتیجهی گام قبلی است
- مدل باید خودش تصمیم بگیرد آیا ادامه دهد یا تمام کند
- تسک باز است و مسیر مشخصی روی کاغذ نمی‌شود نوشت
استفاده از multi-agent برای تسک‌هایی که با یک ایجنت تک‌ابزاری حل می‌شوند، هم هزینه را بالا می‌برد هم قابلیت اطمینان را پایین. این الگو در پروژه‌های عملی بارها تکرار شده و هر بار نتیجه‌اش یکسان بوده: پیچیدگی اضافه بدون ارزش افزوده.
رایج‌ترین اشتباهات در ساخت ایجنت هوش مصنوعی#
پنج اشتباه پرتکرار: نداشتن سقف تکرار، لاگ‌نکردن tool callها، انتخاب فریمورک قبل از معماری، فرض خودمختاری کامل بدون guardrails، و over-engineering با multi-agent برای تسک ساده. هرکدام از این‌ها هزینه‌ی عملی مشخصی دارند — از بی‌ثباتی خروجی تا هزینه‌ی غیرقابل‌پیش‌بینی API.
الگوی تکرارشونده در پروژه‌های عملی — ایجنت تک‌ابزاری با prompt دقیق#
در پروژه‌های واقعی، ایجنت تک‌ابزاری با prompt دقیق در اکثر موارد ساده‌تر، ارزان‌تر و قابل‌اعتمادتر از سیستم چندایجنتی عمل میکند. این الگو بارها در مستندات و پروژه‌های متن‌باز دیده شده است.
ساختار پوشه‌ی نمونه‌ی یک ایجنت تک‌ابزاری:
agent/
main.py # حلقهی اجرا
tools/
search.py
email.py
calculator.py
config.yaml # max_iterations, model, temperature
logs/
tool_calls.log
چگونه guardrails را در لایهی کنترل پیاده کنیم#
Guardrails در لایهی کنترل سه سطح دارند: سقف تکرار (max iterations)، محدودیت ابزار (whitelist)، و human-in-the-loop برای اقدامات پرخطر.
سقف تکرار بدون fallback پیام‌رسان، یعنی ایجنت بعد از رسیدن به سقف، خروجی ناکامل میدهد و کاربر نمی‌فهمد چرا. fallback باید صریح باشد: «تسک در تعداد گام مجاز حل نشد، لطفاً ورودی را ساده‌تر کنید.»
قبل از کدنویسی، مرز بین ورکفلو و ایجنت را مشخص کنید، سقف تکرار را تعیین کنید، و لاگ tool call را از همان ابتدا بگذارید. ایجنت تک‌ابزاری با prompt دقیق، در اکثر پروژه‌ها بهترین انتخاب است.
اگر می‌خواهید این تصمیمات معماری را در عمل پیاده کنید و با ساختار پروژه‌های واقعی آشنا شوید، دوره‌ی «ساخت Ai Agent با N8N» در کامیونیتی اسکول این مسیر را از صفر تا محصول قابل‌استفاده پوشش میدهد.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته می‌شوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.