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

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

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

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

یہ فرض کیا گیا ہے کہ 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 میں موجود نام July 2026 تک n8n کے موجودہ stable version سے مطابقت رکھتے ہیں۔ Version 1.82.0 کے بعد سے ہر AI Agent node بطور Tools Agent چلتا ہے، اس لیے پرانا agent-type dropdown اب موجود نہیں ہے۔

مرحلہ 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 کا استعمال فی ٹوکن بل کیا جاتا ہے اور یہ کسی بھی Claude.ai سبسکرپشن سے الگ ہوتا ہے۔ اس لیے پہلے رن سے قبل اکاؤنٹ میں بلنگ فعال کریں۔

ماڈل کا انتخاب ہر ایجنٹ کے لیے کریں، پوری کمپنی کے لیے نہیں۔ ایک ایسا ایجنٹ جو ایک ٹول کے ذریعے کوئی چیز تلاش کرکے نتیجہ بتاتا ہے، Haiku پر اچھی طرح چلتا ہے۔ July 2026 کے مطابق اس کی قیمت فی million input tokens $1 اور فی million output tokens $5 ہے۔ جب ایجنٹ کے پاس کئی ٹول ہوں اور اسے ان کے درمیان منصوبہ بندی کرنا پڑے، تو Sonnet استعمال کریں۔ آپ جس خرابی سے بچنا چاہتے ہیں وہ یہ ہے کہ سستا ماڈل غلط ٹول کو چار بار کال کرے، جس کی لاگت مہنگے ماڈل کے درست ٹول کو ایک بار کال کرنے سے زیادہ ہو سکتی ہے۔

ذیلی نوڈ کے اختیارات میں Maximum Number of Tokens مقرر کریں۔ یہ ماڈل کے تیار کردہ ہر جواب کی زیادہ سے زیادہ لمبائی مقرر کرتا ہے۔ اگر اسے بڑی ڈیفالٹ قدر پر چھوڑ دیا جائے، تو ایک الجھا ہوا رن بہت طویل جواب تیار کر سکتا ہے اور اس کی فیس بھی عائد ہو سکتی ہے۔

n8n کی دستاویزات میں درج ایک اہم احتیاط سب کے لیے مسئلہ بنتی ہے: ذیلی نوڈ کے اندر موجود expressions ہمیشہ پہلے input item کے حوالے سے resolve ہوتے ہیں، ہر item کے حوالے سے نہیں۔ ہر item سے متعلق expressions کو root node کے prompt fields میں رکھیں۔

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

AI Agent نوڈ کھولیں۔ Prompt پیرامیٹر میں دو ترتیبات ہیں۔

• Take from previous node automatically کو ایک آنے والے فیلڈ کی ضرورت ہوتی ہے جس کا نام chatInput ہو۔ Chat Trigger کے بعد یہ درست انتخاب ہے۔
• Define below ایک Prompt (User Message) فیلڈ دکھاتا ہے، جہاں آپ جامد متن یا ایک expression لکھ سکتے ہیں۔ Schedule Trigger یا Webhook نوڈ کے بعد یہ درست انتخاب ہے۔

جب Webhook نوڈ سے پہلے موجود ہو، تو POST body $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 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 کو واپس کرتا ہے، تو agent بھی ناکام ہوگا۔ ناکامی بظاہر 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 سے 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 میں اسے تلاش کرتا ہے۔ chat workflow میں یہ صارف سے براہِ راست پوچھ بھی سکتا ہے۔

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

میموری کے ذیلی نوڈ کے بغیر، ہر پیغام بالکل ابتدا سے شروع ہوتا ہے۔ حالیہ گفتگو محفوظ رکھنے کے لیے Simple Memory کا ذیلی نوڈ منسلک کریں۔

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

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

جب n8n queue mode میں چل رہا ہو تو فعال production workflow میں Simple Memory کام نہیں کرتا، کیونکہ history کسی shared store کے بجائے workflow کے اپنے data میں محفوظ ہوتی ہے۔ queue-mode instance پر اس کے بجائے Postgres Chat Memory کا ذیلی نوڈ استعمال کریں اور اسے ایسے database سے منسلک کریں جس تک main process اور workers دونوں رسائی حاصل کر سکیں۔

مرحلہ 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.

"Always call the status tool before answering" یہاں واقعی اہم کردار ادا کرتا ہے۔ اس کے بغیر، اگر ماڈل سمجھے کہ اسے جواب پہلے ہی معلوم ہے تو وہ tool کو نظرانداز کرکے اپنی یادداشت سے جواب دے گا۔ آپ کے infrastructure میں تبدیلی ہوتے ہی یہ جواب پُراعتماد مگر غلط ہوگا۔

ایجنٹ کیوں چکر لگاتا ہے، اور اسے کیا روکتا ہے

Options میں Max Iterations بھی موجود ہے، جس کی طے شدہ قدر 10 ہے۔ ایک iteration سے مراد model call اور اس کے بعد context میں واپس شامل کیا جانے والا ایک tool result ہے۔ اس لیے ایجنٹ کا ایک run صرف ایک API call نہیں ہوتا؛ یہ زیادہ سے زیادہ 10 calls پر مشتمل ہو سکتا ہے، اور ہر call میں بڑھتی ہوئی پوری گفتگو بطور input شامل ہوتی ہے۔

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

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

shell سے run کی نگرانی کریں۔

docker compose logs -f n8n

بغیر نگرانی کام کرنے والے ایجنٹ کو خاموشی سے اخراجات کرنے سے روکنا

Chat Trigger کے پیچھے موجود ایجنٹ میں ایک انسان شامل ہوتا ہے، اور جواب غلط معلوم ہونے پر وہ اسے روک دیتا ہے۔ Schedule Trigger کے پیچھے موجود ایجنٹ کی نگرانی کرنے والا کوئی نہیں ہوتا۔ مکمل تفصیل ہمیشہ فعال VPS پر AI ایجنٹ کے اخراجات کا کنٹرول میں موجود ہے۔ یہاں زیادہ تر کام چار ترتیبات کرتی ہیں۔

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

تبدیلیاں کرتے وقت workflow کو deactivate رکھیں۔ فعال workflow، n8n کے محفوظ کردہ 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، ایک call کی لاگت سے چار گنا سے کہیں زیادہ مہنگا ہو سکتا ہے۔ Max Iterations اس تعداد کی بالائی حد مقرر کرتا ہے، جبکہ Return Intermediate Steps دکھاتا ہے کہ کسی run نے حقیقت میں کتنے steps استعمال کیے۔

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

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