آموزش ساخت AI Agent در n8n روی سرور شخصی (VPS)

ماهیت یک AI agent در n8n و تفاوت آن با chain

یک AI agent در n8n، یک نود واحد به نام AI Agent است که نودهای فرعی به آن متصل شده‌اند: یک مدل چت، یک یا چند ابزار، و یک حافظه اختیاری. شما هدف خود را به زبان ساده بیان می‌کنید و مدل تصمیم می‌گیرد که کدام ابزارها را و به چه ترتیبی فراخوانی کند تا بتواند پاسخ دهد. تمام موارد زیر، پیکربندی پیرامون همین ایده واحد است.

یک chain دقیقاً برعکس عمل می‌کند. در یک Basic LLM Chain، شما مراحل را تعیین می‌کنید و مدل فقط متن را تکمیل می‌کند. در یک agent، مدل مراحل را تعیین می‌کند؛ بنابراین یک پرسش مشابه ممکن است امروز یک فراخوانی مدل هزینه داشته باشد و فردا نه فراخوانی. همین تفاوت واحد، تمام تنظیمات این راهنما را هدایت می‌کند.

این راهنما فرض می‌کند که n8n هم‌اکنون پشت HTTPS روی ماشینی که کنترل آن را در دست دارید، در حال اجراست. اگر چنین نیست، با self-hosting n8n on Docker with a real certificate شروع کنید، زیرا API key که قصد ذخیره آن را دارید، به پشتیبان‌گیری از encryption-key نیاز دارد که آن راهنما بر آن تأکید کرده است. برای الگوهای غیر-agent، مانند خلاصه‌سازهای webhook و دسته‌بندی‌کننده‌های زمان‌بندی‌شده، به Claude and n8n workflow patterns مراجعه کنید.

پیش از اعتماد به هر نام فیلد در اینجا، نسخه خود را بررسی کنید، زیرا n8n نودهای AI را به‌طور مکرر تغییر می‌دهد.

docker compose exec n8n n8n --version

نام‌های موجود در این راهنما با نسخه stable فعلی n8n تا ژوئیه 2026 مطابقت دارد. از نسخه 1.82.0 به بعد، هر نود AI Agent به‌عنوان یک Tools Agent اجرا می‌شود، بنابراین منوی کشویی قدیمی برای انتخاب نوع agent دیگر وجود ندارد.

گام 1: انتخاب ماشه (Trigger)

برای یک عامل گفتگو (Conversational Agent)، یک گره Chat Trigger اضافه کنید. گزینه Make Chat Publicly Available را در حین ساخت غیرفعال نگه دارید تا فقط پنل چت ویرایشگر به آن دسترسی داشته باشد. پس از تکمیل عامل و تصمیم‌گیری در مورد احراز هویت، آن را فعال کنید.

گره Chat Trigger فیلدی با نام chatInput را به عامل تحویل می‌دهد. این نام در گام 3 اهمیت دارد و اشتباه در آن، رایج‌ترین خطای اولیه است.

برای یک عامل بدون نظارت (Unattended Agent)، از یک گره Schedule Trigger یا Webhook استفاده کنید. هیچ‌کدام از این‌ها chatInput تولید نمی‌کنند، بنابراین باید prompt را خودتان بنویسید.

گام 2: اعتبارنامه مدل

یک گره AI Agent را روی بوم (canvas) قرار دهید. n8n بلافاصله یک اتصال‌دهنده خالی Chat Model را در زیر آن نمایش می‌دهد. یک زیر-گره Anthropic Chat Model را به آن متصل کنید.

اعتبارنامه را از کنسول Anthropic در آدرس platform.claude.com، بخش Settings و سپس API Keys ایجاد کنید. کلید فقط یک‌بار نمایش داده می‌شود. هزینه استفاده از API بر اساس توکن محاسبه می‌شود و از اشتراک Claude.ai جداست؛ بنابراین پیش از اولین اجرا، باید تنظیمات پرداخت (billing) در حساب کاربری انجام شده باشد.

مدل را بر اساس هر عامل (agent) انتخاب کنید، نه بر اساس شرکت. یک عامل تک‌ابزاری که چیزی را جستجو کرده و گزارش می‌دهد، به‌خوبی با مدل Haiku کار می‌کند که تا ژوئیه 2026، هزینه آن 1 دلار به ازای هر میلیون توکن ورودی و 5 دلار به ازای هر میلیون توکن خروجی است. هنگامی که عامل چندین ابزار دارد و باید بین آن‌ها برنامه‌ریزی کند، از مدل Sonnet استفاده کنید. خطایی که باید از آن اجتناب کنید، استفاده از یک مدل ارزان است که چهار بار ابزار اشتباه را فراخوانی می‌کند؛ چرا که هزینه آن از یک مدل گران‌قیمت که یک‌بار ابزار درست را فراخوانی می‌کند، بیشتر خواهد بود.

گزینه Maximum Number of Tokens را در تنظیمات زیر-گره تعیین کنید. این گزینه طول هر پاسخ تولیدشده توسط مدل را محدود می‌کند. اگر این مقدار روی پیش‌فرض بزرگ باقی بماند، یک اجرای اشتباه می‌تواند پاسخی بسیار طولانی تولید کرده و هزینه زیادی برای شما ایجاد کند.

یک نکته مهم از مستندات n8n که معمولاً باعث سردرگمی می‌شود: عبارت‌ها (expressions) در داخل یک زیر-گره همیشه بر اساس اولین آیتم ورودی ارزیابی می‌شوند و نه به ازای هر آیتم. عبارت‌های مربوط به هر آیتم را در فیلدهای prompt گره اصلی قرار دهید.

گام 3: پرامپتی که ایجنت دریافت می‌کند

گره AI Agent را باز کنید. پارامتر Prompt دارای دو تنظیم است.

• گزینه Take from previous node automatically انتظار یک فیلد ورودی با نام chatInput را دارد. این گزینه برای استفاده پس از یک Chat Trigger مناسب است.
• گزینه Define below فیلد Prompt (User Message) را نمایش می‌دهد که می‌توانید در آن متن ثابت یا یک expression بنویسید. این گزینه برای استفاده پس از یک Schedule Trigger یا گره Webhook مناسب است.

هنگامی که یک گره Webhook در ابتدای مسیر قرار دارد، بدنه درخواست POST در $json.body قرار می‌گیرد، بنابراین فیلد پرامپت به شکل زیر خواهد بود.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

گام 4: اختصاص یک ابزار به ایجنت

یک نود AI Agent بدون زیر-نود ابزار، اجرا نمی‌شود. با یک ابزار شروع کنید، چرا که یک ابزارِ کارآمد، بیش از چهار ابزارِ ناقص‌تنظیم‌شده به شما آموزش می‌دهد.

یک نود HTTP Request را به کانکتور Tool ایجنت متصل کنید. آن را دقیقاً مشابه یک نود HTTP Request معمولی پیکربندی کنید، سپس ابتدا آن endpoint را از طریق shell تست کنید.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

اگر دستور curl خطایی برگرداند یا یک صفحه ورود HTML نمایش دهد، ایجنت نیز با شکست مواجه خواهد شد؛ در حالی که خطا ممکن است شبیه به مشکل مدل به نظر برسد، اما در واقع یک مشکل URL یا احراز هویت است. آن را در shell اصلاح کنید، نه در نود.

فیلد Description در ابزار، مستنداتی برای همکاران شما نیست. این تنها چیزی است که مدل هنگام تصمیم‌گیری برای مرتبط بودن ابزار می‌خواند. آن را به صورت یک جمله ساده درباره خروجی بنویسید: "Returns the current up or down state and the downtime duration for one monitored service, as JSON."

برای اینکه به مدل اجازه دهید بخشی از درخواست را پر کند، از عبارت $fromAI() استفاده کنید. این قابلیت فقط در ابزارهای متصل به نود AI Agent کار می‌کند و در ابزار Code در دسترس نیست.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

آرگومان‌ها شامل key، سپس یک description اختیاری، type و defaultValue هستند. کلید باید بین 1 تا 64 کاراکتر باشد و از حروف، ارقام، آندرلاین و خط تیره استفاده کند. نوع (type) یکی از مقادیر string، number، boolean یا json است و مقدار پیش‌فرض آن string می‌باشد. یک فراخوانی کامل‌تر به این شکل است.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

کلید یک راهنما است، نه ارجاع به داده‌های موجود. $fromAI('service') فیلدی به نام service را از جایی نمی‌خواند. این به مدل می‌گوید "مقداری تولید کن و نام آن را service بگذار"، و مدل برای یافتن آن، گفتگو، داده‌های ورودی و نتایج سایر ابزارها را بررسی می‌کند. در یک گردش‌کار چت، ممکن است به سادگی از کاربر بپرسد.

جستجوی وب معمولاً دومین ابزار است و از آنجایی که این هم صرفاً یک HTTP endpoint دیگر است، می‌توانید همین نود را به نمونه SearXNG خودتان به جای یک API جستجوی پولی متصل کنید، مشروط بر اینکه با هر صفحه‌ای که برمی‌گرداند به عنوان متن غیرقابل‌اعتمادی که اکنون درون prompt شما قرار دارد، برخورد کنید.

گام 5: حافظه و دلیل فراموشی ایجنت

بدون یک زیر-گره (sub-node) حافظه، هر پیام از صفر شروع می‌شود. یک زیر-گره Simple Memory را متصل کنید تا مکالمه‌های اخیر را نگه دارد.

این گره دو پارامتر دارد. Session Key تعیین می‌کند که این کدام مکالمه است، بنابراین دو کاربر با کلیدهای متفاوت، تاریخچه‌های جداگانه‌ای خواهند داشت. Context Window Length مشخص می‌کند که چند تعامل قبلی در پرامپت بازپخش شوند.

پارامتر Context Window Length هم یک تنظیم‌کننده هزینه است و هم یک تنظیم‌کننده کیفیت، زیرا هر نوبتِ به‌خاطر سپرده‌شده، در هر فراخوانی بعدی به‌عنوان توکن‌های ورودی دوباره ارسال می‌شود. یک پنجره با اندازه 20 برای یک ایجنت پرحرف به این معنی است که شما هزینه پیام‌های اولیه را بیست بار پرداخت می‌کنید.

قابلیت Simple Memory در یک گردش‌کار عملیاتی (production) فعال که n8n در حالت queue mode اجرا می‌شود کار نمی‌کند، زیرا تاریخچه به‌جای یک فضای ذخیره‌سازی مشترک، در داده‌های خودِ گردش‌کار باقی می‌ماند. در نمونه‌ای که در حالت queue mode است، به‌جای آن از زیر-گره Postgres Chat Memory استفاده کنید و آن را به پایگاه‌داده‌ای متصل کنید که هم پردازش اصلی و هم workerها به آن دسترسی داشته باشند.

گام 6: پیام سیستم (System Message)

گزینه‌های (Options) ایجنت را باز کرده و یک System Message اضافه کنید. این بخش محل قرارگیری شرح وظایف است و تأثیرگذارترین متن در کل گردش کار محسوب می‌شود.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

دستور "همیشه پیش از پاسخ‌دهی، ابزار وضعیت (status tool) را فراخوانی کن" در اینجا نقش کلیدی ایفا می‌کند. بدون این دستور، مدلی که تصور می‌کند پاسخ را می‌داند، از ابزار صرف‌نظر کرده و بر اساس حافظه خود پاسخ می‌دهد؛ پاسخی که به محض تغییر زیرساخت شما، با اطمینان کامل اشتباه خواهد بود.

چرا عامل (agent) در حلقه می‌افتد و چه چیزی آن را متوقف می‌کند

همچنین در بخش Options، گزینه‌ای به نام Max Iterations وجود دارد که مقدار پیش‌فرض آن 10 است. هر تکرار (iteration) شامل یک فراخوانی مدل به اضافه نتیجه ابزار (tool) است که به context بازگردانده می‌شود. بنابراین، یک اجرای واحد عامل، تنها یک فراخوانی API نیست، بلکه می‌تواند تا 10 فراخوانی باشد و هر کدام از آن‌ها کل مکالمهٔ در حال رشد را به عنوان ورودی حمل می‌کنند.

این مقدار را کاهش دهید. اکثر عامل‌های تک‌ابزاری در 2 تکرار به پایان می‌رسند و محدودیت 3 یا 4 تکرار، یک حلقهٔ بی‌پایان را به یک شکست تمیز تبدیل می‌کند که می‌توانید در لیست اجرا مشاهده کنید.

هنگامی که در حال دیباگ هستید، گزینه Return Intermediate Steps را فعال کنید. در این صورت، خروجی نهایی شامل فراخوانی‌های ابزاری است که عامل در طول مسیر انجام داده است؛ این همان روشی است که می‌توانید تفاوت بین «مدل هرگز ابزار را فراخوانی نکرد» و «ابزار هیچ نتیجه مفیدی برنگرداند» را تشخیص دهید. پیش از عملیاتی کردن (go live)، این گزینه را دوباره غیرفعال کنید، زیرا این مراحل برای کاربر نهایی نویز محسوب می‌شوند.

اجرای یک عملیات را از طریق shell مشاهده کنید.

docker compose logs -f n8n

جلوگیری از مصرف بی‌رویه توسط agentهای بدون نظارت

پشت یک Chat Trigger، یک انسان در جریان کار agent حضور دارد و اگر پاسخ نادرست به نظر برسد، آن را متوقف می‌کند. پشت یک Schedule Trigger کسی نظارت نمی‌کند. آنچه در اینجا باید کنترل کنید، هزینه مصرف مدل است، نه هزینه license؛ زیرا nodeهای agent، tool و memory همگی در نسخه رایگان self-hosted کار می‌کنند و قابلیت‌هایی که به کلید پولی نیاز دارند، عمدتاً مربوط به تیم و governance هستند. توضیح کامل در کنترل هزینه AI agent روی یک VPS همیشه‌روشن آمده است. چهار تنظیم، بیشتر این کنترل را انجام می‌دهند.

• مقدار Maximum Number of Tokens را در sub-node مدل محدود کنید تا هیچ پاسخ تکی نتواند بیش از حد طولانی شود.
• مقدار Max Iterations را روی کوچک‌ترین عددی تنظیم کنید که همچنان وظیفه را به پایان می‌رساند.
• پاسخ‌های ابزارها (tool responses) را کوچک نگه دارید. ابزاری که یک JSON blob با 4,000 خط برمی‌گرداند، تمام آن را در فراخوانی بعدی مدل و سپس در تمام فراخوانی‌های بعدی همان اجرا قرار می‌دهد.
• بررسی کنید که آیا agent واقعاً به زمان‌بندی (schedule) نیاز دارد یا خیر. شغلی که هر پنج دقیقه اجرا می‌شود، در روز 288 بار فعال می‌گردد. هزینه هر بار اجرا، عددی است که باید در این تعداد ضرب کنید.

هنگام اعمال تغییرات، workflow را غیرفعال کنید. یک workflow فعال با Schedule Trigger، همواره بر اساس نسخه‌ای که در n8n ذخیره شده اجرا می‌شود، که لزوماً همان نسخه‌ای نیست که روی صفحه نمایش خود می‌بینید.

FAQ

چرا نود AI Agent من اجرا نمی‌شود؟

نود AI Agent به یک ساب-نود مدل چت و حداقل یک ساب-نود ابزار (tool) نیاز دارد. نودی که مدل دارد اما ابزاری به آن متصل نیست، پیش از برقراری هرگونه تماس API با خطا مواجه می‌شود. یک ابزار، حتی یک ابزار ساده، به آن متصل کنید و دوباره اجرا نمایید.

ایجنت پاسخ می‌دهد، اما هرگز ابزار من را فراخوانی نمی‌کند. مشکل چیست؟

تقریباً همیشه مشکل از فیلد Description ابزار است. مدل‌ها ابزارها را با خواندن این توضیحات انتخاب می‌کنند؛ بنابراین توضیحی مانند "HTTP Request" هیچ اطلاعاتی درباره زمان استفاده از ابزار به مدل نمی‌دهد. آن را بازنویسی کنید تا مشخص شود چه داده‌ای بازگردانده می‌شود و در چه شرایطی مفید است؛ سپس یک خط به System Message اضافه کنید و به ایجنت دستور دهید که پیش از پاسخ‌دهی، آن ابزار را فراخوانی کند.

چرا هزینه یک پرسش مشابه در هر بار اجرا متفاوت است؟

زیرا مدل تعداد گام‌ها (steps) را انتخاب می‌کند. هر تکرار، کل مکالمه تا آن لحظه—شامل خروجی‌های قبلی ابزار—را مجدداً ارسال می‌کند؛ بنابراین اجرایی که چهار تکرار نیاز دارد، بسیار بیشتر از چهار برابرِ یک فراخوانی تکی هزینه خواهد داشت. Max Iterations سقف این تکرارها را تعیین می‌کند و Return Intermediate Steps به شما نشان می‌دهد که یک اجرای خاص واقعاً از چند گام استفاده کرده است.

حافظه (Memory) من در ویرایشگر کار می‌کند اما در محیط عملیاتی (production) خیر. چه چیزی تغییر کرده است؟

بررسی کنید که آیا این instance در حالت queue mode اجرا می‌شود یا خیر. Simple Memory تاریخچه را در داده‌های اجرایی خودِ ورک‌فلو ذخیره می‌کند که با انتقال به یک worker process مجزا از بین می‌رود؛ بنابراین یک ورک‌فلو فعال در محیط عملیاتی آن را از دست می‌دهد. از ساب-نود Postgres Chat Memory استفاده کنید که تاریخچه را در دیتابیسی که تمام workerها به آن دسترسی دارند، نگهداری می‌کند.