ساخت ایجنت هوش مصنوعی (AI Agent) بیشتر از آنکه به پرامپت‌نویسی مربوط باشد، به طراحی حلقه‌ی اجرا و شرایط توقف برمی‌گردد. بخش عمده‌ی پروژه‌هایی که در این حوزه شکست می‌خورند، نه به‌خاطر مدل ضعیف، بلکه به‌خاطر معماری ناقص و نبود منطق توقف صریح است. انتخاب فریمورک، الگوی Loop Engineering و معیارهای عملیِ «چه زمانی اصلاً ایجنت نسازید»، سه تصمیمی هستند که سرنوشت پروژه را تعیین می‌کنند.

ایجنت هوش مصنوعی چیست و چه فرقی با چت‌بات دارد؟#

ایجنت هوش مصنوعی یک مدل زبانی بزرگ (Large Language Model) است که در حلقه‌ی خودگردان تصمیم می‌گیرد کدام ابزار را صدا بزند، نتیجه را تفسیر کند و ادامه دهد یا متوقف شود. چت‌بات یک ورودی را به یک خروجی تبدیل می‌کند؛ ایجنت چند گام اجرا می‌کند و در هر گام بر اساس خروجی قبلی تصمیم جدید می‌گیرد.

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

سه مؤلفه‌ی ضروری در هر ایجنت وجود دارد:

  • LLM (مغز): مدل زبانی که تصمیم‌گیری می‌کند.
  • ابزارها (Tool Use): توابعی که ایجنت می‌تواند صدا بزند — جستجو، اجرای کد، فراخوانی API.
  • منطق توقف (Stopping Condition): شرطی که مشخص می‌کند حلقه کی تمام شود.

تفاوت با RAG (Retrieval-Augmented Generation) هم مهم است. RAG یک الگوی بازیابی است: سند مرتبط را پیدا کن، به پرامپت اضافه کن، پاسخ بده. ایجنت یک الگوی تصمیم‌گیری است: ابزار بعدی چیست، آیا نیاز به گام اضافی هست، آیا کار تمام شده.

مثال عملی: ایجنتی که باگ را پیدا می‌کند، کد را اصلاح می‌کند، تست می‌گیرد و اگر تست رد شد دوباره اصلاح می‌کند — این ایجنت است. چت‌باتی که فقط توضیح می‌دهد باگ احتمالاً کجاست — این چت‌بات است.

یک اشتباه رایج در پروژه‌های اعضای کامیونیتی: سیستمی را «ایجنت» می‌نامند که در واقع یک Workflow خطی با سه مرحله است و هیچ تصمیم‌گیری پویا ندارد. اگر مسیر اجرا ثابت است و مدل فقط نقش تبدیل متن به متن را بازی می‌کند، شما ایجنت نساخته‌اید؛ یک اسکریپت با LLM نوشته‌اید.

معماری ایجنت: حلقه‌ی اجرا مهم‌تر از پرامپت است#

معماری ایجنت از پنج جزء ساخته می‌شود: LLM، ابزارها، حافظه (Memory)، برنامه‌ریز (Planning) و حلقه‌ی اجرا (Agent Loop). بیشترین باگ‌ها در طراحی حلقه‌ی اجرا و شرایط توقف رخ می‌دهد، نه در کیفیت پرامپت. یک پرامپت عالی بدون منطق توقف درست، ایجنت را به چرخه‌ی بی‌پایان تبدیل می‌کند.

اجزای اصلی معماری#

هر ایجنت از این لایه‌ها تشکیل شده:

  • LLM: هسته‌ی تصمیم‌گیری. هر فراخوانی یک گام از حلقه است.
  • Tool Use: رابط ایجنت با دنیای بیرون. ابزارها به‌صورت schema تعریف می‌شوند.
  • Memory: حافظه‌ی کوتاه‌مدت (تاریخچه‌ی مکالمه) و بلندمدت (دانش ذخیره‌شده). بدون حافظه، ایجنت هر بار از صفر شروع می‌کند.
  • Planning: ماژولی که هدف را به زیرمسئله‌ها تقسیم می‌کند.
  • Agent Loop: حلقه‌ی اجرای اصلی. تصمیم می‌گیرد ادامه دهد یا بایستد.

شبه‌کد حلقه‌ی اجرا:

while not stop_condition:
    action = llm.decide(context, tools)
    if action == "finish": break
    result = execute(action)
    context.append(result)
    if iterations > max_iterations: break
    if elapsed_time > timeout: break

دو شرط توقف در انتهای این کد — سقف تکرار و سقف زمانی — تفاوت بین یک ایجنت قابل‌استفاده و یک فاکتور API غیرقابل‌پیش‌بینی را رقم می‌زنند. حذف هرکدام از این دو، پروژه را در حالت «امیدواریم زودتر تمام شود» رها می‌کند.

الگوی ReAct: Reasoning + Acting#

الگوی ReAct توسط Shunyu Yao و همکارانش در دانشگاه پرینستون و Google Research معرفی شد. چرخه‌ی آن سه مرحله است: Thought (تفکر)، Action (اقدام)، Observation (مشاهده). مدل اول فکر می‌کند، بعد ابزار صدا می‌زند، بعد نتیجه را می‌بیند و دوباره فکر می‌کند.

در آزمون‌های HotpotQA و Fever، ReAct نسبت به Chain-of-Thought خالص نتایج بهتری داشت. تفاوت اصلی این است که CoT فقط فکر می‌کند، اما ReAct فکر و عمل را ترکیب می‌کند.

الگوی Plan-and-Execute#

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

تفاوت با ReAct: ReAct گام‌به‌گام فکر می‌کند و در هر لحظه فقط گام بعدی را تعیین می‌کند. Plan-and-Execute اول همه‌ی گام‌ها را مشخص می‌کند و بعد اجرا می‌کند. اگر وظیفه حین اجرا تغییر کند، Plan-and-Execute نیاز به بازبرنامه‌ریزی دارد — و این بازبرنامه‌ریزی خودش یک فراخوانی اضافی و یک نقطه‌ی شکست احتمالی است.

الگوی Reflection#

ایجنت خروجی خودش را نقد می‌کند و اصلاح می‌کند. هزینه‌ی اضافی دارد (هر بار یک فراخوانی بیشتر) اما دقت را بالا می‌برد. مناسب کدنویسی و تولید محتوای حساس.

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

فریمورک‌های ساخت ایجنت: LangGraph، AutoGen، CrewAI و OpenAI Agents SDK#

فریمورک‌های ساخت ایجنت به مدل مدیریت state بستگی دارد: LangGraph گراف‌محور است و برای جریان‌های پیچیده با شرط‌ها مناسب است، AutoGen مکالمه‌محور است و برای تعامل چندعاملی طبیعی‌تر عمل می‌کند، CrewAI نقش‌محور است و OpenAI Agents SDK سبک‌ترین گزینه برای شروع سریع است. هیچ‌کدام «بهترین» نیست؛ هرکدام برای سناریوی خاصی ساخته شده.

فریمورکمدل معماریمدیریت stateمناسب برای
LangGraphGraph-basedهر node یک گام، هر edge یک انتقالجریان‌های پیچیده با شرط و بازگشت
AutoGenConversation-basedتاریخچه‌ی گفتگو بین ایجنت‌هاسناریوهای چندایجنتی تعاملی
CrewAIRole-basedنقش‌های تیمی با مسئولیت مشخصتیم‌های مجازی با تقسیم وظایف
OpenAI Agents SDKHandoff-basedانتقال کنترل بین ایجنت‌هاشروع سریع و پروژه‌های کوچک

LangGraph: Graph-based State Management#

در LangGraph هر ایجنت یک node و هر انتقال یک edge است. کنترل دقیق بر جریان اجرا دارید. اگر ایجنت در مرحله‌ی سوم شکست خورد، می‌توانید به مرحله‌ی دوم برگردید. این سطح از کنترل در فریمورک‌های مکالمه‌محور سخت‌تر است.

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

AutoGen: Conversation-based Multi-Agent#

AutoGen فریمورک چندایجنتی مایکروسافت است. ایجنت‌ها با هم و با انسان گفتگو می‌کنند. مناسب سناریوهایی که تعامل طبیعی بین عوامل اولویت دارد — مثلاً ایجنتی که کد می‌نویسد و ایجنتی که تست می‌گیرد و با هم بحث می‌کنند.

CrewAI و OpenAI Agents SDK#

CrewAI روی نقش‌های تیمی تمرکز دارد. هر ایجنت یک «نقش» دارد (مثلاً Researcher، Writer، Reviewer) و نتایج را به هم دست‌به‌دست می‌کنند. OpenAI Agents SDK (قبلاً Swarm نام داشت) سبک‌تر است و برای شروع سریع مناسب‌تر.

هشدار: این فریمورک‌ها ابزارند نه الزام. بسیاری از تیم‌ها با پیاده‌سازی مستقیم روی API و یک حلقه‌ی ساده، کنترل و وضوح بیشتری دارند. اگر پروژه‌تان پیچیدگی گراف ندارد، LangGraph اضافه است — و اضافه‌بار در کد، هزینه‌ی نگهداری است.

نمونه ساختار پوشه پروژه ایجنت:

agent_project/
  ├── core/
  │    ├── loop.py       # حلقه‌ی اجرا
  │    ├── stop_conditions.py # منطق توقف
  │    └── context_manager.py # مدیریت حافظه
  ├── tools/
  │    ├── search.py
  │    ├── code_exec.py
  │    └── registry.py  # تعریف schema ابزارها
  ├── guardrails/
  │    ├── rate_limiter.py
  │    └── output_validator.py
  └── config.py          # max_iterations، timeout، سقف هزینه

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

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

معیارهای تصمیم‌گیری:

  1. آیا مسیر اجرا از قبل قابل پیش‌بینی است؟ اگر بله، Workflow ثابت بسازید. ایجنت برای مسیرهای غیرقابل‌پیش‌بینی است.
  2. آیا تعداد فراخوانی‌ها ثابت است؟ اگر همیشه سه بار ابزار صدا می‌زنید، حلقه‌ی ایجنت اضافه است. یک تابع با سه فراخوانی کافی است.
  3. آیا خطای یک مرحله فاجعه‌بار است؟ اگر ایجنت در گام دوم اشتباه کند و گام سوم را خراب کند، بهتر است Workflow دستی با تأیید انسانی بسازید.
  4. آیا پاسخ فقط به یک بازیابی نیاز دارد؟ اگر بله، RAG کافی است. ایجنت لازم نیست.

مثال واقعی: تولید خلاصه‌ی مقاله. ورودی مشخص است (متن مقاله)، خروجی مشخص است (خلاصه)، تعداد فراخوانی ثابت است (یک بار). ایجنت اینجا بیش‌ازحد پیچیده است. یک پرامپت با template کافی است.

در مقابل: ایجنتی که باید یک باگ را پیدا کند، اصلاح کند، تست بگیرد و اگر تست رد شد دوباره اصلاح کند — اینجا مسیر اجرا غیرقابل‌پیش‌بینی است و ایجنت لازم است.

در گفتگوهای اعضای کامیونیتی، سؤال «آیا این کار واقعاً به ایجنت نیاز دارد؟» تقریباً همیشه مثبت جواب می‌گیرد — نه چون کار به ایجنت نیاز دارد، بلکه چون ساختن ایجنت جذاب‌تر از نوشتن یک تابع ساده است. این خطای شناختی، پروژه‌ها را به سمت پیچیدگی بی‌مورد می‌کشاند.

رایج‌ترین اشتباهات در ساخت ایجنت: حلقه بی‌پایان و توهم در Tool Call#

رایج‌ترین اشتباهات در ساخت ایجنت، حلقه بی‌پایان (Infinite Loop) و توهم در Tool Call است. حلقه بی‌پایان شایع‌ترین شکست ایجنت‌هاست: مدل ابزار را صدا می‌زند، نتیجه را نمی‌فهمد، دوباره همان ابزار را صدا می‌زند. بدون سه لایه‌ی دفاعی — max_iterations، timeout و reflection-based stopping — هزینه‌ی API به‌صورت نمایی رشد می‌کند.

حلقه بی‌پایان: چرا و چگونه#

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

راه‌حل‌ها:

  • max_iterations: سقف تعداد گام‌های حلقه. اگر ایجنت بعد از N گام به جواب نرسید، متوقف شود.
  • timeout: سقف زمانی. حتی اگر iterations تمام نشده، از زمان بگذرد، ایجنت بایستد.
  • Reflection-based stopping: ایجنت بعد از هر گام از خودش بپرسد «آیا نزدیک‌تر شدم؟» اگر نه، توقف.

توهم در Tool Call#

مدل ابزاری را صدا می‌زند که وجود ندارد، یا پارامترهای اشتباه می‌فرستد. این مشکل در مدل‌های ضعیف‌تر بیشتر است. راه‌حل: اعتبارسنجی ساختاریافته (Structured Output) و retry با بازخورد.

الگوی retry: اگر tool call نامعتبر بود، پیام خطا را به مدل برگردانید و بگویید «این ابزار وجود ندارد، از این لیست انتخاب کن». مدل‌های جدیدتر با این بازخورد خودشان اصلاح می‌کنند.

حذف منطق توقف#

ایجنت نمی‌داند کِی تمام کند. شرایط توقف باید صریح تعریف شود: رسیدن به هدف، تعداد حداکثر گام، یا تشخیص شکست. بدون شرط توقف، ایجنت تا سقف token یا بودجه‌ی API ادامه می‌دهد.

کد نمونه حلقه با stop conditions:

def agent_loop(llm, tools, max_iter=15, timeout=120):
    start = time.now()
    context = [system_prompt, user_goal]
    for i in range(max_iter):
        if time.now() - start > timeout:
            return {"status": "timeout", "steps": i}
        action = llm.call(context, tools)
        if action.type == "finish":
            return {"status": "done", "result": action.payload}
        result = execute_tool(action, tools)
        context.append({"role": "tool", "content": result})
    return {"status": "max_iterations", "steps": max_iter}

در این کد، سه نقطه‌ی خروج (finish، timeout، max_iterations) هر سه باید وجود داشته باشند. حذف هرکدام، یک حالت شکست را بدون پوشش رها می‌کند.

سیستم چندایجنتی: الگوی Orchestrator و Worker#

سیستم چندایجنتی فقط وقتی ارزش دارد که تفکیک وظایف اجزای مستقل واقعی داشته باشد — مثلاً وقتی یک ایجنت کد می‌نویسد و دیگری تست می‌گیرد و هرکدام ابزار و حافظه‌ی متفاوتی نیاز دارند. در اکثر پروژه‌ها یک ایجنت خوب‌طراحی‌شده از سه ایجنت ضعیف بهتر عمل می‌کند.

الگوی Orchestrator: یک ایجنت مرکزی وظایف را تقسیم می‌کند و نتایج را جمع می‌کند. Orchestrator تصمیم می‌گیرد کدام Worker چه کاری انجام دهد. این الگو در LangGraph و CrewAI پیاده‌سازی شده.

الگوی گفتگوی مستقیم: ایجنت‌ها بدون واسطه با هم صحبت می‌کنند. AutoGen این الگو را اجرا می‌کند. مناسب سناریوهایی که تعامل طبیعی بین عوامل اولویت دارد.

قاعده‌ی عملی: اگر نمی‌توانید مرز وظایف هر ایجنت را در یک جمله تعریف کنید، Multi-Agent نسازید. یک ایجنت با چند ابزار ساده‌تر، ارزان‌تر و قابل‌دیباگ‌تر است.

هزینه‌ی پنهان Multi-Agent: هر ایجنت یک حلقه‌ی مستقل دارد. سه ایجنت یعنی سه حلقه، سه برابر فراخوانی API، سه برابر هزینه. اگر تفکیک وظایف واقعی نیست، این هزینه بی‌دلیل است.

ارزیابی، دیباگ و هزینه‌ی پنهان ایجنت#

ارزیابی ایجنت در محیط تولید با Benchmarkهای موجود مثل SWE-bench و GAIA فاصله‌ی جدی دارد. این benchmarkها فقط توانایی (capability) را می‌سنجند — آیا ایجنت می‌تواند این کار را انجام دهد؟ هیچ ابزار استانداردی برای سنجش قابلیت‌اعتماد (reliability) و هزینه‌ی هر وظیفه (cost-per-task) وجود ندارد. در محیط تولید، این شکاف مهم‌تر است.

Benchmarkهای موجود#

  • SWE-bench: حل باگ‌های واقعی GitHub. ایجنت باید باگ را پیدا و اصلاح کند و تست پاس شود.
  • GAIA: وظایف عمومی با ابزار — جستجو، محاسبه، دسترسی به فایل.
  • WebArena: تعامل با وب. ایجنت باید در محیط مرورگر کار کند.

این benchmarkها به شما می‌گویند ایجنت «می‌تواند» این کار را بکند. نمی‌گویند «چند بار از ده بار درست کار می‌کند» یا «هر موفقیت چند دلار هزینه دارد».

آنچه benchmarkها نمی‌سنجند#

سه معیار عملی که در محیط تولید حیاتی‌اند:

  1. Reliability: ایجنت ۱۰ بار اجرا شود، چند بار درست کار می‌کند؟ اگر ۶ بار موفق باشد، در محیط تولید قابل‌اتکا نیست.
  2. Cost-per-task: هر موفقیت چند فراخوانی API و چند دلار هزینه دارد؟ ایجنتی که ۳۰ بار ابزار صدا می‌زند تا یک کار ساده انجام دهد، در مقیاس اقتصادی نیست.
  3. Latency: چند ثانیه طول می‌کشد؟ اگر کاربر ۵ دقیقه منتظر بماند، حتی اگر جواب درست باشد، تجربه‌ی کاربری شکست خورده است.

روش‌های عملی ارزیابی#

ساخت test suite اختصاصی: ۱۰ تا ۲۰ سناریوی واقعی بنویسید و ایجنت را بارها اجرا کنید. اجرای چندباره (N-run) برای سنجش نوسان: یک تست را ۱۰ بار اجرا کنید و درصد موفقیت را ببینید. لاگ‌گیری کامل حلقه‌ی اجرا: هر گام، هر tool call، هر observation را ذخیره کنید تا بتوانید دیباگ کنید.

هزینه‌ی ساخت ایجنت از نمونه‌ی ساده (چند خط روی API) تا پروژه‌ی تولیدی با Guardrails و monitoring متغیر است. تفاوت اصلی در لایه‌ی ارزیابی و پایش است، نه در کد ایجنت.

امنیت ایجنت: Guardrails و نقش MCP#

امنیت ایجنت در محیط تولید یعنی محدودسازی‌شده و قابل‌توقیف بودن. خودمختاری کامل فاجعه است. Guardrails سه لایه دارند: محدودسازی دسترسی ابزار، اعتبارسنجی خروجی، و سقف هزینه‌ی هر اجرا. MCP (Model Context Protocol) پروتکل متن‌بازی است که Anthropic در نوامبر ۲۰۲۴ معرفی کرد و رابط استاندارد بین ایجنت و ابزارها تعریف می‌کند.

به‌جای نوشتن adapter برای هر ابزار، یک بار MCP Server می‌سازید و هر ایجنتی که MCP پشتیبانی کند می‌تواند از آن استفاده کند.

چرا استاندارد شدن Tool Interface مهم است؟ چون بدون استاندارد، هر ایجنت باید بداند هر ابزار دقیقاً چه schema دارد. با MCP، ابزار خودش رابطش را اعلام می‌کند و ایجنت فقط مصرف می‌کند. این مشکل سازگاری Tool Interface را حل می‌کند.

الگوی Human-in-the-Loop: ایجنت قبل از اقدامات حساس تأیید انسانی می‌گیرد. حذف فایل، ارسال ایمیل، پرداخت پول — این‌ها نباید خودکار انجام شوند. ایجنت پیشنهاد می‌دهد، انسان تأیید می‌کند.

مثال ساختار Guardrails:

guardrails = {
    "allowed_tools": ["search", "read_file", "execute_python"],
    "blocked_tools": ["delete_file", "send_email", "payment"],
    "max_cost_per_run": 2.0,  # دلار
    "require_approval_for": ["write_file", "api_call"],
    "output_validation": "schema",
    "max_iterations": 20,
    "timeout_seconds": 180
}

اگر ایجنت ابزاری را صدا بزند که در allowed_tools نیست، اجرا متوقف و لاگ می‌شود. اگر خروجی schema را نقض کند، retry با بازخورد خطا انجام می‌شود.

جمع‌بندی: ایجنت بسازید یا نسازید؟#

ایجنت بسازید فقط وقتی مسیر اجرا از قبل مشخص نیست و مدل خودش باید گام بعدی را انتخاب کند. اگر مسیر قابل‌پیش‌بینی است، Workflow بسازید. اگر فقط یک بازیابی نیاز دارید، RAG کافی است. ایجنت ابزاری قدرتمند است، اما برای هر وظیفه‌ای مناسب نیست.

و اگر ایجنت ساختید، حلقه‌ی اجرا و شرایط توقف را جدی بگیرید. max_iterations، timeout و reflection-based stopping سه لایه‌ی دفاعی شما هستند. بدون آن‌ها، ایجنت در چرخه‌ی بی‌پایان می‌ماند و بودجه‌ی API را تمام می‌کند.

اگر می‌خواهید ایجنت و اتوماسیون را با ابزار عملی بسازید و از آن درآمد داشته باشید، دوره‌ی ساخت Ai Agent با N8N در کامیونیتی اسکول را بررسی کنید. ۵۱ جلسه و ۱۰ فصل دارد و از صفر تا پروژه‌ی واقعی شما را راهنمایی می‌کند.