اکثر آموزش‌های n8n، Agent Node را به‌عنوان راه‌حل کامل ایجنت‌سازی معرفی می‌کنند. در پروژه‌های واقعی، ایجنت‌های چندمرحله‌ای به ترکیب Agent Node، Switch Node و Code Node نیاز دارند. تمایز معماری بین Agent Node (الگوی ReAct، انتخاب خودکار ابزار) و Chain Node (زنجیره ثابت) تصمیم‌ساز است — نکته‌ای که در راهنماهای عمومی n8n فارسی یا انگلیسی تقریباً هیچ‌جا پیدا نمی‌شود.

n8n چیست و چرا معماری نود-محور آن را از ابزارهای ابری جدا می‌کند؟#

n8n یک ابزار اتوماسیون گردش کار (Workflow Automation) نود-محور با لایسنس Fair-code است که به‌جای سرویس ابری بسته، امکان خودمیزبانی (Self-hosted) و دسترسی به کد را می‌دهد. این تفاوت معماری، هزینه و انعطاف را نسبت به Zapier و Make کاملاً تغییر می‌دهد.

معماری نود-محور (Node-based Architecture) و مفهوم workflow#

در n8n، هر workflow از مجموعه‌ای نود (Node) ساخته می‌شود که با خطوط جهت‌دار به هم وصل‌اند. هر نود یک عمل مشخص انجام می‌دهد: دریافت داده، تبدیل، ارسال، یا تصمیم‌گیری. برخلاف ابزارهایی مثل Zapier که workflow را به‌صورت «اگر این شد، آن کار را بکن» تعریف می‌کنند، n8n اجازه می‌دهد منطق شرطی، حلقه و حالت (State) را مستقیم در گراف بچسبانید.

مفهوم workflow در n8n به‌عنوان یک DAG (جهت‌دار غیرحلقوی) اجرا می‌شود. هر نود خروجی مشخصی دارد و نود بعدی فقط از خروجی نود قبلی استفاده می‌کند. وقتی این مدل را با Code Node ترکیب کنید، عملاً یک تابع جاوااسکریپت در وسط گراف دارید — و این دقیقاً همان جایی است که n8n از یک اتوماسیون ساده به یک محیط برنامه‌نویسی تبدیل می‌شود.

مدل لایسنس Fair-code و تأثیر آن بر استفاده تجاری#

Fair-code به معنای رایگان مطلق نیست. اجازه استفاده شخصی و داخلی می‌دهد، اما برای ارائه n8n به‌عنوان سرویس به مشتریان (مدل SaaS-like) محدودیت دارد. اگر می‌خواهید n8n را به‌عنوان زیرساخت محصول خود به کاربر بدهید، باید صفحه لایسنس را دقیق بخوانید. اشتباه رایج در کلاس‌های n8n فارسی این است که شرکت‌کنندگان فرض می‌کنند «open-source یعنی هر استفاده تجاری مجاز است» — و بعد از انتشار محصول، با اخطار حقوقی مواجه می‌شوند.

تفاوت رفتاری n8n Cloud و Self-hosted در AI Nodes#

در نسخه Cloud، timeout پیش‌فرض AI Nodes کوتاه‌تر است و rate limit سخت‌گیرانه‌تری اعمال می‌شود. در Self-hosted، این مقادیر را می‌توانید در environment variables تنظیم کنید. این تفاوت در پروژه‌هایی که ایجنت چند ثانیه فکر می‌کند، حیاتی است.

پیش‌نیازهای عملی که قبل از اولین workflow باید داشته باشید#

پیش‌نیازهای عملی n8n فراتر از آنچه تبلیغات no-code وعده می‌دهند است: برای ساخت workflows قابل‌اتکا به JavaScript پایه، درک مفهوم API و Webhook، و توانایی نوشتن Expression نیاز دارید. بدون Expression، بخش عمده‌ای از workflows عملاً قابل‌ساخت نیستند و n8n به یک ابزار محدود تبدیل می‌شود.

تمایز واقعی بین no-code و low-code در n8n این است: برای کارهای ساده (مثلاً «هر ایمیل جدید را در Google Sheets ثبت کن») واقعاً بدون کد کار می‌کند. اما به‌محض اینکه بخواهید داده را فیلتر کنید، JSON را parse کنید، یا شرط پیچیده بنویسید، وارد Expression Editor می‌شوید که سینتکس آن JavaScript است.

  • متغیر، شرط if/else، و دسترسی به آبجکت‌ها در JavaScript
  • مفهوم HTTP Method (GET، POST) و ساختار JSON
  • توانایی خواندن مستندات API یک سرویس و پیدا کردن endpoint
  • آشنایی با Webhook به‌عنوان Trigger (نقطه ورود داده به workflow)

اگر این چهار مورد را ندارید، n8n را کنار بگذارید و ابتدا با آن‌ها آشنا شوید. ادعای «کاملاً بدون کدنویسی» که در تبلیغات برخی دوره‌های n8n فارسی دیده می‌شود، گمراه‌کننده است — نه چون n8n واقعاً نیاز به کد ندارد، بلکه چون بدون کد، سقف workflows شما بسیار پایین می‌ماند.

چطور n8n را با Docker روی سرور شخصی نصب کنم؟#

نصب n8n با Docker شامل اجرای یک container با پورت پیش‌فرض 5678، تنظیم volume برای ذخیره workflow‌ها، و اتصال دامنه با reverse proxy است. برای محیط production، حتماً Queue Mode را هم فعال کنید و timeout پیش‌فرض AI Nodes را بررسی کنید.

  1. سرور با حداقل 2 گیگابایت RAM تهیه کنید. Docker و Node.js روی سرور نصب باشد.
  2. با docker-compose فایل n8n را تعریف کنید. image رسمی: n8nio/n8n. پورت 5678 را map کنید.
  3. volume برای ~/.n8n تعریف کنید تا workflow‌ها بعد از restart پاک نشوند.
  4. environment variables را تنظیم کنید: N8N_HOST، N8N_PORT، WEBHOOK_URL (آدرس دامنه public).
  5. reverse proxy (Nginx یا Caddy) را روی پورت 443 تنظیم و به 5678 فوروارد کنید.
  6. برای مقیاس‌پذیری، Queue Mode را با Redis فعال کنید: EXECUTIONS_MODE=queue.

نکته عملی: در Self-hosted، timeout پیش‌فرض AI Nodes از Cloud بیشتر است. اگر با OpenAI یا Anthropic کار می‌کنید و ایجنت شما چند ثانیه اجرا می‌شود، در Cloud ممکن است timeout بخورید اما در Self-hosted کار کند. این تفاوت را در تصمیم Cloud vs Self-hosted لحاظ کنید.

ساخت اولین workflow: از Webhook Trigger تا ارسال پاسخ#

یک workflow پایه در n8n از Webhook Node شروع می‌شود، با HTTP Request Node به یک API وصل می‌شود، و با Code Node یا Expression نتیجه را فرمت‌دهی و پاسخ می‌دهد. ترتیب نودها: Webhook Trigger → HTTP Request → Code Node → Respond to Webhook.

Webhook Node نقطه ورود workflow است. وقتی درخواست HTTP به آدرس مشخص‌شده بیاید، workflow اجرا می‌شود. در تنظیمات Webhook، method را POST بگذارید و path را انتخاب کنید (مثلاً /api/agent).

HTTP Request Node برای فراخوانی API خارجی استفاده می‌شود. URL، headers و body را در پنل نود تنظیم می‌کنید. خروجی این نود یک آبجکت JSON است که در نود بعدی با {{ $json }} به آن دسترسی دارید.

Code Node جایگزین Expression برای کارهای پیچیده‌تر است. در این نود، جاوااسکریپت می‌نویسید و خروجی را return می‌کنید. اما اگر فقط فیلتر ساده یا map نیاز دارید، Expression Editor کافی است و Code Node اضافه‌بار دارد.

Respond to Webhook Node پاسخ نهایی را به caller برمی‌گرداند. بدون این نود، caller هیچ پاسخی دریافت نمی‌کند و workflow در حالت «در انتظار» می‌ماند.

Agent Node و Chain Node چه فرقی دارند و کدام را انتخاب کنم؟#

Agent Node الگوی ReAct (Reasoning and Acting) را داخلی دارد و ابزارها را به‌صورت خودکار انتخاب می‌کند. Chain Node زنجیره ثابتی دارد که ترتیب اجرا از قبل مشخص است. این تمایز، معماری کل ایجنت شما را تعیین می‌کند.

مقایسه بصری دو معماری جریان: یکی شاخه‌ای و تصمیم‌گیر (Agent) و دیگری خطی و ترتیبی (Chain) بر روی نمایشگر هولوگرافیک
Agent برای تصمیم‌گیری پویا و Chain برای اجرای ترتیبی با ریسک خطای کمتر مناسب است

الگوی ReAct و انتخاب خودکار ابزار در Agent Node#

Agent Node در n8n بر پایه الگوی ReAct کار می‌کند: مدل زبانی ابتدا فکر می‌کند (Reason)، سپس تصمیم می‌گیرد کدام Tool را صدا بزند (Act)، نتیجه را می‌بیند، و دوباره فکر می‌کند. شما Tool Node‌ها را به Agent وصل می‌کنید و Agent خودش بر اساس prompt و خروجی‌ها انتخاب می‌کند.

برای ایجنت‌های تک‌ابزاری یا کارهایی که ترتیب اجرا قابل‌پیش‌بینی نیست، Agent Node مناسب است. مثال: «بر اساس سؤال کاربر، مشخص کن آیا باید در پایگاه داده جستجو کند یا ایمیل بفرستد.»

Chain Node برای کارهای خطی و پیش‌بینی‌پذیر#

Chain Node یک زنجیره ثابت است: نود اول اجرا می‌شود، خروجی‌اش به نود دوم می‌رود، و الی آخر. ترتیب از قبل مشخص است و مدل زبانی تصمیم‌گیرنده نیست. برای کارهایی مثل «خلاصه‌سازی متن، سپس ترجمه، سپس ذخیره در Notion» که ترتیب همیشه ثابت است، Chain Node ساده‌تر و قابل‌اتکاتر است.

الگوی ترکیبی Agent + Switch Node + Code Node برای workflows چندمرحله‌ای#

در پروژه‌های واقعی، ایجنت‌های چندمرحله‌ای به ترکیب این سه نود نیاز دارند. الگوی عملیاتی: Agent Node تصمیم می‌گیرد کدام مسیر فعال شود → Switch Node بر اساس خروجی Agent، workflow را به شاخه‌های مختلف هدایت می‌کند → Code Node در هر شاخه، منطق سفارشی اجرا می‌کند.

این معماری را هیچ آموزش عمومی n8n نشان نمی‌دهد، چون در drag-and-drop خالی گم می‌شود. اما در پروژه‌هایی که ایجنت باید چند تصمیم متوالی بگیرد و هر تصمیم خروجی متفاوتی دارد، بدون Switch Node عملاً نمی‌توانید workflow قابل‌اتکا بسازید.

اتصال Tool Node و Memory Node به Agent: Tool Node‌ها (مثل HTTP Request، Google Sheets، Vector Store) را با خروجی Agent وصل می‌کنید. Memory Node (حافظه کوتاه‌مدت) هم به Agent وصل می‌شود و مکالمات قبلی را نگه می‌دارد.

اتصال به مدل‌های زبانی: OpenAI، Anthropic و Ollama#

n8n از طریق AI Nodes به OpenAI API، Anthropic و Ollama (پلتفرم اجرای مدل‌های زبانی محلی) وصل می‌شود. رفتار rate limit و timeout در Cloud و Self-hosted متفاوت است و این تفاوت در پروژه‌های عملیاتی حیاتی است.

برای OpenAI: یک credential با API Key بسازید و در AI Model Node انتخابش کنید. برای Anthropic: مشابه، با Anthropic API Key. برای Ollama: آدرس سرور محلی (مثلاً http://localhost:11434) را در نود تنظیم می‌کنید و مدل انتخاب می‌شود.

Ollama در Self-hosted کار می‌کند چون باید به شبکه محلی دسترسی داشته باشد. در n8n Cloud، اتصال به Ollama عملاً ممکن نیست مگر اینکه Ollama روی یک سرور public با HTTPS باشد.

  • rate limit: در Cloud محدودیت درخواست در دقیقه سخت‌تر اعمال می‌شود. در Self-hosted، محدودیت از سمت API provider است نه n8n.
  • timeout: اگر ایجنت شما زمان اجرا طولانی دارد، در Cloud ممکن است به محدودیت timeout بخورید. در Self-hosted، با تنظیم environment variable قابل افزایش است.
  • retry: n8n به‌صورت پیش‌فرض retry ندارد. برای API‌های ناپایدار، خودتان با Loop Node یا Error Workflow retry بنویسید.

n8n در برابر Zapier و Make: مقایسه عملیاتی#

n8n در حالت Self-hosted عملاً محدودیت تعداد workflow ندارد، اما Zapier و Make مدل execution-based pricing دارند که برای حجم کم مقرون‌به‌صرفه‌تر است. انتخاب بین این سه ابزار به حجم اجرا و نیاز به کد بستگی دارد.

معیارn8n (Self-hosted)ZapierMake
مدل هزینههزینه سرور + نگهداری (بدون محدودیت execution)پرداخت به ازای هر Task/Executionپرداخت به ازای هر Operation
دسترسی به کدکاملاً open (Code Node، JavaScript، Python)محدود (Python Code Action)محدود (Function Node)
Self-hostingبله (Docker، Kubernetes)خیرخیر
AI Native Nodesبله (Agent، Chain، Memory، Tool)محدود (AI Actions)محدود (AI Modules)
تعداد Integrationچند صد نود + HTTP سفارشیچند هزار appچند صد module

نکته: هزینه واقعی Self-hosting شامل سرور، نگهداری، آپدیت، مانیتورینگ و backup است. اگر تیم DevOps ندارید، این هزینه پنهان را در محاسبه بگذارید.

چه زمانی Zapier انتخاب بهتری است؟ وقتی workflow ساده است، حجم execution پایین است، و نمی‌خواهید سرور مدیریت کنید. چه زمانی n8n؟ وقتی به AI Agent نیاز دارید، منطق سفارشی می‌خواهید، یا حجم اجرا بالاست.

اشتباهات رایج که workflow در production می‌شکند#

سه اشتباه اصلی: استفاده از Code Node به‌جای Expression برای کارهای ساده، تکیه بر Memory Node برای حافظه بلندمدت ایجنت، و نادیده گرفتن تفاوت رفتار AI Nodes بین Cloud و Self-hosted. هر سه در production به شکست منجر می‌شوند.

Code Node به‌جای Expression — شکست مقیاس‌پذیری در Queue Mode#

وقتی workflow در Queue Mode اجرا می‌شود، هر نود در worker جداگانه اجرا می‌گردد. Code Node در هر اجرا باید کد جاوااسکریپت را compile و execute کند؛ در حجم بالا این overhead قابل‌توجه است. Expression Editor در همان process اجرا می‌شود و سبک‌تر است.

الگوی تکرارشونده در پروژه‌های واقعی: توسعه‌دهنده‌ای که از n8n Cloud به Self-hosted مهاجرت می‌کند، workflows را بدون تغییر می‌برد و بعد از فعال‌سازی Queue Mode، latency چند برابر می‌شود. علت: Code Node‌های غیرضروری که در Cloud مشکلی نداشتند.

محدودیت Memory Node و نیاز به Redis یا Vector DB خارجی#

Memory Node در n8n حافظه کوتاه‌مدت است. وقتی workflow restart شود یا container تغییر کند، حافظه از بین می‌رود. برای پروژه‌های جدی که ایجنت باید تاریخچه مکالمه را نگه دارد، باید به Redis (برای state) یا Vector DB خارجی مثل Pinecone/Chroma (برای جستجوی معنایی) وصل شوید.

نادیده گرفتن timeout و rate limit در محیط production#

در محیط development، یک درخواست OpenAI با timeout کوتاه مشکلی ندارد. در production که ایجنت چند Tool را پشت سر هم صدا می‌زند، مجموع زمان اجرا از timeout پیش‌فرض عبور می‌کند. Error Workflow بنویسید و timeout را در Self-hosted افزایش دهید.

چه زمانی n8n ابزار مناسبی نیست؟#

برای پروژه‌هایی که منطق تجاری پیچیده، state management سنگین، یا نیاز به latency بسیار پایین دارند، کدنویسی واقعی با فریمورک‌هایی مثل LangChain مستقیم بهتر است. n8n ابزار low-code است، نه جایگزین کدنویسی.

محدودیت GUI در مقایسه با کد واقعی: هر چیزی که در GUI قابل بیان نباشد، باید در Code Node نوشته شود. اگر Code Node شما بیش از چند ده خط شد، عملاً دارید در n8n کدنویسی می‌کنید اما debugging آن سخت‌تر از IDE واقعی است.

چه زمانی LangChain مستقیم جایگزین AI Nodes می‌شود؟ وقتی نیاز به custom agent loop دارید (مثلاً Agent که خودش tool جدید تعریف کند)، یا وقتی state machine چندحالتی با transition‌های پیچیده دارید. در این موارد، GUI و Expression n8n ابزار بیان کافی ندارند.

محدودیت n8n در مقیاس بسیار بزرگ: وقتی به میلیون‌ها execution در ماه می‌رسید، مدیریت queue، scaling worker‌ها و monitoring عملاً یک پروژه DevOps مستقل می‌شود. در این مقیاس، ابزارهای اختصاصی با orchestration سفارشی معمولاً مناسب‌ترند.

تصمیم واقعی برای مهاجرت از n8n به کد: وقتی بیش از نیمی از workflows شما Code Node‌های بزرگ دارند و debugging در UI n8n بیشتر از IDE وقت می‌گیرد، مهاجرت منطقی است. تا قبل از آن، سرعت ساخت workflow در n8n برتر است.

خلاصه عملی: n8n ابزار قدرتمندی برای ساخت ایجنت و اتوماسیون است، به شرطی که تمایز Agent Node و Chain Node را درک کنید، الگوی ترکیبی Agent + Switch + Code را برای کارهای چندمرحله‌ای بدانید، و اشتباهات رایج production را از قبل بشناسید. اگر می‌خواهید این الگوها را در پروژه‌های واقعی ببینید و از کسی که خودش با n8n ایجنت ساخته راهنمایی بگیرید، دوره «ساخت Ai Agent با N8N» در کامیونیتی اسکول دقیقاً همین مسیر را پوشش می‌دهد.