نود AI Agent در N8N

نود AI Agent در n8n برای ساخت «عامل‌های هوشمند» (Agent) استفاده می‌شود؛ یعنی یک مدل هوش مصنوعی که فقط پاسخ متنی ساده نمی‌دهد، بلکه می‌تواند بر اساس هدف شما تصمیم بگیرد، از ابزارها (Tools) استفاده کند، چند مرحله فکر کند، داده جمع‌آوری کند و در نهایت یک خروجی قابل استفاده برای ادامه ورکفلو تولید کند. این نود برای اتوماسیون‌های واقعی مثل پشتیبانی مشتری، تحلیل تیکت‌ها، تولید گزارش و کارهای چندمرحله‌ای بسیار کاربردی است.

معرفی نود در N8N

کارکرد نود

AI Agent یک «هماهنگ‌کننده هوشمند» است: شما هدف و قوانین را تعریف می‌کنید، سپس Agent می‌تواند با کمک مدل‌های LLM و ابزارهای متصل، کار را قدم‌به‌قدم جلو ببرد. تفاوت اصلی آن با یک نود چت ساده این است که Agent می‌تواند از ابزارها برای انجام کارهای عملی (مثل جستجو در داده، خواندن/نوشتن در سرویس‌ها، فراخوانی API) استفاده کند و خروجی را ساختارمند تحویل دهد.

دسته‌بندی نود

Action (عملیاتی): چون خروجی تولید می‌کند و می‌تواند کار را پیش ببرد.
در عمل، به‌عنوان یک نود AI/LLM Orchestration هم شناخته می‌شود (هماهنگی بین مدل و ابزارها).

اهمیت در ورکفلوها

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

موارد استفاده

سناریوهای واقعی

پشتیبانی مشتری (Helpdesk Agent): پیام مشتری را می‌گیرد، نوع مشکل را تشخیص می‌دهد، از پایگاه دانش یا دیتابیس جواب پیدا می‌کند، پاسخ پیشنهادی می‌سازد و در سیستم تیکت ثبت می‌کند.
دسته‌بندی و اولویت‌بندی تیکت‌ها: از متن تیکت، «موضوع»، «شدت»، «واحد مسئول» و «SLA» پیشنهادی را استخراج می‌کند.
تحلیل لاگ و رخداد: خطاهای سرویس را می‌گیرد، الگوهای تکرارشونده را پیدا می‌کند، ریشه احتمالی را پیشنهاد می‌دهد و یک Incident در ابزار مانیتورینگ/مدیریت پروژه ایجاد می‌کند.
استخراج اطلاعات از متن‌های طولانی: از قرارداد، ایمیل یا صورتجلسه، آیتم‌های کلیدی (تعهدات، تاریخ‌ها، مبلغ‌ها) را ساختارمند در JSON استخراج می‌کند.
ساخت گزارش مدیریتی: داده فروش/مارکتینگ را از چند منبع جمع می‌کند، تحلیل و خلاصه می‌دهد و خروجی را برای ارسال در ایمیل یا Slack آماده می‌کند.

ترکیب با نودهای دیگر برای ورکفلوهای عملی

Webhook Trigger + AI Agent + Respond to Webhook: ساخت یک API ساده که با یک درخواست، تحلیل/پاسخ هوشمند برگرداند.
Gmail/IMAP Trigger + AI Agent + Google Sheets / Notion: دریافت ایمیل‌ها، استخراج فیلدها، ثبت در دیتابیس.
Zendesk/Jira + AI Agent + IF / Switch: تصمیم‌گیری هوشمند برای مسیر تیکت‌ها و تخصیص به تیم‌ها.
HTTP Request + AI Agent: Agent می‌تواند خروجی API را تحلیل کند و تصمیم عملی بگیرد (مثلاً تشخیص ریسک، پیشنهاد اقدام بعدی).
Vector Store / Database + AI Agent: پیاده‌سازی RAG (بازیابی اطلاعات) برای پاسخ دقیق‌تر و مبتنی بر داده داخلی.

پارامترها و تنظیمات

نام‌گذاری دقیق فیلدها ممکن است بسته به نسخه n8n تغییرات جزئی داشته باشد، اما مفهوم و کاربرد تنظیمات زیر در نود AI Agent ثابت است.

فهرست پارامترهای اصلی

Model (مدل) | نوع داده: انتخابی (Dropdown) | کاربرد: انتخاب ارائه‌دهنده و مدل LLM برای Agent | مثال: انتخاب یک مدل مثل GPT-4.x یا Claude یا مدل‌های OpenAI-compatible.
نکته عملی: اگر خروجی دقیق و ساختارمند می‌خواهید، مدلی را انتخاب کنید که در Structured Output/JSON عملکرد خوبی دارد.
System Instructions / Agent Instructions (دستورالعمل‌های عامل) | نوع داده: متن | کاربرد: تعریف نقش، قوانین، محدودیت‌ها و سبک خروجی Agent | مثال:
«تو یک کارشناس پشتیبانی هستی. فقط بر اساس داده‌های ورودی و ابزارهای مجاز پاسخ بده. خروجی را به JSON با کلیدهای category, priority, reply تولید کن.»
User Message / Prompt (پیام کاربر) | نوع داده: متن (قابل Expression) | کاربرد: متن اصلی مسئله که معمولاً از آیتم ورودی می‌آید | مثال: قرار دادن متن تیکت: {{$json.body}}
نکته عملی: بهتر است همراه پیام، زمینه (context) هم بدهید: نام محصول، زبان پاسخ، سیاست‌های شرکت، محدودیت‌ها.
Tools (ابزارها) | نوع داده: لیست/مجموعه | کاربرد: تعیین ابزارهایی که Agent اجازه دارد صدا بزند (مثل HTTP، دیتابیس، سرچ داخلی، نودهای دیگر) | مثال: افزودن ابزار «HTTP Request» برای دریافت اطلاعات سفارش از API.
نکته مهم: هر ابزاری که اضافه می‌کنید، سطح دسترسی Agent را افزایش می‌دهد؛ فقط ابزارهای ضروری را فعال کنید.
Tool Instructions (راهنمای استفاده از ابزارها) | نوع داده: متن | کاربرد: توضیح می‌دهد Agent چه زمانی و چگونه از ابزارها استفاده کند | مثال: «برای بررسی وضعیت سفارش، فقط از ابزار GetOrderStatus استفاده کن و با orderId کاربر درخواست بده.»
Memory (حافظه) | نوع داده: انتخابی | کاربرد: نگهداری مکالمه/زمینه در چند مرحله یا چند اجرای مرتبط | مثال: Memory مبتنی بر Session برای یک چت چندمرحله‌ای.
نکته عملی: اگر ورکفلو شما تکرارشونده است و ورودی‌های مستقل دارد (مثل پردازش ایمیل‌های جداگانه)، حافظه را محدود یا غیرفعال کنید تا اطلاعات آیتم‌های قبلی قاطی نشود.
Output Format (فرمت خروجی) | نوع داده: انتخابی | کاربرد: تعیین اینکه خروجی متن آزاد باشد یا ساختارمند | مثال: انتخاب Structured/JSON و تعریف اسکیمای خروجی.
نکته مهم: اگر قرار است خروجی وارد نودهای بعدی مثل IF/Switch/Set شود، خروجی ساختارمند انتخاب کنید.
JSON Schema / Structured Output Schema (اسکیما) | نوع داده: شیء/متن | کاربرد: تعریف دقیق فیلدهای مورد انتظار | مثال عملی:
{"type":"object","properties":{"category":{"type":"string"},"priority":{"type":"string","enum":["low","medium","high"]},"reply":{"type":"string"}},"required":["category","priority","reply"]}
Temperature (خلاقیت) | نوع داده: عدد | کاربرد: میزان تصادفی بودن پاسخ | مثال: 0.2 برای خروجی پایدار، 0.7 برای متن‌های خلاقانه.
نکته عملی: برای استخراج داده و تصمیم‌گیری، دما را پایین نگه دارید؛ برای تولید متن مارکتینگ، می‌تواند بالاتر باشد.
Max Tokens (حداکثر توکن خروجی) | نوع داده: عدد | کاربرد: محدودیت طول خروجی | مثال: 600 برای پاسخ‌های متوسط.
نکته مهم: اگر خروجی شما JSON است، توکن کم باعث نیمه‌کاره ماندن JSON و خطا در پارس می‌شود.
Timeout (مهلت اجرا) | نوع داده: عدد/زمان | کاربرد: جلوگیری از طولانی شدن اجرای Agent به‌خصوص وقتی ابزارها فراخوانی می‌شوند | مثال: 60 ثانیه.
Retry / Error Handling (تلاش مجدد/مدیریت خطا) | نوع داده: تنظیمات | کاربرد: کنترل رفتار در خطاهای موقت (Rate limit، Timeout، Network) | مثال: 2 بار تلاش مجدد با Backoff.

نکات مهم هنگام پیکربندی

خروجی ساختارمند را اجباری کنید اگر مرحله بعدی ورکفلو بر اساس فیلدها تصمیم می‌گیرد.
ابزارها را مینیمال نگه دارید تا هم هزینه کمتر شود هم ریسک اقدامات ناخواسته کاهش یابد.
Context را کوتاه و مفید بنویسید: ورودی‌های بزرگ باعث کندی و هزینه بیشتر می‌شود.
قوانین را شفاف بنویسید: مثل «اگر داده کافی نیست، خروجی را با needs_more_info=true و سوالات لازم برگردان».

ورودی‌ها و خروجی‌ها

ورودی (Input)

AI Agent معمولاً یک یا چند آیتم JSON از نود قبلی می‌گیرد. شما در بخش پیام/پرامپت با Expression به فیلدهای ورودی اشاره می‌کنید.

نمونه ورودی JSON:

{  "ticketId": "TCK-10451",  "customerName": "Ali",  "subject": "مشکل در پرداخت",  "body": "سلام، موقع پرداخت خطای 502 می‌گیرم. از دیروز شروع شده.",  "plan": "Pro",  "language": "fa"}

خروجی (Output)

خروجی می‌تواند متن ساده یا JSON ساختارمند باشد. در پروژه‌های عملی، خروجی ساختارمند بهترین گزینه است تا بدون ابهام وارد نودهای بعدی شود.

نمونه خروجی ساختارمند (پیشنهادی):

{  "category": "billing/payment",  "priority": "high",  "needs_more_info": false,  "reply": "سلام علی عزیز. بابت مشکل پیش‌آمده متأسفیم. خطای 502 معمولاً موقتی است و به ارتباط با درگاه پرداخت مربوط می‌شود. لطفاً یک‌بار کش مرورگر را پاک کنید و مجدداً تلاش کنید. اگر همچنان خطا پابرجاست، ساعت تقریبی تلاش و نام مرورگر را ارسال کنید تا بررسی دقیق‌تری انجام دهیم.",  "tags": ["502", "payment", "gateway"],  "suggested_actions": [    {"type": "create_incident", "title": "Payment gateway 502 spikes", "severity": "high"}  ]}

جدول خلاصه ورودی/خروجی

Input: آیتم(های) JSON شامل متن، داده مشتری، شناسه‌ها، و هر context لازم
Output: متن یا JSON شامل نتیجه تحلیل، تصمیم‌ها، پاسخ پیشنهادی، و فیلدهای قابل استفاده در مراحل بعد

نکات پیشرفته و ترفندها

1) طراحی خروجی برای کنترل‌پذیری

به‌جای اینکه Agent فقط متن بدهد، از او بخواهید خروجی را با فیلدهای کنترلی برگرداند:

route: مسیر پیشنهادی (sales/support/tech)
confidence: عدد 0 تا 1
needs_more_info: بولین
next_questions: آرایه سوالات

بعد با نود IF تصمیم بگیرید: اگر confidence کم بود، به اپراتور انسانی ارسال شود.

2) الگوی «ابزار فقط وقتی لازم است»

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

«اگر orderId وجود دارد، ابتدا با ابزار GetOrderStatus وضعیت را بگیر. اگر orderId وجود ندارد، سوال لازم را برگردان و ابزار را فراخوانی نکن.»

3) ترکیب با Set و Switch برای اجرای دقیق

بعد از AI Agent یک نود Set قرار دهید تا فقط فیلدهای لازم را نگه دارید و داده‌های اضافی حذف شود.
با Switch روی فیلد category یا route شاخه‌بندی کنید (مثلاً billing به تیم مالی، technical به تیم فنی).

4) کاهش هزینه و افزایش سرعت

خلاصه‌سازی قبل از Agent: اگر متن خیلی طولانی است، ابتدا با یک مرحله خلاصه‌سازی یا با یک Function نود، بخش‌های غیرضروری را حذف کنید.
دما پایین برای کارهای استخراج و طبقه‌بندی.
محدود کردن ابزارها به 1 تا 3 ابزار کلیدی.

5) استانداردسازی زبان و لحن خروجی

اگر ورودی چندزبانه است، یک فیلد language از ورودی بگیرید و در دستورالعمل‌ها بنویسید:

«خروجی reply را مطابق language تولید کن. اگر language مشخص نبود، فارسی تولید کن.»

محدودیت‌ها و خطاها

محدودیت‌ها

وابستگی به کیفیت پرامپت و اسکیما: اگر دستورالعمل‌ها مبهم باشد، خروجی ناپایدار می‌شود.
ریسک خروجی غیرساختارمند: بدون Structured Output ممکن است متن آزاد تولید شود و پارس کردن سخت شود.
محدودیت توکن: متن‌های طولانی یا ابزارهای پرخروجی باعث قطع شدن پاسخ می‌شوند.
عدم تضمین صددرصدی صحت: Agent ممکن است اشتباه کند؛ باید با کنترل‌های ورکفلو (Validation/Rules) مهار شود.

خطاهای رایج و راه‌حل‌ها

خروجی JSON نامعتبر
علت: Max Tokens کم، یا اسکیما/دستورالعمل ناقص
راه‌حل: Max Tokens را افزایش دهید، Structured Output را فعال کنید، requiredها را دقیق تعریف کنید، نمونه خروجی صحیح در دستورالعمل بیاورید.
پاسخ‌های طولانی و پرحرف
علت: دستورالعمل سبک خروجی مشخص نیست یا Temperature بالا است
راه‌حل: محدودیت طول بگذارید: «reply حداکثر 120 کلمه»، Temperature را کاهش دهید.
استفاده بیش از حد از ابزارها
علت: ابزار زیاد فعال است و Agent آزادی زیادی دارد
راه‌حل: ابزارها را محدود کنید، شرط استفاده از ابزار را بنویسید، Timeout و Retry را منطقی تنظیم کنید.
Rate Limit یا خطای 429 از ارائه‌دهنده مدل
علت: درخواست زیاد یا همزمانی بالا
راه‌حل: Retry با Backoff، کاهش همزمانی (Concurrency)، کش کردن نتایج برای درخواست‌های تکراری.
پاسخ نامرتبط با سیاست‌های کسب‌وکار
علت: قوانین (Policy) در System Instructions نیامده
راه‌حل: سیاست‌ها را صریح اضافه کنید: موارد ممنوع، نحوه ارجاع به انسان، قالب پاسخ، و منابع مجاز.

ایده ها

Agent مدیریت جلسه: صورتجلسه را بگیرد، تصمیم‌ها و Action Itemها را استخراج کند و در Notion/Jira ثبت کند.
Agent کنترل کیفیت محتوا: متن بلاگ را بررسی کند (غلط املایی، لحن برند، چک‌لیست SEO) و خروجی اصلاحات را JSON بدهد.
Agent تحلیل لیدهای فروش: اطلاعات لید را از فرم/CRM بگیرد، امتیازدهی کند، دلیل امتیاز را بنویسد و لیدهای داغ را به Slack اعلام کند.
Agent پاسخ‌گوی سفارش: پیام مشتری را بگیرد، orderId را تشخیص دهد، با ابزار API وضعیت را بخواند و پاسخ آماده ارسال تولید کند.
Agent پایش ریسک: خبر/داده داخلی را تحلیل کند، هشدارهای ریسک عملیاتی را دسته‌بندی کند و گزارش روزانه بسازد.

نود AI Agent در N8N