آموزش n8n یعنی یاد گرفتن ساختن جریان‌های کاری نودمحور که ایجنت هوش مصنوعی (AI Agent) را به‌عنوان یک گره‌ی کنترل‌شده درون workflow اجرا می‌کند. برخلاف ابزارهایی مثل AutoGPT که ایجنت خودمختارند، در n8n شما با یک canvas بصری سروکار دارید که منطق، شرط‌ها و ابزارهای ایجنت را صریحاً تعریف می‌کنید. نتیجه: اتوماسیون قابل‌پیش‌بینی، قابل‌دیباگ و قابل‌بهره‌برداری در محیط واقعی.

n8n چیست و معماری نودمحور چه فرقی با ابزارهای اتوماسیون خطی دارد#

n8n یک پلتفرم اتوماسیون نودمحور (Node-based) است که workflowها را به‌صورت گراف بصری می‌سازد. برخلاف Zapier و Make، قابلیت self-hosting دارد و منطق شرطی چندمرحله‌ای را در یک canvas واحد اجرا می‌کند. هر نود یک وظیفه‌ی مشخص دارد و داده بین نودها به‌صورت JSON جریان می‌یابد.

تفاوت ساختاری نودمحور با اتوماسیون خطی#

در Zapier یا Make، زنجیره‌ی خطی می‌سازید: Trigger → Action → Action → Action. هر مرحله فقط خروجی مرحله‌ی قبل را می‌بیند. n8n یک graph است. هر نود می‌تواند ورودی چند نود قبلی را بخواند، خروجی‌اش را به چند نود بعدی بفرستد، و با Switch یا IF Node مسیر جریان را تغییر دهد.

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

الگویی که در پروژه‌های واقعی اسکول بارها دیده شده: کاربرانی که از Zapier به n8n مهاجرت می‌کنند، ابتدا با آزادی عمل زیاد گیج می‌شوند و workflowهای بدون ساختار می‌سازند. بعد از چند هفته، الگوی «هر نود یک وظیفه» را یاد می‌گیرند و workflowهایشان قابل‌نگهداری می‌شود.

نودهای آماده و اکوسیستم community node#

n8n صدها نود آماده دارد که سرویس‌های رایج مثل Slack، Google Sheets، OpenAI، Anthropic، Telegram و Webhook را پوشش می‌دهند. علاوه بر این، جامعه‌ی توسعه‌دهندگان community nodeهایی می‌سازند که ابزارهای کم‌تکرار را پشتیبانی کنند. اگر نودی برای سرویس خاصی پیدا نکردید، می‌توانید با HTTP Request Node هر API‌ای را صدا بزنید.

Workflow، Node، Credential و Expression — چهار مفهوم پایه#

قبل از ساخت اولین workflow، این چهار مفهوم را باید در ذهن داشته باشید:

  • Workflow: کل گراف بصری — مجموعه‌ای از نودها که به هم وصل‌اند.
  • Node: یک بلوک عملکردی که یا داده می‌گیرد (Trigger)، یا تبدیل می‌کند (Transform)، یا عمل می‌کند (Action).
  • Credential: اطلاعات احراز هویت (API Key، OAuth Token) که بین workflowها قابل‌اشتراک است.
  • Expression: کد کوچک جاوااسکریپتی که داخل فیلدهای نود اجرا می‌شود و داده‌ی ورودی را تبدیل می‌کند.
معیارn8nZapierMake
معماریگراف نودمحور با شاخه‌های نامحدودزنجیره‌ی خطی Trigger-Actionگراف با محدودیت شاخه
Self-hostingبله (Docker، npm)خیرخیر
منطق شرطیSwitch، IF، Merge در هر نقطهمحدود به Filter و PathRouter و Iterator
AI AgentAI Agent Node اختصاصی با Tool CallingAI Actions (محدود)AI Modules (محدود)
هزینه در مقیاسثابت (سرور شخصی)پلکانی بر اساس Taskپلکانی بر اساس Operation

پیش‌نیازهای یادگیری n8n: بدون کدنویسی هم می‌شود شروع کرد؟#

پیش‌نیاز n8n کدنویسی نیست، فهم ساختار داده است. برای اکثر workflowها فقط در Expressionها و Function Node به JavaScript پایه نیاز دارید؛ بخش عمده‌ی workflowها بدون نوشتن یک خط کد قابل‌ساخت‌اند.

مفاهیم API و JSON که حتماً باید بلد باشید#

n8n ابزار «بدون کد» نیست، ابزار «کم‌کد» است. شما باید بفهمید که یک HTTP Request چیست، بدنه‌ی JSON چه شکلی است، و Response از کجا می‌آید. اگر این سه مفهوم را بلد باشید، عمده‌ی کار را می‌توانید در n8n انجام دهید. اگر بلد نیستید، قبل از شروع یک دوره‌ی مقدماتی API بخوانید — وگرنه هر خطا در workflow برایتان مثل جعبه‌ی سیاه می‌ماند.

Expression در برابر Function Node — چه زمانی کدام را استفاده کنید#

Expression برای تبدیل‌های ساده‌ی داخل یک فیلد است: تغییر فرمت تاریخ، چسباندن دو مقدار، یا خواندن یک فیلد از داده‌ی ورودی. Function Node برای منطق پیچیده‌تر است: حلقه روی آرایه، محاسبات چندمرحله‌ای، یا ساخت داده‌ی جدید از صفر.

اشتباه رایج: استفاده از Function Node برای کارهایی که Expression انجام می‌دهد#

الگوی تکرارشونده در پروژه‌های واقعی: کاربری که تازه با n8n آشنا شده، برای یک تبدیل ساده مثل «نام کوچک + نام خانوادگی» یک Function Node اضافه می‌کند. این کار workflow را سنگین، کند و سخت‌دیباگ می‌کند. اگر با {{ $json.firstName }} {{ $json.lastName }} حل می‌شود، Function Node اضافه نکنید.

هر Function Node یک نقطه‌ی شکست احتمالی است. هرچه تعدادشان بیشتر، سطح حمله‌ی باگ بالاتر.

ساخت اولین workflow: از Webhook Trigger تا ارسال نتیجه در Telegram#

یک workflow واقعی از پنج نود تشکیل می‌شود: Webhook Trigger برای دریافت داده، AI Agent برای پردازش، Switch Node برای مسیریابی، HTTP Request برای ارسال خروجی، و Error Workflow برای مدیریت شکست. این ترتیب نودها، الگوی پایه‌ی ایجنت‌های n8n است.

پیکربندی Webhook Trigger و تست با curl#

نود Webhook آدرشی تولید می‌کند که با POST درخواست می‌گیرد. برای تست، یک curl ساده بزنید و بدنه‌ی JSON دلخواه بفرستید. در حالت Test (دکمه‌ی Execute Workflow)، n8n فقط یک بار درخواست را می‌گیرد. برای production، workflow را Active کنید تا Webhook همیشه گوش به زنگ باشد.

تنظیم AI Agent Node با system prompt و tool calling#

AI Agent Node در n8n یک نود اختصاصی است که مدل زبانی بزرگ (LLM) را به‌عنوان مغز تصمیم‌گیرنده‌ی workflow قرار می‌دهد. شما system prompt می‌نویسید، ابزارها (Tools) را تعریف می‌کنید، و ایجنت بر اساس ورودی تصمیم می‌گیرد کدام ابزار را صدا بزند.

نکته‌ای که در آموزش‌ها کم گفته می‌شود: ایجنت فقط ابزارهایی را می‌بیند که صریحاً به آن داده‌اید. دسترسی خودسرانه ندارد. این یعنی اگر ابزار را تعریف نکرده باشید، ایجنت نمی‌تواند آن را استفاده کند — نه اینکه «دنبالش بگردد». این محدودیت، ضعف نیست؛ طراحی است.

اتصال HTTP Request Node به Telegram Bot API#

خروجی AI Agent Node یک JSON است. با یک Expression مقدار {{ $json.output }} را در بدنه‌ی HTTP Request بگذارید و آن را به آدرس Telegram Bot API بفرستید. Token ربات را در Credential ذخیره کنید، نه در متن نود.

افزودن Error Workflow به‌عنوان لایه‌ی نهایی#

در تنظیمات workflow، گزینه‌ی Error Workflow را فعال کنید. این workflow فرعی، هر شکست در workflow اصلی را می‌گیرد و می‌تواند اعلان بفرستد، لاگ بنویسد، یا ورودی را به صف بازبینی انسانی بفرستد. بدون Error Workflow، یک باگ ساده کل سیستم را بی‌صدا از کار می‌اندازد.

ترتیب نودها در این workflow:

  1. Webhook Trigger — دریافت POST با JSON
  2. AI Agent Node — پردازش با system prompt و ابزارهای تعریف‌شده
  3. Switch Node — بررسی نوع خروجی (متن، خطا، درخواست ابزار)
  4. HTTP Request Node — ارسال به Telegram
  5. Error Workflow — اعلان در صورت شکست هر مرحله

ایجنت هوش مصنوعی در n8n نه مثل AutoGPT است نه مثل LangChain#

AI Agent در n8n یک نود درون workflow با جریان کنترل‌شده‌ی بصری است؛ برخلاف AutoGPT که حلقه‌ی خودمختار دارد، ایجنت n8n فقط ابزارهایی را فراخوانی می‌کند که شما به‌صورت صریح به آن داده‌اید. هر تصمیم ایجنت یک لبه‌ی گراف قابل‌مشاهده‌ی شماست.

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

Tool Calling در n8n: تعریف ابزار، محدود کردن دسترسی، و بازگشت نتیجه#

در AI Agent Node، هر Tool یک نود فرعی است که با نام و توضیح تعریف می‌شود. ایجنت بر اساس ورودی و system prompt تصمیم می‌گیرد کدام Tool را صدا بزند. خروجی Tool به ایجنت برمی‌گردد و ایجنت ادامه می‌دهد یا پاسخ نهایی را می‌دهد. این حلقه‌ی Tool Calling داخل یک نود اتفاق می‌افتد، نه در کد.

الگوی Hub Agent — یک ایجنت مرکزی، چند workflow فرعی#

این الگو در آموزش‌های رایج n8n پوشش داده نمی‌شود. در پروژه‌های واقعی، یک workflow مرکزی (Hub) وجود دارد که AI Agent Node در آن قرار دارد. این ایجنت مرکزی با Execute Workflow Node به چند workflow فرعی (Sub-workflow) دسترسی دارد. هر Sub-workflow یک وظیفه‌ی مشخص دارد: یکی ایمیل می‌فرستد، یکی در CRM جست‌وجو می‌کند، یکی گزارش تولید می‌کند. ایجنت مرکزی تصمیم می‌گیرد کدام Sub-workflow اجرا شود.

مزیت این الگو: هر Sub-workflow مستقل قابل‌تست، قابل‌نگهداری و قابل‌بازیافت است. اگر یک ابزار تغییر کند، فقط آن Sub-workflow را بازنویسی می‌کنید، نه کل سیستم را.

اتصال به OpenAI، Anthropic و Ollama (Local AI)#

n8n یک Ollama Node اختصاصی دارد. کافی است URL سرور Ollama را در Credential وارد کنید و مدل مورد نظر را انتخاب کنید. برای مدل‌های local در شبکه‌ی داخلی، Ollama را روی همان سرور یا شبکه‌ی localhost اجرا کنید.

مزیت Ollama در n8n: داده از سرور شما خارج نمی‌شود و هزینه‌ی API صفر است. البته این یعنی GPU هم باید از شما باشد — که برای مدل‌های بزرگ، چالش سخت‌افزاری‌اش جدی‌تر از هزینه‌ی API است.

تفاوت ساختاری ایجنت n8n با LangChain و CrewAI#

LangChain و CrewAI کتابخانه‌های کدنویسی‌اند. شما با Python یا JS ایجنت می‌سازید و دیپلوی می‌کنید. n8n یک پلتفرم بصری است: ایجنت داخل canvas ساخته می‌شود، لاگ‌ها در UI قابل‌مشاهده‌اند، و هر تغییر بدون باز‌دیپلوی اعمال می‌شود. برای تیم‌هایی که توسعه‌دهنده‌ی اختصاصی ندارند، n8n مانع اصلی ورود به ایجنت‌سازی را برمی‌دارد.

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

سه اشتباه ساختاری — Paired Item نادرست، جابه‌جایی Expression و Function Node، و مدیریت خطا با IF Node به‌جای Error Workflow — مسئول بخش عمده‌ای از خرابی‌های workflow در محیط واقعی‌اند. این اشتباهات در حالت Test دیده نمی‌شوند و فقط در production خودشان را نشان می‌دهند.

خطای Paired Item: چرا downstream nodes داده‌ی نادرست می‌گیرند#

رایج‌ترین باگ مخفی در workflowهای AI Agent. وقتی یک نود (مثلاً Split Out یا Merge) چند آیتم تولید می‌کند، هر آیتم باید به آیتم اصلی خود برگردد. اگر این بازگشت تنظیم نشده باشد، نودهای بعدی داده‌ی آیتم اشتباه را می‌خوانند. نتیجه: ایجنت بر اساس ورودی نادرست تصمیم می‌گیرد و خروجی بی‌ربط تولید می‌کند.

الگوی تکرارشونده: کاربر AI Agent را با یک Input Node ترکیب می‌کند که چند آیتم تولید می‌کند. ایجنت برای هر آیتم اجرا می‌شود، اما خروجی‌ها به‌هم ریخته به نود بعدی می‌روند. راه‌حل: در تنظیمات نودهای Split و Merge، گزینه‌ی «Keep Paired Items» را فعال کنید.

مدیریت خطا با Error Workflow به‌جای try-catch دستی#

برخی کاربران با IF Node سعی می‌کنند خطا را بگیرند. IF Node خروجی نود قبلی را بررسی می‌کند، اما اگر نود قبلی اصلاً اجرا نشود (مثلاً Timeout)، IF Node هم اجرا نمی‌شود. Error Workflow یک لایه‌ی جدا است که هر شکست در هر نقطه‌ی workflow را می‌گیرد، حتی اگر نود خطا اصلاً خروجی ندهد.

Sub-workflow و الگوهای سازمان‌دهی برای workflowهای بزرگ#

وقتی workflow شما به بیش از 15 نود می‌رسد، درک و نگهداری آن به‌صورت تک‌فایل دشوار می‌شود. الگوی پیشنهادی: هر 5 تا 7 نود که یک وظیفه‌ی منطقی دارند را در یک Sub-workflow بگذارید. workflow اصلی فقط نودهای اتصال و تصمیم‌گیری را دارد. این کار debugging را از «جست‌وجو در 30 نود» به «بررسی 5 نود در هر Sub-workflow» کاهش می‌دهد.

امنیت Credential در محیط production#

Credentialها در database ذخیره می‌شوند. اگر سرور n8n بدون احراز هویت در دسترس شبکه باشد، هر کسی می‌تواند workflow اجرا کند و مقادیر Credential را در لاگ‌ها ببیند. در production: n8n را پشت reverse proxy با Basic Auth یا OAuth بگذارید. Credential را هرگز در Expression یا Function Node به‌صورت متنی hard-code نکنید.

n8n Cloud یا Self-hosted؟ مقایسه‌ی واقعی هزینه و مسئولیت#

Self-hosting n8n روی سرور شخصی رایگان نیست؛ زمان‌مصرف‌شده برای آپدیت امنیتی، مدیریت SSL، بکاپ و مانیتورینگ هزینه‌ی پنهانی است که در مقایسه‌های «رایگان vs پولی» نادیده گرفته می‌شود. برای تیم‌های بدون DevOps، این هزینه‌ها می‌توانند Cloud را منطقی‌تر کنند.

نصب با Docker و npm — گام‌های عملی#

سریع‌ترین راه شروع، Docker است:

  1. دستور docker run -it -p 5678:5678 n8nio/n8n را اجرا کنید.
  2. مرورگر را روی localhost:5678 باز کنید.
  3. حساب اولیه بسازید و وارد شوید.
  4. برای production: Nginx یا Caddy به‌عنوان reverse proxy تنظیم کنید، SSL با Let's Encrypt بگیرید، و volume برای persistent data تعریف کنید.

نصب با npm هم ممکن است (دستور npm install n8n -g)، اما برای محیط‌هایی که Docker دارند، Docker ساده‌تر و قابل‌بازتولیدتر است.

چه زمانی Cloud منطقی‌تر است و چه زمانی Self-hosted توجیه دارد#

Self-hosted توجیه دارد وقتی: حجم workflowها بالاست و هزینه‌ی Cloud پلکانی به‌صرفه نمی‌شود، داده‌ی حساس دارید که نباید از سرور شما خارج شود، یا به Ollama و مدل‌های local نیاز دارید.

Cloud منطقی‌تر است وقتی: تیم DevOps ندارید، uptime برایتان حیاتی است، و می‌خواهید روی ساخت workflow تمرکز کنید نه روی نگه‌داری سرور.

چه زمانی n8n انتخاب اشتباهی است#

برای اتوماسیون‌های تک‌مرحله‌ای با کمتر از 3 نود، تیم‌هایی که اصلاً با مفاهیم API آشنا نیستند، و نیاز به SLA بالا بدون تیم DevOps، n8n بیش از حد پیچیده و پرریسک است. ابزار اشتباه، حتی اگر قدرتمند باشد، وقت و انرژی تیم را می‌بلعد.

اتوماسیون ساده — Zapier سریع‌تر به نتیجه می‌رسد#

اگر نیازتان «وقتی فرم پر شد، ایمیل بفرست» است، n8n overhead بیشتری دارد. Zapier در 5 دقیقه setup می‌شود. n8n در همان حالت، شما را مجبور می‌کند Webhook، Credential، و حداقل دو نود را پیکربندی کنید. این overhead برای اتوماسیون تک‌مرحله‌ای توجیه ندارد.

تیم بدون دانش API — overhead یادگیری n8n توجیه ندارد#

n8n ابزار «بدون کد» نیست، ابزار «کم‌کد» است. اگر هیچ‌کس در تیمتان نمی‌داند HTTP Status Code چیست یا JSON چه شکلی است، overhead یادگیری n8n به‌جای حل مشکل، خودش تبدیل به مشکل می‌شود. در این حالت، ابزارهای ساده‌تر مثل Zapier یا حتی نودهای آماده‌ی Make مسیر کوتاه‌تری دارند.

نیاز به uptime بالا بدون تیم فنی#

Self-hosting یعنی شما مسئول uptime هستید. اگر سرور افتد، workflowها متوقف می‌شوند و کسی جز شما نمی‌داند. بدون تیم فنی، این ریسک عملیاتی را به‌عهده نگیرید. n8n Cloud یا Make با SLA مشخص، این مسئولیت را از دوش شما برمی‌دارند.

نکته‌ی عملی: اگر الان در مرحله‌ی تصمیم‌گیری هستید و n8n برای شما منطقی به‌نظر می‌رسد، الگوی Hub Agent و خطای Paired Item را از همان شروع workflow جدی بگیرید. این دو موضوع، مرز بین setup آماتور و production را تعیین می‌کنند و در اکثر آموزش‌های رایج n8n اصلاً اشاره نمی‌شوند.

اگر می‌خواهید این الگوها را در یک مسیر ساختاریافته یاد بگیرید، دوره‌ی «ساخت Ai Agent با N8N» در کامیونیتی N8N اسکول دقیقاً روی همین موضوعات — ایجنت‌سازی، Tool Calling، Hub Agent و دیباگ workflowهای AI — تمرکز دارد.