گران‌ترین اشتباه در ساخت ایجنت هوش مصنوعی، انتخاب فریم‌ورک غلط نیست. اشتباه اصلی این است که ایجنت بسازید جایی که یک workflow ثابت با هزینه و پیچیدگی بسیار کمتر، همان کار را حل می‌کرد. این مقاله ابتدا مرز بین ایجنت و workflow را مشخص می‌کند، سپس معماری حلقه‌ی ReAct، مقایسه‌ی فریم‌ورک‌ها و معیارهای تصمیم‌گیری را با مثال‌های واقعی پوشش می‌دهد.

مرز بین ایجنت و workflow ساده کجاست؟#

ایجنت هوش مصنوعی (AI Agent) سیستمی است که در زمان اجرا (runtime) خودش تصمیم می‌گیرد کدام ابزار را با چه ورودی صدا بزند و چه زمانی متوقف شود. workflow مسیر از پیش تعریف‌شده‌ای دارد و در runtime تصمیم‌گیری نمی‌کند. این تمایز، نه تعداد ابزار، نه تعداد شرط — همین یک ویژگی، مرز را مشخص می‌کند.

تمایز سه‌گانه‌ی عملی این است: یک chatbot با function calling ایجنت نیست، چون کاربر هر مرحله را هدایت می‌کند. یک workflow با چند شرط ایجنت نیست، چون مسیر از قبل خط‌چینی شده. ایجنت حلقه‌ی تصمیم‌گیری دارد: مدل در هر تکرار فکر می‌کند، ابزار انتخاب می‌کند، نتیجه را می‌خواند و تصمیم می‌گیرد ادامه بدهد یا بایستد.

مثال ملموس: کاربر می‌گوید «حقوق کارمندان بخش فنی را محاسبه کن». ایجنت خودش تشخیص می‌دهد باید ابتدا database query بزند تا لیست کارمندان را بگیرد، سپس calculator tool را صدا بزند و در نهایت خروجی را فرمت کند. در workflow ثابت، این سه مرحله از پیش در کد خط‌چینی شده‌اند و اگر کاربر بگوید «حقوق بخش مالی»، باید مسیر جدیدی تعریف کنید.

نکته‌ی کلیدی: اگر کاربر هر مرحله را خودش هدایت می‌کند، شما ایجنت ندارید؛ chatbot با function calling دارید. autonomy در انتخاب ابزار، planning و stopping condition سه رکن تعریف عملیاتی ایجنت‌اند.

معماری ایجنت: حلقه‌ی Reasoning و Acting#

حلقه‌ی Reasoning و Acting (ReAct) قلب معماری هر ایجنت است: مدل زبانی بزرگ (LLM) در هر تکرار استدلال می‌کند (Thought)، یک ابزار را صدا می‌زند (Action)، نتیجه را می‌خواند (Observation) و تا رسیدن به پاسخ یا سقف تکرار ادامه می‌دهد. بدون این حلقه، ایجنت چیزی جز یک تابع با چند if-else نیست.

حلقه‌ی بصری بین تفکر و عمل در معماری ایجنت با دو ناحیه‌ی نورانی متمایز و جریان انرژی
حلقه‌ی Reasoning-Acting قلب هر ایجنت است؛ بدون آن فقط یک pipeline ساده داریم.

الگوی ReAct و جای آن در ایجنت‌های مدرن#

مقاله‌ی Yao et al. (2022) ترکیب chain-of-thought با acting را در benchmark‌های HotpotQA و ALFWorld ارزیابی کرد و نشان داد این ترکیب دقت را نسبت به baseline افزایش می‌دهد. پایه‌ی فنی بسیاری از ایجنت‌های امروزی، قابلیت Function Calling است که OpenAI در ژوئن 2023 به API اضافه کرد و به مدل اجازه داد خروجی ساختاریافته برای صدا زدن ابزار تولید کند.

در عمل، حلقه‌ی ReAct ساده است: Thought → Action → Observation → تکرار یا توقف. پیچیدگی در مدیریت context window و تصمیم‌گیری درباره‌ی توقف است — نه در خود حلقه.

اجزای معماری: حافظه، ابزار، برنامه‌ریزی#

یک ایجنت کامل چهار جزء معماری دارد:

  • Short-term memory (scratchpad): تاریخچه‌ی تکرارهای جاری در context window نگه داشته می‌شود. هر iteration نتیجه‌ی قبلی را به ورودی بعدی اضافه می‌کند.
  • Long-term memory: در vector store ذخیره می‌شود و بین session‌ها بازیابی می‌گردد. bottleneck اصلی context window است؛ ایجنت‌های بلندمدت باید بین این دو لایه جابه‌جا شوند.
  • Tool registry: تعریف طرح‌واره (schema) هر ابزار و پارامترهایش. هر ابزار یک توصیف متنی و یک ساختار ورودی/خروجی دارد.
  • Planner: ماژولی که task را به زیر-قدم‌ها تجزیه می‌کند (Plan-and-Execute Pattern). در ایجنت‌های ساده‌تر، planner و executor در یک حلقه‌ی ReAct ادغام می‌شوند.

مسئله‌ی non-termination و infinite loop#

ایجنت ممکن است در چرخه‌ی تکراری گیر کند یا هرگز متوقف نشود. این مسئله در اکثر آموزش‌های فارسی‌زبان غایب است — و همین غیبت، پرهزینه‌ترین باگ پنهان ایجنت‌های ایرانی است. راه‌حل‌های عملی: max iterations، timeout، step budget و stopping condition صریح در system prompt. بدون این‌ها، یک ایجنت در production می‌تواند ساعت‌ها LLM call بزند و هزینه‌ی قابل‌توجهی تحمیل کند.

مقایسه‌ی فریم‌ورک‌های ساخت ایجنت: کدام مناسب چه taskی است؟#

بهترین فریم‌ورک ساخت ایجنت AI وجود ندارد؛ انتخاب به معماری task وابسته است نه به محبوبیت ابزار: LangChain برای اکوسیستم گسترده و prototyping سریع، AutoGen برای گفتگوی چندایجنتی، CrewAI برای workflowهای نقش‌محور، و Semantic Kernel برای یکپارچه‌سازی با استک مایکروسافت مناسب‌اند. هر کسی که یک فریم‌ورک را «بهترین» مطلق معرفی می‌کند، یا هنوز معماری loop را نفهمیده یا دارد محصول خودش را می‌فروشد.

فریم‌ورکمعماریمناسب‌ترین use caseLearning curve
LangChainSingle-agent loop + tool chainPrototyping سریع، اکوسیستم گسترده، observability با LangSmithمتوسط (abstraction سنگین)
AutoGen (Microsoft)Conversation-based multi-agentTask‌هایی که چند نقش (researcher, coder, reviewer) باید هماهنگ شوندسنگین
CrewAIRole-based orchestrationWorkflowهای خطی با چند عامل، ساده‌تر از AutoGenسبک
Semantic KernelPlugin-based + plannerسازمان‌هایی که روی Azure و استک .NET invested‌اندمتوسط

نکته‌ی ضدالگو: پرش مستقیم به فریم‌ورک بدون فهم معماری loop و memory باعث می‌شود کاربر در debug گیر کند. نمی‌داند کدام iteration چرا ابزار X را انتخاب کرد. ابتدا معماری را بفهم، بعد ابزار انتخاب کن — این ترتیب، هزینه‌ی یادگیری را نصف می‌کند.

ساخت ایجنت از صفر: شش مرحله‌ی عملی#

ساخت ایجنت عملیاتی در شش مرحله انجام می‌شود: تعریف task و stopping condition، انتخاب مدل و ابزارها، پیاده‌سازی حلقه‌ی ReAct، افزودن حافظه و محصورسازی (guardrail)، تست با سناریوهای واقعی، و استقرار با قابلیت مشاهده (observability). مرحله‌ی اول — stopping condition — مرحله‌ای است که اکثر تیم‌ها از آن می‌گذرند و بعد در production غافلگیر می‌شوند.

مراحل گام‌به‌گام#

  1. تعریف task و stopping condition: دقیقاً چه زمانی ایجنت باید متوقف شود؟ بدون پاسخ به این سؤال، حلقه بی‌پایان است.
  2. انتخاب مدل و ابزارها: کدام LLM؟ کدام tools با چه schema؟ هر ابزار یک توصیف متنی و ساختار ورودی/خروجی دارد.
  3. پیاده‌سازی حلقه‌ی ReAct: Thought → Action → Observation → (تکرار یا توقف). این حلقه را ابتدا بدون فریم‌ورک بسازید تا درک کنید چه اتفاقی می‌افتد.
  4. افزودن memory و context management: scratchpad برای تاریخچه‌ی جاری، long-term store برای بازیابی بین session‌ها.
  5. Guardrails و safety: input validation، output filtering، human-in-the-loop برای عملیات حساس مثل حذف داده یا انتقال وجه.
  6. تست و ارزیابی: task completion rate، cost per task، safety violations. سه معیار جداگانه.

نمونه ساختار پروژه#

ساختار پوشه‌ی یک ایجنت ساده:

  • agent.py — حلقه‌ی اصلی ReAct
  • tools/ — تعریف schema و پیاده‌سازی هر ابزار
  • memory/ — scratchpad و vector store
  • guardrails/ — input validation و output filtering
  • eval/ — سناریوهای تست و متریک‌ها

نمونه‌ی شبه‌کد حلقه‌ی ReAct:

while iteration < max_iterations:
    thought = llm.reason(context + scratchpad)
    if thought.is_final_answer:
        return thought.answer
    action = thought.select_tool()
    observation = execute(action)
    scratchpad.append(thought, action, observation)
    iteration += 1

ایجنت چندگانه کی لازم است و کی فقط پیچیدگی اضافی است؟#

ایجنت چندگانه (Multi-Agent System) فقط وقتی توجیه دارد که task‌های فرعی ماهیتاً متفاوت‌اند و نیاز به context window جداگانه دارند؛ در غیر این صورت یک ایجنت با ابزارهای بیشتر از سه ایجنت ساده بهتر و ارزان‌تر کار می‌کند. اضافه کردن ایجنت دوم، معمولاً مشکل را حل نمی‌کند — فقط debug را دو برابر سخت‌تر می‌کند.

الگوهای orchestration#

  • Supervisor Pattern: یک ایجنت central تصمیم می‌گیرد کدام sub-agent را صدا بزند. ساده‌ترین الگوی multi-agent.
  • Hierarchical Pattern: لایه‌بندی supervisorها برای سازمان‌دهی عمیق‌تر. مناسب task‌های با چندین زیر-سطح.
  • Sequential Pattern: ایجنت‌ها پشت سر هم اجرا می‌شوند؛ خروجی هر کدام ورودی بعدی است.

معیار تصمیم: کی multi-agent و کی single-agent#

نکته‌ی کلیدی: هماهنگی و token overhead در multi-agent به‌صورت نمایی رشد می‌کند. مثال عملی: task «تحقیق + نوشتن مقاله» → دو ایجنت (researcher + writer) توجیه دارد چون context window متفاوت نیاز دارند. task «جستجو + محاسبه + فرمت‌دهی» → یک ایجنت با سه tool کافی است.

اندرو ان‌جی در talkهای 2024 اشاره کرد الگوهای multi-agent collaboration می‌توانند عملکرد را بهبود دهند، اما این ادعا مربوط به task‌های کدنویسی خاص است و نباید به‌عنوان قاعده‌ی عمومی تعمیم داده شود. اگر کسی می‌گوید «multi-agent همیشه بهتر است»، هنوز هزینه‌ی coordination را محاسبه نکرده است.

هزینه‌ی واقعی اجرای ایجنت در production#

هزینه‌ی واقعی ایجنت در production، هر iteration ایجنت یک call کامل به LLM است؛ بنابراین یک ایجنت با ده ابزار و پنج iteration می‌تواند ده‌ها برابر یک query ساده هزینه داشته باشد. محاسبه‌ی token economics قبل از شروع ساخت، نه بعد از آن، لازم است.

فرمول ساده‌ی تخمین: iterations × (input tokens + output tokens) × قیمت هر token. عوامل افزایش هزینه: تعداد ابزار در system prompt (هر ابزار schema خودش را به context اضافه می‌کند)، طول تاریخچه‌ی حافظه، retry در خطا.

راه‌حل‌های کاهش هزینه:

  • Context pruning: حذف تکرارهای قدیمی از scratchpad.
  • Summarization بین تکرارها: به‌جای نگه‌داشتن کل تاریخچه، خلاصه‌ی تکرارهای قبلی را نگه دارید.
  • Model routing: مدل ارزان برای classification، مدل قوی برای reasoning. نه همه‌ی iterations به گران‌ترین مدل نیاز دارند.

مقایسه‌ی کیفی: هزینه‌ی یک workflow ثابت در برابر یک ایجنت با همان خروجی — معمولاً ایجنت گران‌تر است و باید این تفاوت با ارزش autonomy توجیه شود. اگر تفاوت هزینه را نمی‌توانید توجیه کنید، ایجنت نسازید.

5 اشتباه رایج هنگام ساخت ایجنت#

رایج‌ترین اشتباهات هنگام ساخت ایجنت پنج موردند: ساخت ایجنت برای taskهایی که با regex یا تابع ساده حل می‌شوند، فرض خودمختاری کامل، پرش به فریم‌ورک بدون فهم معماری، نادیده‌گرفتن non-termination، و استفاده از ایجنت به‌جای chatbot با function calling. از این پنج، نادیده‌گرفتن non-termination پرهزینه‌ترین است چون مستقیماً بودجه‌ی LLM را می‌سوزاند.

اشتباهات معماری#

ایجنت برای task قابل‌پیش‌بینی: اگر مسیر اجرا از قبل مشخص است، workflow ثابت بسازید. ایجنت برای taskهایی که ترتیب ابزارها در runtime مشخص نمی‌شود مناسب است، نه برای فرآیندهای خطی.

فرض خودمختاری کامل: ایجنت تولیدی بدون guardrail، timeout و human-in-the-loop در اولین edge case شکست می‌خورد. ایجنت بدون guardrail در production یک آسیب‌پذیری امنیتی است.

اشتباهات فنی#

پرش مستقیم به LangChain بدون فهم loop: کاربر در debug گیر می‌کند چون نمی‌داند کدام iteration چرا ابزار X را انتخاب کرد. ابتدا حلقه را دستی بسازید، بعد فریم‌ورک.

حذف stopping condition: ایجنت در infinite loop گیر می‌کند و هزینه‌ی LLM call به‌صورت کنترل‌نشده بالا می‌رود.

اشتباهات ارزیابی#

فقط accuracy سنجیدن: ایجنت‌ها باید با task completion rate، cost per task و safety violations جداگانه ارزیابی شوند. ارزیابی ایجنت بنیادین با ارزیابی LLM متفاوت است.

نکته‌ی مشاهده‌ی میدانی: در پروژه‌های اعضای N8N اسکول، رایج‌ترین علت شکست ایجنت در production نبود timeout و max iterations است. ایجنتی که حلقه‌ی بی‌پایان می‌زند، نه هزینه‌ی LLM را کنترل می‌کند و نه تجربه‌ی کاربر را.

چه زمانی اصلاً نباید ایجنت بسازم#

اگر task شما مسیر از پیش تعریف‌شده دارد، ورودی‌اش محدود و قابل‌پیش‌بینی است، و خروجی‌اش با یک تابع ساده یا database query قابل‌محاسبه است، ایجنت فقط هزینه و پیچیدگی اضافی تحمیل می‌کند — و این هزینه، نه یک‌بار بلکه در هر request تکرار می‌شود.

چک‌لیست تصمیم‌گیری — سه سؤال قبل از ساخت ایجنت:

  1. آیا مسیر اجرا از قبل مشخص است؟ اگر بله → workflow ثابت.
  2. آیا task در runtime نیاز به انتخاب ابزار دارد؟ اگر نه → prompt chain ساده.
  3. آیا خروجی با یک regex، تابع یا query قابل‌محاسبه است؟ اگر بله → اصلاً LLM لازم نیست.

جایگزین‌های ساده‌تر: prompt chain، workflow ثابت، rule-based routing، function calling بدون loop.

مثال واقعی: task «ترجمه‌ی متن کاربر به انگلیسی» → یک API call به مدل، نه ایجنت. task «تحلیل داده‌های فروش و ارائه‌ی توصیه» → ایجنت چون ابزار و ترتیب اجرا در runtime مشخص نمی‌شود.

نتیجه‌ی عملی: ایجنت ابزاری است برای taskهایی که در runtime تصمیم‌گیری نیاز دارند. قبل از ساخت، بپرسید آیا یک workflow ثابت همان کار را با هزینه‌ی کمتر انجام می‌دهد یا نه. اگر بله، ایجنت نسازید.

اگر می‌خواهید ایجنت‌سازی را با ابزار عملی و پروژه‌محور یاد بگیرید، دوره‌ی «ساخت Ai Agent با N8N» در کامیونیتی N8N اسکول، 51 جلسه و 41 ساعت آموزش آفلاین است که از معماری حلقه تا استقرار در production را پوشش می‌دهد.