كيف تبني وكيل AI خاص بك على سيرفر VPS باستخدام n8n

ما هو وكيل AI في n8n، وكيف يختلف عن السلسلة

وكيل AI في n8n هو عقدة AI Agent واحدة متصلة بها عقد فرعية: نموذج محادثة واحد، وأداة واحدة أو أكثر، وذاكرة اختيارية. تذكر الهدف بلغة عادية، ويقرر النموذج الأدوات التي يستدعيها والترتيب الذي يستدعيها به إلى أن يتمكن من الإجابة. كل ما يلي هو إعدادات مرتبطة بهذه الفكرة الواحدة.

تعمل السلسلة بطريقة مختلفة. في Basic LLM Chain تحدد الخطوات، ولا يفعل النموذج سوى إنشاء النص. أما في الوكيل، فيحدد النموذج الخطوات. لذلك قد يكلّف السؤال نفسه استدعاءً واحداً للنموذج اليوم وتسعة استدعاءات غداً. هذا الاختلاف وحده يحدد كل إعداد في هذا الدليل. إذا كانت هذه الحلقة جديدة عليك كفكرة، لا كميزة في n8n، فمن المفيد كتابة واحدة يدوياً مرة واحدة قبل تركيبها من العقد، لأن العقدة تخفي الجزء الدقيق الذي ستقضي بقية هذا الدليل في تحليله.

يفترض هذا أن n8n يعمل مسبقاً خلف HTTPS على جهاز تتحكم فيه. إذا لم يكن كذلك، فابدأ بـاستضافة n8n ذاتياً على Docker باستخدام شهادة حقيقية، لأن مفتاح API الذي توشك على تخزينه يحتاج إلى النسخة الاحتياطية لمفتاح التشفير التي يصر عليها ذلك الدليل. بالنسبة إلى الأنماط غير المعتمدة على الوكلاء، مثل ملخّصات webhook والمصنّفات المجدولة، راجع أنماط سير عمل Claude وn8n.

تحقق من إصدارك قبل الوثوق بأي اسم حقل هنا، لأن n8n يغيّر عقد AI كثيراً.

docker compose exec n8n n8n --version

أصبح إعداد نوع الوكيل مهملاً في الإصدار 1.82.0 لصالح Tools Agent. ما زالت عقد v1 القديمة تحتوي على هذا الإعداد؛ وتحدد وثائق n8n الإصدار 3.0 من n8n لإزالة إصدار تلك العقدة.

الخطوة 1: اختر المشغّل

بالنسبة إلى وكيل محادثة، أضف عقدة Chat Trigger. اترك الخيار Make Chat Publicly Available معطّلاً أثناء الإنشاء، حتى تتمكن لوحة الدردشة في المحرّر فقط من الوصول إليه. فعّله بعد اكتمال الوكيل وتحديد أسلوب المصادقة.

يمرّر Chat Trigger إلى الوكيل حقلاً باسم chatInput. هذا الاسم مهم في الخطوة 3، والخطأ فيه هو أكثر أسباب الفشل الأول شيوعاً.

بالنسبة إلى وكيل يعمل دون مراقبة، استخدم عقدة Schedule Trigger أو Webhook بدلاً من ذلك. لا تنتج أي منهما chatInput، لذلك ستكتب الموجّه بنفسك.

الخطوة 2: بيانات اعتماد النموذج

أضف عقدة AI Agent إلى اللوحة. يعرض n8n فوراً موصلاً فارغاً باسم Chat Model أسفلها. أرفق بها عقدة فرعية من نوع Anthropic Chat Model.

أنشئ بيانات الاعتماد من Claude Console على platform.claude.com، ضمن Settings ثم API keys. يظهر المفتاح مرة واحدة فقط. يطلب منك Console أيضاً اختيار تاريخ انتهاء الصلاحية عند إنشاء المفتاح. ويتوقف agent غير المتصل عن العمل في يوم انتهاء صلاحية مفتاحه، لذلك سجّل ذلك التاريخ في مكان ستراه. بالنسبة إلى agent غير المتصل، استخدم مفتاح حساب خدمة مقيّداً بنطاق workspace، حتى لا تحتاج الطلبات إلى ترويسة workspace منفصلة.

تُحاسَب استخدامات API حسب عدد الرموز، وتعتمد طريقة الدفع على خطة Claude، وذلك اعتباراً من 31 October 2026. تتضمن خطط Max وUltra وTeam أرصدة API شهرية: $100 في Max، و$200 في Ultra، وما يصل إلى $500 مجمّعة في Team. تطالب بهذه الأرصدة عبر ربط مؤسسة Console بالخطة من Settings > Billing في Max أو Ultra، أو من Organization settings > Billing في Team. ولا تحتاج إلى إضافة طريقة دفع في Console. يمكن للمشتركين الجدد المطالبة بالأرصدة بعد مرور 7 أيام على الخطة. وتنتهي صلاحية الأرصدة غير المستخدمة في نهاية كل دورة فوترة، أو شهرياً في الخطط السنوية. عند نفاد الأرصدة المشمولة، تستمر الطلبات باستخدام الأرصدة المشتراة. ويمكن لـ auto-reload شراء أرصدة إضافية، بينما تُحاسَب المؤسسات التي تستخدم الفوترة بالفاتورة على الاستخدام الزائد. تتوقف الطلبات عندما لا يتبقى أي رصيد في مؤسسة مدفوعة مسبقاً. ولا تُحمَّل استخدامات API مطلقاً على خطة Claude نفسها. ولا تتضمن خططا Free وPro وEnterprise أي أرصدة API شهرية، لذلك تُحاسَب API فيهما بشكل منفصل عن الاشتراك.

اختر النموذج لكل agent، وليس لكل شركة. يعمل agent ذو الأداة الواحدة الذي يبحث عن شيء ويعرض النتيجة جيداً باستخدام Haiku. يسجّل الإصدار الحالي، Haiku 5.5، سعراً قدره $0.10 لكل مليون رمز إدخال و$0.50 لكل مليون رمز إخراج اعتباراً من 12 October 2026. ويرتفع السعر إلى $0.50 و$2.50 لأي طلب يتجاوز فيه prompt عدد 100,000 رمز، وهو أمر قد يحدث بسبب نافذة ذاكرة طويلة ونتائج أدوات كبيرة. عندما يحتوي agent على عدة أدوات ويحتاج إلى التخطيط بينها، انتقل إلى Sonnet. الخطأ الذي تتجنبه هو استخدام نموذج رخيص يستدعي الأداة الخاطئة أربع مرات، فتكون تكلفته أعلى من تكلفة النموذج الأغلى الذي يستدعي الأداة الصحيحة مرة واحدة.

اضبط Maximum Number of Tokens في خيارات العقدة الفرعية. يحدد هذا الخيار طول كل استجابة ينتجها النموذج. إذا تركته على قيمة افتراضية كبيرة، فقد ينتج تشغيل واحد مرتبك إجابة طويلة جداً، وتُحاسَب على هذه الرموز.

هناك ملاحظة مهمة في وثائق n8n تفوت كثيراً من المستخدمين: تُقيَّم expressions داخل العقدة الفرعية دائماً مقابل عنصر الإدخال الأول، وليس لكل عنصر على حدة. ضع expressions الخاصة بكل عنصر في حقول prompt في العقدة الجذرية.

الخطوة 3: المطالبة التي يتلقاها الوكيل

افتح عقدة AI Agent. يحتوي الإعداد Source for Prompt (User Message) على خيارين.

• يتوقع Connected Chat Trigger Node حقلاً وارداً باسم chatInput. هذا هو الخيار المناسب عند استخدامه خلف Chat Trigger.
• يكشف Define below عن حقل Prompt (User Message)، حيث تكتب نصاً ثابتاً أو تعبيراً. هذا هو الخيار المناسب عند استخدامه خلف Schedule Trigger أو عقدة Webhook.

عند وضع عقدة Webhook أمامه، يصل نص طلب POST ضمن $json.body، لذلك يبدو حقل المطالبة كما يلي.

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: امنح الوكيل أداة واحدة

توضح وثائق n8n أنّه يجب ربط عقدة فرعية واحدة على الأقل للأدوات بعقدة AI Agent، مع أنّ الشيفرة الحالية للعقدة (الإصدار 3.1) ترفض التشغيل فقط عند غياب نموذج محادثة. ابدأ بأداة واحدة في كلتا الحالتين، لأن أداة واحدة تعمل تعلّمك أكثر من أربع أدوات نصف مُعدّة، ولأن الوكيل الذي لا يملك أداة ليس سوى سلسلة ذات تكلفة أعلى.

أرفق عقدة HTTP Request بموصل Tool في الوكيل. اضبطها تماماً كما تضبط عقدة HTTP Request عادية، ثم اختبر نقطة النهاية من 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"، ثم يبحث النموذج في المحادثة وبيانات الإدخال ونتائج الأدوات الأخرى للعثور على قيمة مناسبة. وفي سير عمل للمحادثة، قد يطلبها من المستخدم ببساطة.

يُعد البحث على الويب الأداة الثانية المعتادة. وبما أنّه مجرد نقطة نهاية HTTP أخرى، يمكنك توجيه هذه العقدة نفسها إلى مثيل SearXNG الخاص بك بدلاً من واجهة بحث مدفوعة، شرط أن تتعامل مع كل صفحة تُعيدها باعتبارها نصاً غير موثوق أصبح الآن داخل مطالبتك.

الخطوة 5: الذاكرة، ولماذا ينسى الوكيل

من دون عقدة فرعية للذاكرة، تبدأ كل رسالة من الصفر. أضف عقدة Simple Memory فرعية للاحتفاظ بالمحادثة الأخيرة.

تحتوي هذه العقدة على معاملين. يحدد Session Key المحادثة المقصودة، لذلك يحصل مستخدمان لديهما مفاتيح مختلفة على سجلين منفصلين. يحدد Context Window Length عدد التفاعلات السابقة التي يعاد إدراجها في موجّه الطلب.

يُعدّ Context Window Length أداة للتحكم في التكلفة بقدر ما هو أداة للتحكم في الجودة، لأن كل تفاعل محفوظ يُرسل مجدداً كرموز إدخال في كل استدعاء لاحق. إذا كانت النافذة تساوي 20 لدى وكيل كثير التفاعل، فأنت تدفع تكلفة الرسائل المبكرة نفسها عشرين مرة.

لا تعمل Simple Memory في سير عمل إنتاجي نشط عندما يعمل n8n في وضع queue، لأنها تخزن السجل في Map مفردة محلية للعملية، وتستخدم معرّفات سير العمل والجلسة كمفاتيح. ولا تشترك workers في هذه الذاكرة. في مثيل يعمل بوضع queue، استخدم بدلاً منها العقدة الفرعية Postgres Chat Memory، ووجّهها إلى قاعدة بيانات يمكن لكل من العملية الرئيسية وworkers الوصول إليها.

الخطوة 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. التكرار الواحد هو استدعاء واحد للنموذج. في هذا الاستدعاء يطلب النموذج استخدام أدوات أو يعيد الإجابة النهائية. تُمرَّر نتائج الأدوات إلى الاستدعاء التالي. لذلك لا يقتصر تشغيل الوكيل الواحد على استدعاء API واحد، بل قد يتكون من 10 استدعاءات، ويحمل كل استدعاء منها المحادثة الكاملة المتزايدة كمدخل.

خفّض هذه القيمة. تنتهي معظم الوكلاء الذين يستخدمون أداة واحدة خلال تكرارين. ويحوّل الحد 3 أو 4 دورةً لا نهائية إلى فشل واضح يمكنك رؤيته في قائمة التنفيذ.

أثناء تصحيح الأخطاء، فعّل Return Intermediate Steps. سيشمل الناتج النهائي عندئذٍ استدعاءات الأدوات التي أجراها الوكيل أثناء التنفيذ. يتيح لك ذلك التمييز بين «النموذج لم يستدعِ الأداة قط» و«الأداة أعادت نتيجة غير مفيدة». عطّل هذا الخيار قبل تشغيل النظام في بيئة الإنتاج، لأن هذه الخطوات تشكّل ضوضاء للمستخدم النهائي.

راقب تنفيذ عملية من shell.

docker compose logs -f n8n

منع agent غير المراقَب من استهلاك الموارد بصمت

يحتوي agent خلف Chat Trigger على شخص يراقبه، ويتوقف ذلك الشخص عندما تبدو الإجابة خاطئة. أما agent خلف Schedule Trigger فلا يراقبه أحد. ما تراقبه هنا هو إنفاق النموذج، لا تكلفة الترخيص، لأن عقد agent والأدوات والذاكرة تعمل جميعها على الإصدار المجاني المستضاف ذاتياً، كما أن الميزات التي تتطلب مفتاحاً مدفوعاً تقتصر غالباً على ميزات الفرق والحوكمة. يوضّح التحكم في تكلفة agent للذكاء الاصطناعي على VPS يعمل دائماً التفاصيل كاملة. تكفي 4 إعدادات لإنجاز معظم العمل هنا.

• حدّد Maximum Number of Tokens في العقدة الفرعية للنموذج، حتى لا تستمر أي استجابة منفردة مدة طويلة.
• اضبط Max Iterations على أصغر عدد يُكمل المهمة.
• اجعل استجابات الأدوات صغيرة. تعيد أداة ما كائن JSON مكوّناً من 4,000 سطر، فتُدرج هذه البيانات كلها في استدعاء النموذج التالي، ثم في كل استدعاء لاحق ضمن التشغيل نفسه.
• اسأل ما إذا كان agent يحتاج إلى جدول تشغيل أصلاً. تعمل مهمة كل خمس دقائق 288 مرة يومياً. اضرب تكلفة التشغيل الواحد في هذا العدد.

ألغِ نشر workflow أثناء التكرار، أو تذكّر على الأقل أي إصدار منشور حالياً. يواصل workflow المنشور الذي يحتوي على Schedule Trigger تشغيل الإصدار الذي نشرته آخر مرة، وليس المسودة الظاهرة على شاشتك، لأن n8n يحتفظ بتعديلاتك في مسودة إلى أن تنشرها مرة أخرى.

FAQ

لماذا ترفض عقدة AI Agent التنفيذ؟

تحقق من الموصلات أولاً. تحتاج عقدة AI Agent إلى عقدة فرعية لنموذج محادثة، وبدونها تتوقف برسالة "Please connect a model to the Chat Model input" قبل إجراء أي استدعاء لواجهة API. تذكر وثائق n8n أيضاً أن هناك حاجة إلى عقدة فرعية واحدة على الأقل لأداة، لذلك إذا كان النموذج متصلاً وما زالت العقدة ترفض التنفيذ، فأضف أداة واحدة، حتى لو كانت بسيطة، ثم شغّلها مرة أخرى.

تستجيب الوكيلة، لكنها لا تستدعي أداتي أبداً. ما الخطأ؟

في معظم الحالات، يكون الخطأ في حقل Description الخاص بالأداة. يختار النموذج الأدوات بقراءة أوصافها، لذلك لا يوضح وصف مثل "HTTP Request" متى تنطبق الأداة. أعد صياغته ليوضح البيانات التي تعيدها الأداة والحالة التي تكون مفيدة فيها، ثم أضف سطراً إلى System Message يوجّه الوكيلة إلى استدعاء هذه الأداة قبل الإجابة.

لماذا تختلف تكلفة السؤال نفسه في كل عملية تشغيل؟

لأن النموذج يختار عدد الخطوات. تعيد كل دورة إرسال المحادثة الكاملة حتى تلك اللحظة، بما في ذلك مخرجات الأدوات السابقة، لذلك تُحتسب على عملية تشغيل تستغرق أربع دورات تكلفة رموز الإدخال والإخراج في الاستدعاءات الأربعة كلها. يحدد Max Iterations الحد الأقصى لذلك، بينما يوضح Return Intermediate Steps عدد الخطوات التي استخدمتها عملية تشغيل معينة فعلياً.

تعمل الذاكرة لدي في المحرر، لكنها لا تعمل في بيئة الإنتاج. ما الذي تغيّر؟

تحقق مما إذا كان المثيل يعمل في وضع الطابور. تخزن Simple Memory السجل في Map مفردة محلية للعملية، ويُحدَّد المفتاح باستخدام معرّفات سير العمل والجلسة، ولا تشارك العمليات العاملة المنفصلة هذه البيانات. استبدلها بالعقدة الفرعية Postgres Chat Memory، التي تحفظ السجل في قاعدة البيانات التي تشترك فيها جميع العمليات العاملة.