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

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

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

chain اس کے برعکس کام کرتی ہے۔ Basic LLM Chain میں steps آپ طے کرتے ہیں، جبکہ model صرف text تیار کرتا ہے۔ agent میں steps کا فیصلہ model کرتا ہے، اس لیے ایک ہی سوال کے لیے آج ایک model call اور کل نو model calls درکار ہو سکتی ہیں۔ اس ایک فرق سے اس guide کی ہر setting متاثر ہوتی ہے۔

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

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

docker compose exec n8n n8n --version

اس guide میں دیے گئے names July 2026 تک n8n کے موجودہ stable version سے مطابقت رکھتے ہیں۔ Version 1.82.0 سے ہر AI Agent node بطور Tools Agent چلتا ہے، اس لیے پرانا agent-type dropdown اب موجود نہیں ہے۔

مرحلہ 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: model credential

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

credential، Anthropic Console میں platform.claude.com کے ذریعے، پہلے Settings اور پھر API Keys کے تحت بنائیں۔ key صرف ایک بار دکھائی جاتی ہے۔ API استعمال کی billing فی token ہوتی ہے اور یہ کسی بھی Claude.ai subscription سے الگ ہے، اس لیے پہلے run سے قبل account کی billing ترتیب دینا ضروری ہے۔

model کا انتخاب ہر agent کے لیے کریں، پوری کمپنی کے لیے نہیں۔ ایک ایسا one-tool agent جو کسی چیز کو تلاش کرکے نتیجہ بتاتا ہے، Haiku پر اچھی طرح چلتا ہے۔ July 2026 تک اس کی قیمت $1 فی million input tokens اور $5 فی million output tokens درج ہے۔ جب agent کے پاس کئی tools ہوں اور اسے ان کے درمیان planning کرنی پڑے، تو Sonnet پر منتقل کریں۔ آپ جس failure سے بچنا چاہتے ہیں وہ یہ ہے کہ سستا model غلط tool کو چار بار call کرے، جس کی لاگت مہنگے model کے درست tool کو ایک بار call کرنے سے زیادہ ہو جاتی ہے۔

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

n8n docs میں درج ایک اہم caveat سب کو متاثر کرتا ہے: sub-node کے اندر expressions ہمیشہ first input item کے مطابق resolve ہوتے ہیں، ہر item کے مطابق نہیں۔ ہر item سے متعلق expressions کو root node کے prompt fields میں رکھیں۔

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

AI Agent node کھولیں۔ Prompt parameter میں 2 settings ہیں۔

• Take from previous node automatically آنے والے field کا نام chatInput ہونے کی توقع رکھتا ہے۔ 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: ایجنٹ کو ایک tool دیں

ایسا AI Agent node جس کے ساتھ کوئی tool sub-node منسلک نہ ہو، چلنے سے انکار کر دیتا ہے۔ ایک tool سے شروع کریں، کیونکہ ایک درست کام کرنے والا tool چار ادھورے configured tools سے زیادہ معلومات فراہم کرتا ہے۔

ایجنٹ کے Tool connector کے ساتھ ایک HTTP Request node منسلک کریں۔ اسے بالکل اسی طرح configure کریں جیسے عام HTTP Request node کو کرتے ہیں، پھر پہلے shell سے اس endpoint کی آزمائش کریں۔

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

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

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

model کو request کا کچھ حصہ خود پُر کرنے دینے کے لیے $fromAI() expression استعمال کریں۔ یہ صرف ان tools میں کام کرتا ہے جو AI Agent node سے منسلک ہوں، اور 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 کی طرف بھیج سکتے ہیں، کسی paid search API کے بجائے، بشرطیکہ اس سے واپس آنے والے ہر page کو untrusted text سمجھیں جو اب آپ کے prompt میں شامل ہے۔

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

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

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

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

جب n8n queue mode میں چل رہا ہو تو فعال production workflow میں Simple Memory کام نہیں کرتا، کیونکہ history workflow کے اپنے data میں رہتی ہے، shared store میں نہیں۔ 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 اور context میں واپس شامل کیا جانے والا ایک tool result ہوتا ہے۔ اس لیے ایک 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 میں agent کی جانب سے راستے میں کی گئی tool calls بھی شامل ہوں گی۔ اس طرح آپ معلوم کر سکتے ہیں کہ model نے tool کو کبھی call نہیں کیا، یا tool نے کوئی مفید result واپس نہیں کیا۔ Live deployment سے پہلے اسے دوبارہ غیر فعال کر دیں، کیونکہ یہ steps end user کے لیے غیر ضروری تفصیل ہیں۔

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

docker compose logs -f n8n

غیر زیرِ نگرانی agent کو خاموشی سے خرچ کرنے سے روکنا

Chat Trigger کے پیچھے موجود agent میں ایک انسان شامل ہوتا ہے، اور جب جواب غلط معلوم ہو تو وہ اسے روک دیتا ہے۔ Schedule Trigger کے پیچھے موجود agent کی نگرانی کوئی نہیں کرتا۔ یہاں آپ licence کے خرچ کے بجائے model کے استعمال کے خرچ کی نگرانی کر رہے ہیں، کیونکہ agent، tool اور memory nodes سب free self-hosted edition میں کام کرتے ہیں، اور وہ features جن کے لیے paid key درکار ہوتی ہے، زیادہ تر team اور governance سے متعلق ہیں۔ مکمل وضاحت ہمیشہ فعال VPS پر AI agent کے اخراجات کا کنٹرول میں موجود ہے۔ یہاں زیادہ تر کام چار 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 ہوتا ہے۔ ایک run کی لاگت جتنی بھی ہو، اسی عدد کو 288 سے ضرب دیں۔

جب تک آپ iterate کر رہے ہوں، workflow کو deactivate رکھیں۔ Schedule Trigger والا active workflow اس version کے مطابق run ہوتا رہتا ہے جسے n8n نے save کیا ہے۔ یہ ضروری نہیں کہ وہ version آپ کی screen پر موجود version ہی ہو۔

FAQ

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

AI Agent node کے لیے chat model sub-node اور کم از کم ایک tool sub-node درکار ہوتا ہے۔ ایسا node جس میں model موجود ہو لیکن tool نہ ہو، کسی بھی API call سے پہلے ناکام ہو جاتا ہے۔ ایک tool منسلک کریں، چاہے وہ معمولی ہی ہو، پھر دوبارہ چلائیں۔

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

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

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

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

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

دیکھیں کہ instance queue mode میں چل رہا ہے یا نہیں۔ Simple Memory تاریخچہ workflow کے اپنے execution data میں محفوظ کرتا ہے۔ یہ data کسی الگ worker process کو منتقل ہونے کے بعد برقرار نہیں رہتا، اس لیے فعال production workflow اپنی memory کھو دیتا ہے۔ اس کے بجائے Postgres Chat Memory sub-node استعمال کریں، جو تاریخچہ اس database میں محفوظ رکھتا ہے جسے ہر worker استعمال کرتا ہے۔