استكشاف المشاكل وحلّها

حدد المرحلة التي تفشل بهذا الترتيب

1. هل تقبل compileConfig() ملف YAML مع قيم Environment Variables المطلوبة؟ إذا لم يقبله، أصلح مسار الإعداد المذكور في الخطأ أولًا.
2. هل تستطيع invoke() تشغيل الـ Tool بمدخل ثابت واستجابة HTTP من Mock؟ إذا فشل، افحص التحقق والـ Mapping ومسارات الـ Dependencies.
3. هل ينجح الاستدعاء المباشر مع الـ API في Staging؟ إذا فشل، افحص Auth والحالة والنقل وoutput Schema.
4. هل تختار chat() الـ Tool والـ Input نفسيهما؟ عندها فقط افحص قدرات الـ Provider والأوصاف والتلميحات وrecall.
5. هل تستطيع الواجهة متابعة Selection والـ Confirmation بالـ Session المصرّح بها نفسها؟ افحص الانتهاء وحفظ الحالة.

استخدم مثال أول Tool كنقطة بداية معروفة، ثم أضف الميزة التي تفشل. تغيير الـ AI Model بينما request.map غير صحيحة يصعّب تحديد السبب.

جهّز حالة إعادة إنتاج مفيدة

سجّل إصدار Config وID الـ Tool والـ Input بعد إزالة البيانات الحساسة وشكل الـ Response المتوقع وحالة النتيجة ورمز الخطأ وmetrics العملية. استخدم debug: true لتشخيص المرشحين والـ Mapping، ولا تضع بيانات اعتماد في بلاغ المشكلة.

يجب أن يتكرر خطأ compilation دون AI Model. ويجب أن يتكرر خطأ Dependency بعينة API صغيرة وثابتة. أما مشكلة Routing فتحتاج الرسالة نفسها والمرشح المتوقع. بهذه المعلومات يستطيع مطوّرو المكتبة إعادة إنتاج المشكلة وفحصها.

يعيد npm الرمز E404

راجع التثبيت، ونفّذ npm view agento-runtime version dist-tags. عدم توافر الحزمة أو الإصدار مشكلة في السجل أو الإصدار، وليس خطأ YAML أو import في Node. لا تثبّت حزمة مشابهة بالاسم بدلًا منها.

ظهور ROUTING_NO_MATCH في محادثة عادية

تحقق من:

assistant:
  conversation:
    enabled: true

عندما تكون المحادثة معطّلة، فإن قرار عدم اختيار Tool يعيد خطأً عن قصد.

إذا كانت المحادثة مفعّلة وفشل استدعاء الـ AI Model، افحص خطأ Provider بدل إضافة Tools تحية وهمية.

الطلب العربي لا يختار Tool بوصف إنجليزي

تحقق من التالي:

1. AI Model Routing مضبوط.
2. Semantic Recall مفعّل.
3. حجم الفهرس لا يتجاوز حدود recall.
4. Provider والـ AI Model يتعاملان مع العربية بكفاءة كافية.
5. أضف trigger hints عربية واضحة لتحسين زمن الـ Response والتكلفة.

يدعم Lexical Retrieval معالجة النص العربي، لكنه يطابق الكلمات ولا يترجم المفاهيم بين اللغات بنفسه.

الـ AI Model يخترع مدخلًا

يجب أن يرفض Runtime الحقول غير المعرّفة أو غير الصالحة. إذا عبّر المستخدم عن مفهوم مشروع لا يوجد له حقل، أضفه إلى Schema الـ Tool. وإذا كانت القيمة ID يملكه الخادم، فاجلبها عبر Dependency أو Selection أو Reference، بدل توسيع prompt.

حالة needs_input تطلب حقلًا يفترض أن تنتجه الـ Dependency

راجع مسار الحقل الهدف في map الخاصة بالـ Dependency. يجب أن يطابق حقل مدخل الـ Tool الأم تمامًا:

map:
  $.slot_token: $.slot_token

وتأكد أيضًا من تعريف الـ Dependency على الـ Tool الأم الصحيحة.

انتهاء صلاحية Selection بسرعة

ارفع TTL المتعلقة بالـ Dependency أو Selection عن قصد. تذكّر أن Confirmation لا يمكن أن يبقى صالحًا بعد انتهاء بيانات الـ Dependency. لا تضبط مددًا ضخمة عشوائيًا لبيانات سريعة التغيّر، مثل المواعيد المتاحة.

AUTH_REJECTED

ينقل AGENTO Response 401 أو 403 من API لديك. افحص جلب Token وانتهاءه وscopes وربط المتصل بالـ Session وقواعد الصلاحيات في API. لا تضف تحقق JWT محليًا لمحاولة تجاوز API ترفض المتصل بصورة صحيحة.

AUTH_REQUIRED

يعني عادةً أن API key المضبوط للخادم غير متاح. راجع Environment Variable المذكور في request.auth.env.

حظر redirect

صحّح URL المضبوط ليشير إلى REST Endpoint النهائية مباشرةً. متابعة redirects معطّلة عمدًا لمنع إرسال بيانات الاعتماد إلى origin أخرى.

الـ Tool تعمل مباشرةً، لكن chat() تفشل

لا يحتاج الاستدعاء المباشر إلى AI Model، بينما تحتاجه chat(). راجع models.routing أو وفّر ModelAdapter مخصصًا.

MODEL_SCHEMA_VIOLATION

الأسباب الشائعة:

• أعاد Provider Input Tool خارج Schema المعلنة.
• لا تدعم مجموعة tool Schema الصارمة لدى Provider الميزات المتقدمة التي تستخدمها.
• أعاد adapter المخصص Output منظّمة غير سليمة.

جرّب مجموعة Schema مدعومة أو صحّح القدرات المعلنة للـ AI Model، بدل تعطيل التحقق في Runtime.

TOOL_OUTPUT_SCHEMA_VIOLATION

لم يعد الـ Response من الـ API يطابق الشكل المعلن في الـ Config. حدّد إن كانت API تغيّرت أم أن Schema كانت خاطئة. لا تحذف Schema بلا مراجعة إذا كانت خطوات التنفيذ تعتمد على تلك الحقول.

TOOL_CIRCUIT_OPEN

حدثت أعطال مؤقتة كافية في الخدمة لفتح circuit breaker الخاصة بالـ Tool. افحص صحة الخدمة؛ تعرض diagnostics() حالة circuit breaker.

TOOL_EXECUTION_UNCERTAIN

لا تمسح الـ Session فورًا وتكرر عملية دفع أو حجز أو حذف. استعلم من backend باستخدام idempotency key أو ID العملية، وتحقق من النتيجة أولًا.

انتهاء الـ Session بعد النشر

هذا متوقع عند تغيّر Config hash أو انتهاء TTL. ابدأ مسارًا جديدًا؛ يمنع ذلك استكمال عمليات معلّقة قديمة وفق Mappings أو سياسات جديدة.

الرسائل المتزامنة تفسد المسار عبر عدة instances

غالبًا لا يحقق SessionStore المخصص متطلبات تنفيذ المعاملة كاملةً بالتتابع. قيمة Redis مشتركة وحدها لا تكفي دون قفل قابل للتجديد وآلية fencing.