LangGraph أم smolagents؟ متى تحتاج إلى وكيل ينفّذ Python

إذا كنت توازن بين smolagents وLangGraph، فاختر smolagents عندما يحتاج وكيلك المكتوب بـ Python إلى الجمع بين الأدوات والحسابات بمرونة أثناء العمل، وتستطيع توفير بيئة مضبوطة لتنفيذ تلك الشيفرة. عدد فئات الوكلاء التي توفرها Hugging Face هو 2: CodeAgent وToolCallingAgent؛ والفارق هو ما إذا كان النموذج يعبّر عن خطوته التالية بشيفرة Python أم باستدعاء منظّم لأداة. تساعد بساطة المكتبة في بناء وكيل يحل مسألة محددة النطاق، لكنها لا تعفيك من مسؤولية استمرارية سير العمل أو إدارة الصلاحيات أو العزل.

جرى التحقق بالرجوع إلى وثائق Hugging Face وLangChain وOpenAI المنشورة، بتاريخ 31 أكتوبر 2026. تقارن التوصيات التالية بين طرق تركيب الإجراءات، والتحكم في سير العمل، وحدود التنفيذ. وهي أحكام تتعلق بالتصميم المعماري، وليست نتائج اختبارات أداء.

كيف يستخدم smolagents شيفرة Python لتنفيذ الإجراءات؟

smolagents مكتبة Python مفتوحة المصدر من Hugging Face لبناء وكلاء يمكنهم التعبير عن إجراءاتهم بشيفرة قابلة للتنفيذ. يعمل الوكيل ضمن حلقة يقودها النموذج: يختار إجراءً، ويرصد ما حدث، ثم يقرر الخطوة التالية. يستخدم CodeAgent شيفرة Python للتعبير عن ذلك الإجراء، بينما يستخدم ToolCallingAgent استدعاءات منظّمة للأدوات. ويقبل كلاهما نموذجًا ومجموعة أدوات. مرجع الوكلاء من Hugging Face.

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

وهذا يختلف عن مساعد يسلّمك ملف شيفرة لمراجعته. هنا، الشيفرة التي يولّدها النموذج هي الوسيلة التي ينفّذ بها الوكيل خطوته التالية.

للمقارنة بصورة مفيدة، حدّد الجزء الذي يحتاج إلى المرونة في تطبيقك:

يصف الصفان الأخيران ما تركز عليه وثائق LangGraph وOpenAI Agents SDK، ولا يعني ذلك أن هذه الإمكانات حصرية لأي منهما. يتوقف القرار على الموضع الذي تريد أن يوفّر فيه إطار العمل بنية واضحة لتطبيقك.

CodeAgent في smolagents: دع النموذج يركّب الإجراءات

تظهر قيمة CodeAgent عندما يكون التعبير عن العمل الوسيط بـ Python أسهل من حصره في قائمة ثابتة من الاستدعاءات. تذكر Hugging Face الحلقات والشروط والجمع بين الأدوات ضمن نقاط قوته، إلى جانب ضرورة التعامل مع الأخطاء النحوية والاستثناءات والسلوك غير المتوقع. الجولة التعريفية.

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

تصبح نتيجة التنفيذ معلومة يستند إليها النموذج في قراره التالي. وإذا أخفقت عملية حسابية، يستطيع الوكيل التعامل مع هذا الإخفاق بوصفه ملاحظة جديدة؛ لكن ذلك لا يثبت أنه سينجح في تصحيح نفسه.

ToolCallingAgent: احصر الإجراءات في قائمة محددة

يمثل ToolCallingAgent نقطة بداية أنسب عندما تكون عملياتك محددة المدخلات والمخرجات والسلوك. فهو يصدر استدعاءات JSON منظّمة تتضمن أسماء الأدوات ومعاملاتها، بدلًا من توليد إجراءات بشيفرة Python. مقارنة Hugging Face.

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

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

اختيار الأدوات مستقل عن اختيار النموذج

احصر مجموعة الأدوات في نطاق ضيق، واختر النموذج بصورة مستقلة. هذا الفصل من أهم مزايا smolagents العملية: يمكنك تغيير طريقة استدلال الوكيل من دون إعادة تعريف كل وظيفة من وظائف العمل.

الأداة دالة لها واجهة واضحة وقابلة للاستخدام

تغلّف الأداة في smolagents دالةً باسم ووصف وبيانات تصف المدخلات ونوع المخرجات. يلائم المُزيّن @tool الدوال البسيطة التي تتضمن تلميحات للأنواع وسلسلة توثيق مفيدة. ولإنشاء أداة أكثر تعقيدًا، اشتق فئة من Tool وضع منطق التنفيذ في forward. دليل الأدوات.

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

يمكن أيضًا جلب الأدوات عبر Model Context Protocol، أو MCP، وهو واجهة معيارية لإتاحة الأدوات لتطبيقات النماذج، وكذلك عبر موائمات أدوات LangChain وHugging Face Spaces. وإعادة استخدام أداة لا تثبت موثوقية تنفيذها. تشترط Hugging Face صراحةً استخدام trust_remote_code=True عند تحميل أدوات Hub، لأنها تشغّل شيفرة مخصصة. وثائق دمج الأدوات وتحميلها.

هذا قرار يستلزم مراجعة الشيفرة. افحص تنفيذ الأداة واعتمادياتها قبل إتاحتها للوكيل.

جهة تشغيل النموذج لا تحدد بيئة عزل الشيفرة

يوثّق مرجع النماذج الحالي عدة خيارات:

• يتصل InferenceClientModel عبر Hugging Face Inference Providers.
• يستخدم LiteLLMModel طبقة التكامل مع المزوّدين في LiteLLM.
• يشغّل TransformersModel نموذجًا من Transformers محليًا.
• يتصل OpenAIModel بخادم نماذج متوافق مع OpenAI.

وتتناول الجولة التعريفية أيضًا استخدام Ollama للاستدلال المحلي. هذه خيارات لجهة تشغيل النموذج، وليست ضمانًا بأن كل النماذج تتساوى في جودة توليد الشيفرة أو اختيار الأدوات.

افصل بين سؤالين: أين يعمل النموذج؟ وأين تُنفّذ شيفرة Python التي يولّدها؟ يمكن لنموذج مستضاف أن يوجّه منفّذ Docker. وقد يولّد نموذج محلي إجراءات غير آمنة. نقل الاستدلال إلى جهازك لا ينشئ بحد ذاته حدودًا تعزل التنفيذ.

لإتاحة تكرار التجربة، حدّد النموذج صراحةً عند تجاوز المثال التوضيحي. تنبّه Hugging Face إلى أن النموذج الافتراضي لـ InferenceClientModel قد يتغير. إعداد النموذج.

مثال تطبيقي صغير مستمد من الوثائق

ابدأ بمهمة الحساب الواردة في الوثائق لفهم مسار التنفيذ قبل إضافة الأدوات. يطلب المثال التمهيدي من Hugging Face حساب مجموع الأعداد من 1 إلى 10، مع مجموعة أدوات فارغة. تحافظ النسخة التالية على المهمة نفسها، وتضيف نمط مدير السياق الخاص بـ Docker من دليل العزل. المثال الأصلي، إعداد التنفيذ في Docker.

1. 1

   جهّز بيئة العمل

   يشترط دليل التثبيت استخدام Python 3.10 أو أحدث، ويوصي ببيئة افتراضية. ويتطلب هذا المثال أيضًا تثبيت Docker وتشغيله. دليل التثبيت.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   اضبط متغير البيئة HF_TOKEN باستخدام رمز وصول من Hugging Face يملك صلاحية استدعاء Inference Providers. يستطيع InferenceClientModel قراءة هذا المتغير تلقائيًا. لا تضع رمز الوصول داخل البرنامج. آلية المصادقة.

2. 2

   شغّل المهمة الموثّقة داخل Docker

   احفظ الشيفرة التالية في ملف sum_agent.py:

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   ثم شغّل:

   python sum_agent.py

   يتولى مدير السياق تنظيف بيئة العزل عند الخروج من الكتلة البرمجية. هذا مثال معدّل عن الوثائق، وليس نتيجة تنفيذ لاختبار أُجري من أجل هذا المقال.

3. 3

   تحقق من النتيجة وحدود التنفيذ

   الإجابة الرياضية المتوقعة هي 55، وفق العملية 10 × 11 ÷ 2. يختار النموذج شيفرة Python التي يولّدها، لذلك لا تفترض تطابق سجل التنفيذ أو صياغة الإجابة في كل تشغيل.

   تعني tools=[] أنك لم تزوّد الوكيل بأدوات مخصصة. ولا تعني أن CodeAgent فقد قدرته على تنفيذ Python. إعداد المنفّذ هو ما ينقل تلك الشيفرة المولّدة إلى Docker.

لهذه العملية الحسابية الثابتة، تكون شيفرة Python العادية هي الخيار المنطقي في التطبيق. والغرض من المثال هو إظهار آلية عمل الوكيل. أضف وكيلًا عندما يكون اختيار الخطوات الوسيطة جزءًا من المشكلة، لا لمجرد أن العملية الحسابية قابلة للوصف باللغة الإنجليزية.

الوكلاء الذين ينفّذون الشيفرة يحتاجون إلى بيئة عزل

تعامل مع شيفرة Python المولّدة بوصفها شيفرة غير موثوقة، ووفّر لها بيئة عزل صريحة قبل تعريضها لمدخلات غير موثوقة. المنفّذ المحلي الافتراضي مفسّر مقيّد، وليس ضمانًا لعزل الجهاز المضيف. تذكر Hugging Face أخطاء النموذج، وحقن التعليمات، والطلبات العدائية ضمن المخاطر. التنفيذ الآمن للشيفرة.

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

ما خيارات العزل التي تذكرها Hugging Face؟

تدعم واجهة المنفّذ الحالية Blaxel وE2B وModal وDocker، إلى جانب المنفّذ المحلي. تتطابق أسماء الإعدادات أدناه مع مرجع CodeAgent ومرجع المنفّذات.

اختر المزوّد وبيانات الاعتماد بصورة منفصلة عن هذه الإعدادات. تسرد وثائق التثبيت الاعتماديات الاختيارية؛ فتثبيت إضافة وحده لا يجهّز بيئة النشر.

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

عزل المقاطع البرمجية لا يعزل منظومة الوكيل كلها

حدّد ما الذي سيعمل داخل حدود العزل قبل إضافة المزيد من الوكلاء. تميّز Hugging Face بين تشغيل المقاطع المولّدة في بيئة عزل وتشغيل منظومة الوكيل كاملةً فيها. ويحذّر دليلها الأمني من أن أسلوب عزل المقاطع وحدها لا يدعم الوكلاء المُدارين، أي الوكلاء الذين يستدعيهم وكيل آخر لمساعدته. ونقل المنظومة كاملةً إلى الداخل يتطلب إعدادًا إضافيًا، وقد يتطلب تزويدها ببيانات اعتماد. أساليب العزل.

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

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

smolagents أم LangGraph؟ متى تكفي بساطة الإطار؟

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

smolagents أم LangGraph: مرونة الإجراءات أم استمرارية سير العمل؟

يمثل LangGraph نقطة بداية أقوى عندما تحتاج عمليتك إلى حفظ حالتها والتوقف والاستئناف عبر حالات أعمال صريحة. فهو بيئة تشغيل للتنسيق على مستوى منخفض، مخصصة لتدفقات العمل ذات الحالة، وتدعم حفظ الحالة وإدخال المراجعة البشرية في سير العمل. ويمكنها الجمع بين خطوات حتمية وأخرى يقودها النموذج، ولا تشترط استخدام LangChain. نظرة عامة على LangGraph.

تصوّر سير عمل للمشتريات يجمع الأدلة، وينتظر قرار مدير، ثم يستأنف بعد الموافقة. المشكلة المحورية هنا هي الحفاظ على حالة العملية وفرض الانتقال المسموح به. ابدأ بـ LangGraph إذا كانت هذه المتطلبات هي ما يحدد طبيعة المنتج.

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

اختر smolagents عندما يكون السؤال المفتوح أساسًا هو: أي عمليات Python ستحل هذه المهمة؟ واختر LangGraph عندما يكون السؤال: كيف تنتقل هذه العملية بأمان عبر حالات محفوظة وقابلة للاستئناف؟ هذه توصية تصميمية، وليست ادعاءً بأن أيًا من الإطارين لا يصلح إلا لنوع واحد من العمل.

OpenAI Agents SDK: إحالة المحادثات والفحوص وتتبّع التنفيذ

يكون OpenAI Agents SDK خيارًا افتراضيًا أنسب عندما يتمحور التطبيق حول تنسيق الوكلاء المتخصصين والفحوص التشغيلية. تنقل آليات الإحالة فيه مسؤولية المحادثة إلى وكيل آخر؛ بينما يتيح نمط الوكلاء كأدوات لوكيل مدير الاحتفاظ بمسؤولية الرد. وثائق التنسيق.

في مساعد لخدمة العملاء، قد يكون إسناد المحادثة إلى وكيل متخصص في الفوترة أوضح تصميمًا من الاعتماد على وكيل عام يحل المسائل بـ Python. يسجّل التتبّع المدمج استدعاءات النماذج والأدوات، والإحالات، وضوابط الحماية. وتوفّر ضوابط الحماية فحوصًا آلية، بينما توقف آليات المراجعة البشرية الإجراءات الحساسة انتظارًا لقرار. تتبّع التنفيذ، ضوابط الحماية والمراجعة.

وتظل سياسة التطبيق مسؤوليتك: تحديد ما يستدعي الموافقة، وتنفيذ الأداة بصورة صحيحة، والتعامل مع العمل المنقطع. هذه المكونات الأساسية لا تضع تلك السياسة نيابةً عنك. وتوثّق الحزمة أيضًا أنماطًا لوكلاء يعملون في بيئات عزل، لذا فإن تنفيذ الشيفرة ليس حكرًا على smolagents.

فضّل smolagents عندما تكون الميزة المطلوبة هي تركيب الإجراءات بـ Python، وتكفيك حلقة صغيرة. واختر Agents SDK عندما تلائم مكوناته للتنسيق والمراجعة التطبيق الذي تبنيه. وصف الإطار بأنه «خفيف» لا يحسم المقارنة وحده.

لتوسيع قائمة الخيارات، راجع مقارنة أطر عمل وكلاء الذكاء الاصطناعي. وإذا كنت تبحث عن تطبيق وكلاء جاهز للتثبيت بدلًا من مكتبة تبني عليها، فابدأ بـ دليل وكلاء الذكاء الاصطناعي مفتوحة المصدر.

أين تُبالغ الوعود المتعلقة بوكلاء تنفيذ الشيفرة؟

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

لا تحوّل قابلية الجمع بين العمليات إلى وعد عام بالسرعة. قد يغيّر دمج العمليات شكل التشغيل؛ لكن النتيجة تظل مرهونة بالنموذج، والمهمة، وسلوك الأدوات، وبيئة التنفيذ. قِس الأداء على مهمتك أنت قبل اتخاذ قرار مبني عليه.

وهناك حد محدد ينبغي فهمه: القيمة الافتراضية لـ max_steps هي 20 في واجهة الوكلاء الحالية. وهي تحدّ عدد خطوات الوكيل، لا الموارد التي يستهلكها إجراء Python واحد. وتتيح الواجهة أيضًا دوال ردّ نداء، ووكلاء مُدارين، وفحوصًا للإجابة النهائية؛ لذا لا ينبغي الخلط بين البساطة وغياب الضوابط. مرجع الوكلاء.

عمليًا، عليك ضبط حدود وقت التنفيذ والموارد بصورة منفصلة. فسقف الخطوات لا يغني عن سياسة للعزل، وبيئة العزل لا تضمن صحة النتيجة.

بماذا تبدأ الأسبوع المقبل؟

ابدأ بمهمة محدودة النطاق، للقراءة فقط، ويمكنك التحقق من إجابتها بصورة مستقلة. يمكن لمطور Python يقيّم smolagents أن يستخدم ملفًا مصدّرًا للمخزون بعد تنقيته من البيانات الحساسة، وأداة بحث ضيقة النطاق، ثم يقارن الفروقات التي يقترحها الوكيل بأمثلة معروفة.

سجّل ما إذا كان الوكيل قد اختار السجلات الصحيحة، واستخدم الأدوات كما ينبغي، وتعافى من الإخفاقات المتوقعة، وتوقف ضمن الحدود التي وضعتها. واحتفظ بحل حتمي مرجعي للمقارنة. إذا كانت المهمة تتبع المسار نفسه دائمًا، فاكتب ذلك المسار بشيفرة عادية؛ إذ تفضّل إرشادات Hugging Face نفسها الدوال الحتمية كلما أمكن. بناء وكلاء جيدين.

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

التثبيت والتوافق

كيف تثبّت smolagents باستخدام pip؟

ثبّت المكتبة الأساسية باستخدام pip install smolagents. ثم أضف الإضافات التي تحتاج إليها أدواتك أو نماذجك أو بيئة التنفيذ. يستخدم المثال التطبيقي smolagents[docker].

ماذا عن HfApiModel في smolagents؟

عند كتابة شيفرة جديدة، اتبع واجهة InferenceClientModel الواردة في الوثائق الحالية. وقارن الأمثلة القديمة بمرجع النماذج المنشور قبل نسخ تعليمات الاستيراد منها.

كيف تشغّل smolagents داخل Docker؟

ثبّت Docker وشغّله، وثبّت إضافة Docker، ثم اختر executor_type="docker". اضبط حدود التنفيذ بما يناسب عبء العمل؛ فهذا الإعداد وحده ليس سياسة أمنية متكاملة.

اشترك في النشرة لتصلك ملاحظات عملية عن البناء بالذكاء الاصطناعي.