SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor

اپنے VPS پر n8n AI agent کیسے بنائیں

n8n میں عملی AI agent بنائیں: AI Agent node، Claude credential، HTTP Request tool، memory اور trigger شامل کریں، جبکہ settings model calls اور لاگت محدود رکھیں۔

n8n AI agent کیا ہے، اور یہ chain سے کیسے مختلف ہے

n8n AI agent ایک واحد AI Agent node ہوتا ہے، جس کے ساتھ sub-nodes منسلک ہوتے ہیں: ایک chat model، ایک یا زیادہ tools، اور اختیاری memory۔ آپ سادہ زبان میں ہدف بیان کرتے ہیں، اور model فیصلہ کرتا ہے کہ جواب دینے تک کون سے tools کس ترتیب سے call کرنے ہیں۔ ذیل کی تمام configuration اسی ایک تصور کے گرد ہے۔

Chain اس کے برعکس کام کرتی ہے۔ Basic LLM Chain میں آپ steps طے کرتے ہیں، اور model صرف text تیار کرتا ہے۔ Agent میں steps کا فیصلہ model کرتا ہے، اس لیے ایک ہی سوال پر آج model کی ایک call اور کل نو calls ہو سکتی ہیں۔ یہی فرق اس guide کی ہر setting کی بنیاد ہے۔ اگر یہ loop بطور تصور آپ کے لیے نیا ہے، نہ کہ صرف n8n feature کے طور پر، تو nodes سے اسے assemble کرنے سے پہلے ایک بار اسے خود لکھ کر دیکھنا مفید ہے، کیونکہ node اس عین حصے کو چھپا دیتا ہے جس کے بارے میں آپ اس guide کے باقی حصے میں غور کریں گے۔

یہ فرض کیا گیا ہے کہ n8n پہلے ہی آپ کے زیرِ انتظام machine پر HTTPS کے پیچھے چل رہا ہے۔ اگر ایسا نہیں ہے تو پہلے حقیقی certificate کے ساتھ Docker پر n8n self-host کرنا شروع کریں، کیونکہ آپ جو API key ابھی store کرنے والے ہیں، اس کے لیے اس guide میں لازمی قرار دیا گیا encryption-key backup درکار ہے۔ Non-agent patterns، یعنی webhook summarizers اور scheduled classifiers کے لیے Claude اور n8n workflow patterns دیکھیں۔

کسی بھی field name پر اعتماد کرنے سے پہلے اپنا version check کریں، کیونکہ n8n AI nodes میں اکثر تبدیلیاں کرتا ہے۔

docker compose exec n8n n8n --version

Version 1.82.0 نے agent-type setting کو deprecated کر کے Tools Agent کو ترجیح دی۔ Legacy v1 nodes میں یہ setting اب بھی موجود ہے؛ n8n کی documentation کے مطابق اس node version کو n8n 3.0 میں remove کیا جائے گا۔

مرحلہ 1: trigger منتخب کریں

Conversational agent کے لیے Chat Trigger node شامل کریں۔ تعمیر کے دوران Make Chat Publicly Available کو بند رکھیں، تاکہ صرف editor کا chat panel ہی اس تک رسائی حاصل کر سکے۔ Agent مکمل ہونے اور authentication کے طریقے کا فیصلہ کرنے کے بعد اسے فعال کریں۔

Chat Trigger agent کو chatInput نامی field فراہم کرتا ہے۔ مرحلہ 3 میں یہ نام اہم ہے، اور اسے غلط لکھنا پہلی ناکامی کی سب سے عام وجہ ہے۔

Unattended agent کے لیے اس کے بجائے Schedule Trigger یا Webhook node استعمال کریں۔ ان میں سے کوئی بھی chatInput پیدا نہیں کرتا، اس لیے prompt خود لکھنا ہوگا۔

مرحلہ 2: ماڈل کی اسناد

Canvas پر AI Agent node رکھیں۔ n8n فوراً اس کے نیچے ایک خالی Chat Model connector دکھائے گا۔ وہاں Anthropic Chat Model sub-node منسلک کریں۔

Credential، Claude Console میں platform.claude.com پر بنائیں۔ پہلے Settings، پھر API keys کھولیں۔ Key صرف ایک بار دکھائی جاتی ہے۔ Key بناتے وقت Console آپ سے expiration منتخب کرنے کو بھی کہتا ہے۔ Unattended agent، key کے expire ہونے والے دن کام کرنا بند کر دیتا ہے۔ اس لیے یہ تاریخ ایسی جگہ لکھیں جہاں آپ اسے دیکھ سکیں۔ Unattended agent کے لیے workspace تک محدود service account key استعمال کریں، تاکہ requests کو الگ workspace header درکار نہ ہو۔

API usage کی billing فی token ہوتی ہے۔ 31 October 2026 تک ادائیگی کا طریقہ آپ کے Claude plan پر منحصر ہے۔ Max، Ultra اور Team plans میں ماہانہ API credits شامل ہیں: Max میں $100، Ultra میں $200، اور Team میں مشترکہ طور پر زیادہ سے زیادہ $500۔ انہیں حاصل کرنے کے لیے Max یا Ultra میں Settings > Billing سے، یا Team میں Organization settings > Billing سے Console organization کو plan کے ساتھ link کریں۔ Console میں payment method شامل کرنے کی ضرورت نہیں۔ نئے subscribers plan پر 7 دن مکمل ہونے کے بعد credits حاصل کر سکتے ہیں۔ استعمال نہ ہونے والے credits ہر billing cycle کے اختتام پر، یا annual plans میں ہر ماہ، expire ہو جاتے ہیں۔ شامل credits ختم ہونے کے بعد requests purchased credits کے خلاف جاری رہتی ہیں۔ auto-reload مزید credits خرید سکتا ہے، جبکہ invoiced organizations سے اضافی usage کی billing کی جاتی ہے۔ Prepaid organization میں credits ختم ہونے پر requests رک جاتی ہیں۔ API usage کبھی بھی آپ کے Claude plan پر charge نہیں ہوتی۔ Free، Pro اور Enterprise plans میں ماہانہ API credits شامل نہیں، اس لیے ان plans میں API کی billing subscription سے الگ ہوتی ہے۔

Model ہر agent کے لیے منتخب کریں، پوری company کے لیے نہیں۔ ایسا one-tool agent جو کسی چیز کو تلاش کرکے رپورٹ کرتا ہے، Haiku پر ٹھیک چلتا ہے۔ موجودہ version، Haiku 5.5، کی قیمت 12 October 2026 تک $0.10 فی million input tokens اور $0.50 فی million output tokens درج ہے۔ اگر کسی request کا prompt 100,000 tokens سے زیادہ ہو جائے تو قیمت بالترتیب $0.50 اور $2.50 ہو جاتی ہے۔ طویل memory window اور tool کے بڑے results آپ کو اس حد سے آگے لے جا سکتے ہیں۔ جب agent کے پاس کئی tools ہوں اور اسے ان کے درمیان planning کرنا پڑے، تو Sonnet استعمال کریں۔ جس failure سے آپ بچنا چاہتے ہیں وہ یہ ہے کہ سستا model غلط tool کو چار بار call کرے، جس کی لاگت مہنگے model کے درست tool کو ایک بار call کرنے سے زیادہ ہو۔

Sub-node کے options میں Maximum Number of Tokens مقرر کریں۔ یہ ہر response کی زیادہ سے زیادہ لمبائی محدود کرتا ہے جو model تیار کرتا ہے۔ اگر اسے بڑے default پر چھوڑ دیا جائے تو ایک الجھا ہوا run بہت طویل جواب تیار کر سکتا ہے اور اس کی billing بھی ہو سکتی ہے۔

n8n docs کی ایک اہم وضاحت یہ ہے کہ sub-node کے اندر expressions ہمیشہ first input item کے مطابق resolve ہوتی ہیں، ہر item کے مطابق نہیں۔ Per-item expressions کو root node کے prompt fields میں رکھیں۔

مرحلہ 3: ایجنٹ کو موصول ہونے والا prompt

AI Agent node کھولیں۔ Source for Prompt (User Message) پیرامیٹر میں دو settings ہیں۔

  • Connected Chat Trigger Node کو chatInput نامی incoming field درکار ہوتی ہے۔ Chat Trigger کے بعد یہ درست انتخاب ہے۔
  • Define below میں Prompt (User Message) field ظاہر ہوتی ہے، جہاں آپ static text یا expression لکھ سکتے ہیں۔ Schedule Trigger یا Webhook node کے بعد یہ درست انتخاب ہے۔

جب سامنے Webhook node موجود ہو تو POST body $json.body کے تحت آتی ہے، اس لیے prompt field یوں دکھائی دیتی ہے۔

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: agent کو ایک tool دیں

n8n کی دستاویزات کے مطابق آپ کو AI Agent node کے ساتھ کم از کم ایک tool sub-node connect کرنا ضروری ہے، اگرچہ موجودہ node code (version 3.1) صرف chat model کے بغیر چلنے سے انکار کرتا ہے۔ بہرحال ابتدا ایک tool سے کریں، کیونکہ ایک کام کرنے والا tool چار ادھورے configured tools سے زیادہ معلومات فراہم کرتا ہے، اور بغیر tool والا agent صرف ایک ایسی chain ہے جس کی لاگت زیادہ ہوتی ہے۔

HTTP Request node کو agent کے Tool connector کے ساتھ attach کریں۔ اسے بالکل اسی طرح configure کریں جیسے عام HTTP Request node کو کرتے ہیں، پھر پہلے shell سے اس endpoint کی testing کریں۔

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

اگر curl error یا HTML login page واپس کرے تو agent بھی fail ہوگا۔ اس کی failure بظاہر model کا مسئلہ لگے گی، حالانکہ اصل مسئلہ URL یا authentication کا ہوگا۔ اسے node میں نہیں بلکہ shell میں درست کریں۔

tool کا Description field آپ کے ساتھیوں کے لیے documentation نہیں ہے۔ model یہ field tool کے نام اور parameter schema کے ساتھ پڑھتا ہے تاکہ فیصلہ کر سکے کہ آیا یہ tool متعلقہ ہے۔ اس میں سادہ الفاظ میں لکھیں کہ کیا واپس آتا ہے: "ایک monitored service کی موجودہ up یا down حالت اور downtime duration کو JSON کے طور پر واپس کرتا ہے۔"

model کو request کا کچھ حصہ خود پُر کرنے دینے کے لیے $fromAI() expression استعمال کریں۔ یہ صرف ان tools میں کام کرتا ہے جو AI Agent node کے ساتھ connected ہوں، اور Code tool میں کام نہیں کرتا۔

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

arguments key، پھر اختیاری description، type اور defaultValue ہیں۔ key کی لمبائی 1 سے 64 characters ہونی چاہیے اور اس میں letters، digits، underscores اور hyphens استعمال کیے جا سکتے ہیں۔ type string، number، boolean یا json میں سے ایک ہوتا ہے، اور default string ہے۔ مکمل call اس طرح دکھائی دیتی ہے۔

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

key صرف ایک hint ہے، موجودہ data کا reference نہیں۔ $fromAI('service') کہیں سے بھی service نام کا field نہیں پڑھتا۔ یہ model کو بتاتا ہے کہ "ایک value تیار کریں اور اسے service کہیں"، پھر model conversation، input data اور دوسرے tool results میں سے مناسب value تلاش کرتا ہے۔ chat workflow میں یہ صارف سے براہِ راست پوچھ بھی سکتا ہے۔

Web search عموماً دوسرا tool ہوتا ہے۔ چونکہ یہ بھی ایک HTTP endpoint ہے، اس لیے آپ اسی node کو اپنے SearXNG instance کی طرف point کر سکتے ہیں، paid search API استعمال کرنے کے بجائے، بشرطیکہ اس سے واپس آنے والے ہر page کو untrusted text سمجھیں جو اب آپ کے prompt میں شامل ہے۔

مرحلہ 5: memory، اور agent کیوں بھول جاتا ہے

memory sub-node کے بغیر ہر message صفر سے شروع ہوتا ہے۔ حالیہ گفتگو محفوظ رکھنے کے لیے Simple Memory sub-node منسلک کریں۔

اس میں 2 parameters ہوتے ہیں۔ Session Key طے کرتا ہے کہ یہ کون سی گفتگو ہے، اس لیے مختلف keys والے 2 users کی histories الگ رہتی ہیں۔ Context Window Length بتاتا ہے کہ prompt میں پچھلی کتنی interactions دوبارہ شامل کی جائیں گی۔

Context Window Length معیار کے ساتھ ساتھ لاگت کو بھی متاثر کرتا ہے، کیونکہ یاد رکھی گئی ہر turn بعد کی ہر call میں input tokens کے طور پر دوبارہ بھیجی جاتی ہے۔ chatty agent میں window کو 20 پر رکھنے کا مطلب یہ ہے کہ ابتدائی messages کی لاگت 20 بار ادا کریں گے۔

جب n8n queue mode میں چل رہا ہو تو Simple Memory active production workflow میں کام نہیں کرتا، کیونکہ یہ history کو workflow اور session IDs کی بنیاد پر process-local singleton Map میں محفوظ کرتا ہے، اور workers اس memory کو share نہیں کرتے۔ queue-mode instance پر اس کے بجائے Postgres Chat Memory sub-node استعمال کریں اور اسے ایسے database سے منسلک کریں جس تک main process اور workers دونوں رسائی حاصل کر سکیں۔

مرحلہ 6: System Message

ایجنٹ کے Options کھولیں اور System Message شامل کریں۔ یہیں کام کی وضاحت درج کی جاتی ہے، اور workflow میں سب سے زیادہ اثر رکھنے والا متن یہی ہوتا ہے۔

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 کو call کریں" واقعی اہم کردار ادا کرتا ہے۔ اس کے بغیر، اگر model یہ سمجھے کہ اسے جواب پہلے ہی معلوم ہے تو وہ tool کو نظرانداز کرکے memory کی بنیاد پر جواب دے گا۔ جیسے ہی آپ کے infrastructure میں تبدیلی آئے گی، یہ جواب پُراعتماد مگر غلط ہوگا۔

ایجنٹ loop کیوں کرتا ہے، اور اسے کیا روکتا ہے

Options میں Max Iterations بھی موجود ہے، جس کی default قدر 10 ہے۔ ایک iteration ایک model call ہوتی ہے، جو یا تو tools کی درخواست کرتی ہے یا final answer واپس کرتی ہے؛ tool results اگلی call کو input کے طور پر فراہم ہوتے ہیں۔ اس لیے ایک agent run صرف ایک API call نہیں ہوتا، بلکہ زیادہ سے زیادہ 10 calls پر مشتمل ہو سکتا ہے، اور ہر call میں بڑھتی ہوئی پوری conversation بطور input شامل ہوتی ہے۔

اس قدر کو کم کریں۔ زیادہ تر single-tool agents دو iterations میں مکمل ہو جاتے ہیں، اور 3 یا 4 turns کی limit بے قابو loop کو ایسی واضح failure میں بدل دیتی ہے جسے execution list میں دیکھا جا سکتا ہے۔

Debugging کے دوران Return Intermediate Steps فعال کریں۔ اس کے بعد final output میں وہ tool calls بھی شامل ہوں گی جو agent نے دورانِ عمل کیں۔ اس طرح آپ معلوم کر سکتے ہیں کہ "model نے tool کو کبھی call نہیں کیا" یا "tool نے کوئی مفید نتیجہ واپس نہیں کیا"۔ Live ہونے سے پہلے اسے دوبارہ بند کر دیں، کیونکہ یہ steps end user کے لیے غیر ضروری معلومات ہیں۔

Shell سے run کو ہوتے ہوئے دیکھیں۔

docker compose logs -f n8n

بغیر نگرانی کے چلنے والے agent کو خاموشی سے خرچ کرنے سے روکنا

Chat Trigger کے پیچھے موجود agent میں ایک انسان شامل ہوتا ہے، اور جواب غلط معلوم ہونے پر وہ اسے روک دیتا ہے۔ Schedule Trigger کے پیچھے موجود agent کو کوئی نہیں دیکھ رہا ہوتا۔ یہاں آپ licence spend کے بجائے model spend کی نگرانی کر رہے ہیں، کیونکہ agent، tool اور memory nodes سب free self-hosted edition پر کام کرتے ہیں، اور جن features کے لیے paid key درکار ہوتی ہے، وہ زیادہ تر team اور governance سے متعلق ہیں۔ مکمل وضاحت AI agent cost control on an always-on VPS میں موجود ہے۔ یہاں زیادہ تر کام چار settings کرتی ہیں۔

  • model sub-node پر Maximum Number of Tokens کی حد مقرر کریں، تاکہ کوئی ایک response بہت طویل نہ ہو سکے۔
  • Max Iterations کو اس کم ترین تعداد پر set کریں جس سے task مکمل ہو جائے۔
  • tool responses مختصر رکھیں۔ 4,000 لائنوں پر مشتمل JSON blob واپس کرنے والا tool اس کا پورا مواد اگلی model call میں، اور اسی run کے بعد کی ہر call میں بھی شامل کر دیتا ہے۔
  • یہ بھی دیکھیں کہ agent کو schedule کی واقعی ضرورت ہے یا نہیں۔ ہر پانچ منٹ بعد چلنے والا job دن میں 288 مرتبہ چلتا ہے۔ ایک run کی لاگت جتنی بھی ہو، آپ اسے 288 سے ضرب دیں گے۔

Iterate کرتے وقت workflow کو unpublish رکھیں، یا کم از کم یہ یاد رکھیں کہ کون سا version live ہے۔ Schedule Trigger والا published workflow آپ کی screen پر موجود draft کے بجائے آخری بار publish کیے گئے version کو چلاتا رہتا ہے، کیونکہ n8n آپ کی edits کو دوبارہ publish کرنے تک draft میں رکھتا ہے۔

FAQ

میرا AI Agent node چلنے سے کیوں انکار کرتا ہے؟

پہلے connectors چیک کریں۔ AI Agent node کے لیے chat model sub-node درکار ہوتا ہے۔ اس کے بغیر یہ کسی بھی API call سے پہلے "Please connect a model to the Chat Model input" پیغام کے ساتھ رک جاتا ہے۔ n8n کی دستاویزات میں کم از کم ایک tool sub-node بھی ضروری بتایا گیا ہے۔ اس لیے اگر model connected ہے لیکن node پھر بھی چلنے سے انکار کرتا ہے تو ایک tool منسلک کریں، چاہے وہ معمولی tool ہی ہو، اور اسے دوبارہ چلائیں۔

agent جواب دیتا ہے، لیکن میرے tool کو کبھی call نہیں کرتا۔ مسئلہ کیا ہے؟

تقریباً ہمیشہ مسئلہ tool کے Description field میں ہوتا ہے۔ model tools کا انتخاب ان descriptions کو پڑھ کر کرتا ہے۔ اس لیے "HTTP Request" جیسی description اسے یہ نہیں بتاتی کہ tool کب استعمال کرنا ہے۔ Description کو اس طرح دوبارہ لکھیں کہ اس میں بتایا جائے کہ کون سا data واپس آتا ہے اور یہ tool کس صورتِ حال میں مفید ہے۔ پھر System Message میں ایک سطر شامل کریں جس میں agent کو جواب دینے سے پہلے اس tool کو call کرنے کی ہدایت ہو۔

ہر run میں ایک ہی سوال کی لاگت مختلف کیوں ہوتی ہے؟

کیونکہ steps کی تعداد model منتخب کرتا ہے۔ ہر iteration میں اب تک کی مکمل conversation دوبارہ بھیجی جاتی ہے، جس میں پچھلا tool output بھی شامل ہوتا ہے۔ اس لیے 4 iterations والا run تمام 4 calls کے input اور output tokens کے لیے billing پیدا کرتا ہے۔ Max Iterations اس تعداد کی زیادہ سے زیادہ حد مقرر کرتا ہے، جبکہ Return Intermediate Steps دکھاتا ہے کہ کسی run نے حقیقت میں کتنے steps استعمال کیے۔

میری memory editor میں کام کرتی ہے، لیکن production میں نہیں۔ کیا تبدیل ہوا ہے؟

چیک کریں کہ instance queue mode میں چل رہا ہے یا نہیں۔ Simple Memory تاریخچہ process-local singleton Map میں workflow اور session IDs کی بنیاد پر محفوظ کرتا ہے، اور الگ worker processes اس Map کو share نہیں کرتے۔ اس کے بجائے Postgres Chat Memory sub-node استعمال کریں۔ یہ history اس database میں محفوظ کرتا ہے جسے ہر worker share کرتا ہے۔

کیا یہ مضمون مفید تھا؟