ساخت عامل هوش مصنوعی n8n روی VPS شخصی

عامل هوش مصنوعی n8n چیست و چه تفاوتی با زنجیره دارد

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

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

این راهنما فرض می‌کند n8n از قبل روی ماشینی که کنترل آن را در اختیار دارید و پشت HTTPS اجرا می‌شود. اگر چنین نیست، ابتدا میزبانی n8n روی Docker با یک گواهی واقعی را دنبال کنید؛ زیرا کلید API که قرار است ذخیره کنید به پشتیبان‌گیری از کلید رمزنگاری نیاز دارد و آن راهنما بر این موضوع تأکید می‌کند. برای الگوهای بدون عامل، یعنی خلاصه‌سازهای webhook و دسته‌بندی‌کننده‌های زمان‌بندی‌شده، به الگوهای گردش‌کار Claude و n8n مراجعه کنید.

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

docker compose exec n8n n8n --version

نام‌های این راهنما با آخرین نسخه پایدار n8n در July 2026 مطابقت دارند. از version 1.82.0، تمام گره‌های AI Agent به‌صورت Tools Agent اجرا می‌شوند؛ بنابراین فهرست کشویی نوع عامل قدیمی دیگر وجود ندارد.

گام 1: انتخاب محرک

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

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

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

مرحله 2: اعتبار مدل

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

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

مدل را برای هر agent انتخاب کنید، نه برای کل شرکت. یک agent با یک ابزار که چیزی را جست‌وجو و نتیجه را گزارش می‌کند، با Haiku به‌خوبی اجرا می‌شود. طبق قیمت‌گذاری در July 2026، هزینه Haiku برای هر یک میلیون token ورودی $1 و برای هر یک میلیون token خروجی $5 است. وقتی agent چند ابزار دارد و باید بین آن‌ها برنامه‌ریزی کند، به Sonnet منتقل شوید. خطایی که باید از آن جلوگیری کنید، استفاده از یک مدل ارزان است که ابزار نادرست را 4 بار فراخوانی می‌کند؛ این کار از فراخوانی یک‌باره ابزار درست با مدل گران‌تر هزینه بیشتری دارد.

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

یک نکته مهم در مستندات n8n وجود دارد که معمولاً باعث خطا می‌شود: expressionهای داخل یک زیرگره همیشه بر اساس اولین item ورودی resolve می‌شوند، نه برای هر item به‌صورت جداگانه. expressionهای مربوط به هر item را در فیلدهای prompt گره root قرار دهید.

مرحله 3: promptی که agent دریافت می‌کند

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

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

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

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 ابزار مستنداتی برای همکاران شما نیست. این فیلد تنها چیزی است که مدل هنگام تصمیم‌گیری درباره مرتبط‌بودن ابزار می‌خواند. آن را به‌صورت جمله‌ای ساده درباره خروجی بنویسید: «وضعیت فعلی بالا یا پایین و مدت قطعی یک سرویس تحت پایش را به‌صورت JSON برمی‌گرداند.»

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

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

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

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

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

گام 5: حافظه و دلیل فراموش‌کردن agent

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

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

Context Window Length به همان اندازه که برای کیفیت اهمیت دارد، یک عامل تعیین‌کننده هزینه نیز هست؛ زیرا در هر فراخوانی بعدی، هر نوبت ذخیره‌شده دوباره به‌عنوان input token ارسال می‌شود. در یک agent پرگفت‌وگو، پنجره‌ای با مقدار 20 باعث می‌شود هزینه همان پیام‌های ابتدایی را 20 بار بپردازید.

Simple Memory در یک workflow فعال production، زمانی که n8n در queue mode اجرا می‌شود، کار نمی‌کند؛ زیرا تاریخچه به‌جای یک مخزن اشتراکی، در داده‌های خود workflow ذخیره می‌شود. در یک instance دارای queue mode، به‌جای آن از زیرگره Postgres Chat Memory استفاده کنید و آن را به databaseی متصل کنید که هم فرایند اصلی و هم workerها بتوانند به آن دسترسی داشته باشند.

گام 6: پیام سیستمی

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.

عبارت «Always call the status tool before answering» در اینجا واقعاً نقش مهمی دارد. بدون آن، مدلی که تصور می‌کند پاسخ را از قبل می‌داند، ابزار را نادیده می‌گیرد و بر اساس حافظه پاسخ می‌دهد؛ اما به‌محض تغییر زیرساخت شما، این پاسخ با اطمینان نادرست خواهد بود.

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

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

مقدار آن را کاهش دهید. بیشتر عامل‌هایی که فقط از یک ابزار استفاده می‌کنند، در دو تکرار کار خود را تمام می‌کنند. محدودیت 3 یا 4، یک حلقه بی‌پایان را به خطایی مشخص تبدیل می‌کند که می‌توانید آن را در فهرست اجراها ببینید.

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

یک اجرا را از shell مشاهده کنید.

docker compose logs -f n8n

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

عامل متصل به Chat Trigger یک انسان را در چرخه دارد و آن انسان وقتی پاسخ نادرست به نظر برسد، آن را متوقف می‌کند. عامل متصل به Schedule Trigger ناظری ندارد. توضیحات کامل در کنترل هزینه عامل هوش مصنوعی در یک VPS همیشه‌روشن آمده است. در اینجا چهار تنظیم بیشتر کار را انجام می‌دهند.

• Maximum Number of Tokens را در زیرگره مدل محدود کنید تا هیچ پاسخ واحدی بیش از حد طولانی نشود.
• Max Iterations را روی کمترین تعدادی تنظیم کنید که همچنان وظیفه را کامل می‌کند.
• پاسخ‌های ابزار را کوچک نگه دارید. ابزاری که یک شیء JSON چهار هزارخطی برمی‌گرداند، تمام آن را در فراخوانی بعدی مدل و سپس در هر فراخوانی بعدی در همان اجرا وارد می‌کند.
• بررسی کنید که آیا عامل اصلاً به زمان‌بندی نیاز دارد یا نه. کاری که هر پنج دقیقه اجرا می‌شود، در هر روز 288 بار اجرا می‌شود. هر هزینه‌ای که یک اجرا داشته باشد، باید آن را در این عدد ضرب کنید.

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

FAQ

چرا گره AI Agent از اجرا شدن خودداری می‌کند؟

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

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

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

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

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

حافظه من در ویرایشگر کار می‌کند، اما در محیط production نه. چه چیزی تغییر کرده است؟

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