لماذا يعلق وكيل التوليد التلقائي في حلقات لا نهائية - وكيفية إصلاح ذلك

هناك تغيير هام في المنصة يجب معرفته قبل تصحيح أخطاء حلقة AutoGen. اعتبارًا من سبتمبر 2026، أصبح مستودع AutoGen الرسمي في وضع الصيانة: من المتوقع أن يتلقى تحديثات للصيانة فقط بدلاً من ميزات جديدة، وتوصي مايكروسوفت باستخدام Microsoft Agent Framework للمشاريع الجديدة. لا يزال مستودع AutoGen الرسمي يُدرج Python 0.7.5 كإصدار مستقر حالي، بينما نشرت مايكروسوفت دليلًا محدثًا للهجرة من AutoGen إلى Agent Framework في 25 أغسطس 2026. مع ذلك، إذا كنت تستخدم AutoGen بالفعل في بيئة الإنتاج، فإن تقنيات استكشاف الأخطاء وإصلاحها المذكورة أدناه تظل مفيدة بشكل مباشر. راجع مستودع AutoGen الرسمي ، وإصدارات AutoGen الرسمية ، ودليل مايكروسوفت للهجرة من AutoGen .

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

تشخيص سريع: ما نوع الحلقة التي تراها؟

1. أضف نقطة توقف صارمة قبل تصحيح أي شيء آخر

يُوفّر AutoGen AgentChat شروط إنهاء مُدمجة خصيصًا للحفاظ على ترابط فرق العمل. تتضمن الوثائق المُعتمدة ما يلي : [ MaxMessageTerminationأدخل TextMentionTerminationالشروط هنا ] . TokenUsageTerminationراجع وثائق إنهاء AutoGen الرسمية .TimeoutTerminationHandoffTerminationSourceMatchTerminationExternalTerminationStopMessageTerminationTextMessageTerminationFunctionCallTerminationFunctionalTermination

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

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

done = TextMentionTermination("TERMINATE")
safety_cap = MaxMessageTermination(max_messages=25)

termination = done | safety_cap

من الأخطاء الشائعة الاعتماد فقط على عبارة "قل TERMINATE عند الانتهاء". هذا يجعل صحة النموذج تعتمد على سلوكه. خطأ آخر هو دمج الشروط &عندما يكون المقصود هو "التوقف عند أي منهما". يدعم AutoGen كلاً من "AND" و"OR"، لذا اختر الدلالات بعناية.

ما الذي يُصلحه هذا؟

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

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

2. اجعل الإكمال قابلاً للكشف بواسطة الآلة، وليس مجرد محادثة.

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

إذا كنت تستخدم هذه الطريقة TextMentionTermination("TERMINATE")، فحدد المسؤولية بوضوح: أي جهة مخولة بإعلان الإنجاز، وتحت أي شرط مُتحقق؟ تجنب إعطاء كل مشارك تعليمات غامضة مثل "استمر حتى الرضا". هذا النوع من التعليمات قد يُنتج سلوكًا لا نهاية له من النقد وإعادة الكتابة لأن "الرضا" ليس له حدود قابلة للملاحظة.

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

3. قم بإصلاح توجيه SelectorGroupChat قبل إعادة كتابة جميع مطالبات الوكيل

SelectorGroupChatيستخدم نموذجًا لاختيار المتحدث التالي من سياق المحادثة المشتركة. تشير الوثائق الرسمية إلى أهمية أسماء المشاركين وأوصافهم لأنها تُستخدم في اختيار المتحدث. افتراضيًا، لا يتم اختيار المتحدث نفسه بشكل متكرر إلا إذا كان هو الوكيل الوحيد المتاح، مع إمكانية allow_repeated_speaker=Trueتغيير هذا السلوك. يوفر AutoGen أيضًا خيارات تحكم أكثر دقة selector_funcعند candidate_funcالحاجة. راجع وثائق SelectorGroupChat الرسمية .

إذا استمر اختيار نفس المشارك، فتحقق من هذه الأمور بالترتيب التالي:

• وصف الوكلاء: يجب أن يوضح كل وصف وظيفة الوكيل ومتى يجب اختياره. يؤدي تداخل الأوصاف إلى عدم استقرار التوجيه.
• تنبيه المُحدِّد: اجعل قواعد التوجيه قصيرة بما يكفي لتطبيق النموذج بشكل موثوق. توصي وثائق AutoGen صراحةً بالنظر في استخدام مُحدِّد مُخصَّص عندما يبدأ التنبيه بتجميع العديد من الشروط.
• إعداد مكبر الصوت المتكرر: اتركه allow_repeated_speakerخارج هذا الإعداد إلا إذا كانت هناك حاجة فعلية إلى تكرار التشغيل.
• تقييد المرشحين: إذا كان هناك وكيلان فقط صالحان بعد حالة معينة، فقم بتقييد مجموعة المرشحين بدلاً من مطالبة النموذج بالاختيار من بين كل مشارك.
• الانتقالات الحتمية: تُستخدم selector_funcعندما يكون سير العمل في الواقع عبارة عن آلة حالة متنكرة في صورة محادثة.

يكمن الفرق الأساسي في أمر بسيط: استخدم اختيار المتحدث بناءً على نموذج اللغة واللغة عندما يتطلب المتحدث التالي حكماً دلالياً حقيقياً. استخدم التوجيه الحتمي عندما يُملي حالة سير العمل المتحدث التالي.

4. أوقف استدعاءات الأدوات المتكررة من خلال إظهار التقدم المحرز

في AgentChat الحالي، AssistantAgentيوجد max_tool_iterationsمُعامل. تشير وثائق واجهة برمجة التطبيقات المستقرة إلى أن القيمة الافتراضية هي 1؛ عند زيادتها، يُمكن للوكيل إجراء استدعاءات أدوات متسلسلة إضافية حتى يُعيد النموذج استجابة نصية أو يتم الوصول إلى الحد الأقصى. هذا يعني أن تشغيل الوكيل الواحد محدود بهذا الإعداد، ولكن لا يزال بإمكان الفريق اختيار نفس الوكيل مرة أخرى وتكرار نمط فشل الأداة نفسه عبر الأدوار. راجع مرجع واجهة برمجة تطبيقات AssistantAgent الرسمي .

agent = AssistantAgent(
    name="worker",
    model_client=model_client,
    tools=[lookup_tool],
    max_tool_iterations=3,
)

إذا تكررت نفس الأداة والوسائط مرارًا وتكرارًا، فإن تقليل حد التكرار لا يحل المشكلة تمامًا. يكمن الحل الجذري عادةً في عقد الأداة. يحتاج النموذج إلى معلومات كافية لتحديد ما إذا كانت العملية قد نجحت، أو فشلت بشكل دائم، أو فشلت مؤقتًا، أو لم تُنتج أي معلومات جديدة.

يفضل الحصول على نتيجة موجزة وواضحة مثل:

{
    "status": "no_new_data",
    "query": "customer_123",
    "retryable": false,
    "reason": "record already checked",
    "next_action": "return_to_planner"
}

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

تحقق أيضًا من استدعاءات الأدوات المتوازية

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

5. كسر نظام التمريرات المتتالية في فرق أسلوب السرب

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

يمكن حل هذه المشكلة بتحديد شرط دقيق وقاعدة لما يحدث عند تعذر إحراز تقدم في كل عملية تسليم. بالنسبة لسير العمل التفاعلي مع المستخدم، HandoffTermination(target="user")صُمم النظام لإيقاف الفريق عند عودة التحكم إلى التطبيق أو الشخص المعني. كما توضح وثائق AutoGen الخاصة بالتدخل البشري أن سير عمل Swarm يتطلب استئنافًا متعمدًا للعمل بعد تسليم المستخدم. راجع الوثائق الرسمية الخاصة بالتدخل البشري .

يتضمن عقد التسليم الجيد ما يلي:

• القدرة الدقيقة التي يمتلكها الهدف؛
• الأدلة التي تبرر عملية التسليم؛
• ما الذي يجب أن يعيده الهدف في حالة نجاحه؟
• ما الذي ينبغي على الهدف فعله في حالة عدم توفر المعلومات المطلوبة؟
• حظر إعادة المهمة دون تغيير.

6. تعامل مع دورات GraphFlow على أنها حلقات حقيقية تحتاج إلى مخارج صريحة

GraphFlowيدعم هذا النظام الحلقات المتعمدة، والتفرع الشرطي، ونقاط الخروج من الحلقات. يصف الإصدار المستقر من واجهة برمجة التطبيقات الحلقات بأنها صالحة فقط عند وجود شرط يؤدي في النهاية إلى الخروج من الحلقة، ويتحقق المُنشئ من صحة بنية الرسم البياني. كما أنه مصنف كإصدار تجريبي. قد تستمر الحلقة الصالحة هيكليًا لفترة طويلة جدًا إذا كان شرط الخروج غير قابل للتحقيق منطقيًا، لذا يُنصح بالاحتفاظ بشرط إنهاء مستقل أو تحديد حد زمني حوله. راجع مرجع واجهة برمجة تطبيقات فرق AutoGen الرسمي .

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

7. إعادة ضبط الحالة عندما تكون المهمة التالية غير ذات صلة

يحتفظ وكلاء وفرق AgentChat بحالة المحادثة. تشير وثائق AutoGen المستقرة إلى أن الفريق يحتفظ بسياق المحادثة بين عمليات التشغيل لضمان استمرار المهام ذات الصلة، كما يوفر reset()إمكانية مسح حالة الفريق والمشاركين. يُعد هذا السلوك مفيدًا للاستمرار، ولكنه قد يبدو كحلقة مفرغة إذا ورثت مهمة غير ذات صلة سياقًا قديمًا أو تفويضًا غير مكتمل أو افتراضات سابقة.

await team.reset()
result = await team.run(task=new_unrelated_task)

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

8. سجل عملية الانتقال، وليس النص النهائي فقط.

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

كحد أدنى، سجل:

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

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

خط أساس عملي وآمن

بالنسبة لتطبيق AutoGen AgentChat الحالي، فإن خط الأساس المتحفظ هو:

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

ما لا يجب فعله

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

متى يجب الترحيل بدلاً من الاستمرار في الترقيع؟

إذا كنت تُجري صيانة لتطبيق AutoGen موجود، فإن هذه الإصلاحات مناسبة، والوثائق الحالية لا تزال متاحة. أما بالنسبة لنظام جديد أو إعادة كتابة شاملة لعملية التنسيق، فإن حالة وضع الصيانة تُغيّر القرار. تُوجّه مايكروسوفت الآن المستخدمين الجدد إلى Microsoft Agent Framework، وتصف وثائق الترحيل الخاصة بها التحوّل من نظام AutoGen الأساسي القائم على الأحداث وفرق العمل عالية المستوى إلى سير عمل مُصنّف وقائم على الرسوم البيانية. هذا لا يعني وجوب ترحيل حلقة AutoGen فورًا، ولكنه يعني أنه يجب عليك مُوازنة تكلفة أعمال التنسيق المُعمّقة الخاصة بـ AutoGen مُقارنةً بالانتقال إلى البديل المدعوم.

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

المراجع الرسمية

• مستودع Microsoft AutoGen — إشعار وضع الصيانة الحالي.
• إصدارات AutoGen — معلومات عن إصدارات Python المستقرة.
• دليل إنهاء خدمة AutoGen AgentChat .
• دليل AutoGen SelectorGroupChat .
• مرجع واجهة برمجة تطبيقات AutoGen AssistantAgent .
• دليل فرق AutoGen .
• دليل ترحيل Microsoft AutoGen-to-Agent-Framework — تم التحديث في 25 أغسطس 2026.