# لماذا تفشل استدعاءات الأدوات بعد نقل وكيل البرمجة إلى نموذج آخر؟ > تفشل استدعاءات الأدوات بعد تبديل النموذج غالبًا لأن النموذج البديل يغيّر البروتوكول أو متطلبات المخطط أو تسلسل الوسائط أو أحداث البث أو سلوك حالة المحادثة. تعامل مع الانتقال كتغيير في العقد، لا كتغيير لاسم النموذج. الاختبار الأول المفيد أصغر من معيار برمجي كامل: اطلب من النموذج البديل استدعاء دالة للقراءة فقط لها وسيطان إلزاميان. إذا فشل، فالمشكلة تقع أسفل طبقة التخطيط. وإذا نجح، فأضف البث وتعدد الأدوات والحالة وعمليات الكتابة واحدًا تلو الآخر حتى تظهر أول نقطة انقطاع في العقد. يكشف تبديل النموذج افتراضات كانت مخفية داخل التكامل القديم. وكيل البرمجة ليس مجرد prompt ونموذج، بل آلة حالات تصل مخرجات النموذج بمحلل البث وسجل الأدوات والمنفذ وحلقة إعادة نتائج الأدوات. ## افصل القدرة عن البروتوكول قد يكون النموذج قويًا في البرمجة لكنه غير متاح عبر البروتوكول الذي يرسله العميل. وقد يقبل نموذج آخر الطلب من دون إعلان دعم الأدوات على ذلك المسار. تحقق من بيانات القدرات قبل تغيير اسم النموذج. يسرد [دليل بروتوكولات LLM في Atlas Cloud](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models) صيغ OpenAI Chat Completions وResponses وAnthropic Messages وGoogle Gemini وغيرها على Base URL واحد. ليست كل النماذج متاحة عبر كل بروتوكول. استخدم `supported_apis` وقدرة الأدوات الخاصة بالنموذج كمصدر للحقيقة. | الطبقة | سؤال الانتقال | إشارة الفشل | |---|---|---| | Endpoint | هل يقبل النموذج هذا البروتوكول؟ | استجابة 400 أو تجاهل الحقول | | القدرة | هل يعلن المسار دعم الأدوات؟ | إجابة نصية بدل الاستدعاء | | المخطط | هل الاسم وJSON Schema صالحان؟ | وسائط ناقصة أو مشوهة | | البث | هل تُجمع دلتا الوسائط صحيحة؟ | JSON مبتور | | الحلقة | هل تعاد النتيجة بالدور الصحيح؟ | استدعاء مكرر أو دورة عالقة | ## اختصر مخطط الأداة إلى عقد واحد ابدأ بدالة ذات اسم قصير وسلسلتين إلزاميتين، من دون union أو تداخل اختياري. تمزج المخططات المعقدة سلوك النموذج بسلوك validator فتبطئ التشخيص. ```json { "type": "function", "function": { "name": "read_file", "description": "Read a UTF-8 text file from the workspace.", "parameters": { "type": "object", "properties": { "path": {"type": "string"}, "max_chars": {"type": "integer", "minimum": 1} }, "required": ["path", "max_chars"], "additionalProperties": false } } } ``` افرض هذه الدالة إذا كان البروتوكول يدعم forced tool choice. يميز الاستدعاء الإجباري بين عدم القدرة على الاستدعاء وقرار التخطيط بعدم استخدام الأداة. ## اختبر من دون بث أولًا تعرض الاستجابة غير المتدفقة كائن الأداة النهائي في payload واحد. أما البث فقد يرسل الاسم وcall ID ووسائط JSON في أحداث منفصلة. لا تحلل الوسائط إلا بعد حدث final أو done الخاص بالبروتوكول. لا تنفذ الأداة لمجرد أن buffer جزئيًا قابل للتحليل كـ JSON؛ قد تمده دلتا لاحقة. احتفظ بالـ buffer حسب call ID، وارفض الإنهاء المكرر، وسجّل ترتيب الأحداث الخام. | ثابت البث | السلوك المطلوب | |---|---| | هوية استدعاء مستقرة | تتجه كل الدلتا إلى buffer واحد | | تجميع مرتب | تضاف الأجزاء حسب ترتيب الأحداث | | اكتمال صريح | ينتظر التنفيذ الحدث النهائي | | تنفيذ واحد | ينفذ الاستدعاء المكتمل مرة واحدة كحد أقصى | ## طبّع حلقة الوكيل بوضوح لا تنشر الحقول الخاصة بالمزود داخل المنفذ. حوّل كل استجابة إلى صيغة داخلية مثل `assistant_text` و`tool_calls` و`usage` و`stop_reason`، ثم أعد النتائج عبر مهايئ البروتوكول. تعامل مع call ID كقيم opaque وحافظ عليها كما هي. تحقق من الوسائط قبل التنفيذ وأعد أخطاء منظمة بدل تعديل JSON غير الصالح بصمت. ## صفّر الحالة في المقارنة الأولى قد يتضمن السجل القديم reasoning blocks أو أدوار نتائج أدوات أو state handles أو رسائل assistant لا يقبلها المسار الجديد. ابدأ محادثة جديدة بتعليمات النظام نفسها، ثم أعد تشغيل سجل قصير ومطبّع. اختصارات الحالة مرتبطة بالبروتوكول. اختبر استمرار التعليمات صراحة بدل افتراض أن response handle سابق يحملها تلقائيًا. ## أنشئ سلّم انتقال شغّل الـ fixture نفسها بهذا الترتيب: * استجابة نصية عادية. * أداة قراءة إجبارية واحدة من دون بث. * اختيار أداة تلقائي واحد من دون بث. * أداة إجبارية واحدة مع البث. * أداتان مستقلتان. * خطأ أداة واحد مع التعافي. * مهمة برمجية قصيرة متعددة الدورات. توقف عند أول فشل وافحص بيانات wire. لا تنتقل مباشرة من health check إلى تعديل repository ذاتي. ## قرر ما إذا كان مهايئ واحد يكفي المهايئ المشترك مناسب عندما تقتصر الفروق على أسماء الحقول أو الأحداث. المهايئات المنفصلة أكثر أمانًا عندما تحتاج النماذج بروتوكولات أو تمثيل سجل أو دلالات نتائج مختلفة. يسهّل Atlas Cloud تجربة النماذج لأن مفتاحًا وBase URL واحدين يتيحان صيغًا متعددة و[كتالوج نماذج LLM](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models) متغيرًا. لكن ذلك لا يلغي فحص القدرات. سجّل النموذج والبروتوكول وإصدار المخطط ووضع البث ونتيجة الاختبار معًا. ## الخلاصة تفشل استدعاءات الأدوات بعد تبديل النموذج عندما يعامل التكامل انتقال السلوك والبروتوكول كاستبدال نصي. تحقق من المسار، وبسّط المخطط، واجتز اختبار الاستدعاء الإجباري من دون بث، ثم تحقق من تجميع البث وأضف حالة المحادثة أخيرًا. إذا اختلفت دلالات الرسائل أو الأحداث فعليًا، فاستخدم مهايئات منفصلة. ## FAQ ### لماذا يجيب النموذج الجديد بالنص بدل استدعاء أداة؟ قد لا يدعم الأدوات عبر البروتوكول المختار، أو يحتاج إعداد tool choice مختلفًا، أو يفسر وصف الأداة بطريقة أخرى. تحقق من بيانات القدرات واختبر استدعاءً إجباريًا واحدًا. ### هل يمكن لنموذجين متوافقين مع OpenAI إرجاع بنيتين مختلفتين لاستدعاء الأداة؟ نعم. قد يتوافق شكل الطلب الخارجي بينما تختلف دلتا البث ومعرّفات الاستدعاء واكتمال الوسائط وأسباب الإنهاء. ### هل ينبغي إعادة استخدام المحادثة القديمة بعد تبديل النموذج؟ فقط بعد التأكد من أن النموذج والبروتوكول الجديدين يقبلان عناصر السجل نفسها. الاختبار الأكثر أمانًا يبدأ بمحادثة جديدة ثم يعيد الحالة تدريجيًا. ### ما أسرع اختبار تشخيصي؟ افرض أداة حتمية للقراءة فقط ذات JSON Schema صغير، وشغّلها من دون بث، وسجّل الطلب والاستجابة الخام قبل اختبار حلقة الوكيل الكاملة. ### هل يوحّد Atlas Cloud كل النماذج في واجهة أدوات متطابقة؟ لا. يدعم Atlas Cloud بروتوكولات متعددة، وينشر كل نموذج واجهات API والقدرات التي يدعمها. يجب على العميل اختيار بروتوكول يدعمه النموذج فعليًا. ### متى يجب الاحتفاظ بمهايئين منفصلين لنموذجين؟ عندما لا يمكن تمثيل كائنات الحالة أو أحداث البث أو رسائل نتائج الأدوات أو دلالات الأخطاء بأمان ضمن عقد موحّد واحد.