كيفية بناء وكيل n8n للذكاء الاصطناعي على VPS

ما هو وكيل n8n للذكاء الاصطناعي، وكيف يختلف عن السلسلة

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

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

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

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

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 لكل رمز، وهي منفصلة عن أي اشتراك في Claude.ai، لذلك يجب إعداد الفوترة للحساب قبل التشغيل الأول.

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

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

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

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

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

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

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

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

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

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

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

الخطوة 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، بل من 10 استدعاءات كحد أقصى، ويحمل كل استدعاء منها المحادثة الكاملة المتزايدة كمدخل.

اخفض هذه القيمة. تنتهي معظم الوكلاء الذين يستخدمون أداة واحدة في تكرارين، ويحوّل الحد البالغ 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

لماذا ترفض عقدة وكيل الذكاء الاصطناعي التنفيذ؟

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

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

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

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

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

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

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