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

ما هو وكيل 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

تتطابق الأسماء في هذا الدليل مع الإصدار المستقر الحالي من n8n في July 2026. منذ الإصدار 1.82.0، تعمل كل عقدة AI Agent بصفتها Tools Agent، لذلك لم تعد القائمة المنسدلة القديمة لنوع الوكيل موجودة.

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

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

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

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

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

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

أنشئ بيانات الاعتماد من Anthropic Console على platform.claude.com، ضمن Settings ثم API Keys. يظهر المفتاح مرة واحدة فقط. تُحتسب تكلفة استخدام API لكل token، وهي منفصلة عن أي اشتراك في Claude.ai، لذلك يجب إعداد الفوترة للحساب قبل التشغيل الأول.

اختر النموذج لكل وكيل، وليس لكل شركة. يعمل الوكيل الذي يستخدم أداة واحدة للبحث عن شيء وإعداد تقرير عنه بشكل جيد على Haiku، الذي كان سعره في يوليو 2026 يبلغ $1 لكل مليون token للإدخال و$5 لكل مليون token للإخراج. عندما يستخدم الوكيل عدة أدوات ويحتاج إلى التخطيط بينها، انتقل إلى Sonnet. المشكلة التي تتجنبها هي أن يستدعي نموذج رخيص الأداة الخطأ أربع مرات، فتكون تكلفته أعلى من تكلفة النموذج الأغلى الذي يستدعي الأداة الصحيحة مرة واحدة.

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

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

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

افتح عقدة AI Agent. يحتوي المعلّم Prompt على إعدادين.

• يتوقع الخيار Take from previous node automatically حقلاً وارداً باسم 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: امنح الوكيل أداة واحدة

يرفض تشغيل عقدة AI Agent التي لا تحتوي على عقدة أداة فرعية. ابدأ بأداة واحدة، لأن الأداة العاملة الواحدة تعلّمك أكثر من أربع أدوات نصف مهيّأة.

صِل عقدة 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 الخاص بك بدلاً من واجهة API مدفوعة للبحث، شرط أن تتعامل مع كل صفحة تعيدها باعتبارها نصاً غير موثوق أصبح الآن داخل prompt.

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

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

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

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

لا تعمل Simple Memory في workflow إنتاجي نشط عندما يعمل n8n في queue mode، لأن السجل يبقى في بيانات workflow نفسه بدلاً من تخزين مشترك. في مثيل يعمل في queue mode، استخدم العقدة الفرعية 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" وظيفة فعلية هنا. من دونها، قد يتجاوز النموذج الأداة ويرد اعتماداً على ذاكرته إذا اعتقد أنه يعرف الإجابة مسبقاً. ويصبح الرد خاطئاً بثقة فور تغيّر البنية الأساسية لديك.

لماذا يكرر الوكيل الحلقة، وما الذي يوقفه

يوجد ضمن الخيارات أيضاً الحد الأقصى للتكرارات، وتبلغ قيمته الافتراضية 10. التكرار الواحد هو استدعاء واحد للنموذج، إضافةً إلى نتيجة أداة واحدة تُعاد إلى السياق. لذلك لا يعني تشغيل الوكيل مرة واحدة إجراء استدعاء API واحداً، بل قد يتضمن ما يصل إلى عشرة استدعاءات، ويحمل كل استدعاء منها المحادثة الكاملة المتنامية كمدخل.

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

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

راقب تنفيذ إحدى التشغيلات من shell.

docker compose logs -f n8n

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

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

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

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

FAQ

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

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

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

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

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

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

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

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