الأخطاء والتعافي، توثيق AGENTO v1.1.0

اختر بين الإصلاح والسؤال والتحديث والتحقق من التنفيذ

تفيد رموز الأخطاء عندما تقود إلى إجراء صحيح. ابدأ بالتفريق بين استثناء بدء التشغيل ونتيجة العملية. YAML غير الصالحة تفشل إنشاء Runtime، أما Selection المنتهية فتعود عادةً ضمن AgentResult بالقيمة status: "error".

عند خطأ في Config أو Mapping، صحح القواعد أو المسارات لتطابق متطلبات الـ API. وفي مدخل مستخدم غير صالح، وضّح قيد الحقل. وعند انتهاء Selection، اجلب خيارات جديدة. ولـ401 و403، استخدم تجربة تسجيل الدخول أو الصلاحيات. أما الكتابة التي ربما وصلت، فتحقق من حالتها لدى backend قبل اقتراح محاولة جديدة.

تتبّع انتهاء المهلة بعد الموافقة

تخيّل أن API قبلت POST الحجز، لكن الرد ضاع. بدء invocation جديد قد ينشئ حجزًا آخر. افحص error.details.executionMayHaveOccurred وسجل idempotency والاستعلام عن حالة العملية لدى API. النتيجة error لا تثبت أن Side Effect لم تحدث.

بالمقابل، غياب حقل قبل أي tool call لم يرسل الكتابة. استخدم meta.toolCalls وأحداث دورة الحياة لفهم المرحلة، وتعامل مع عدم اليقين كما يصرّح به Runtime.

يظهر RATE_LIMITED عند استنفاد حد الفترة الزمنية، وRATE_SESSION_LIMIT عند استنفاد حد الـ Session طوال عمرها. أما Response 429 من الـ API فتظهر باسم TOOL_RATE_LIMITED. تختلف معالجة ميزانية التطبيق عن معالجة سعة API.

استخدم الجداول التالية كمرجع بعد تحديد الحد الذي فشل. يبدأ استكشاف المشاكل من الأعراض.

بنية نتيجة الخطأ

تعيد عمليات Runtime الأخطاء على شكل بيانات:

{
  "status": "error",
  "error": {
    "code": "AUTH_REJECTED",
    "category": "AUTH",
    "message": "Upstream API rejected the request.",
    "details": {
      "status": 401
    }
  }
}

أما فشل الإعداد أو بدء التشغيل فيرمي AgentRuntimeError، لأن Runtime لم يتمكن من التهيئة بأمان.

الفئات

يستنتج AgentRuntimeError الفئة من بادئة رمز الخطأ:

CONFIG
MODEL
ROUTING
INPUT
SESSION
AUTH
TOOL
DEPENDENCY
CONFIRMATION
RATE
INTERNAL

أخطاء الإعداد الشائعة

الرمز	المعنى أو الإجراء التالي
`CONFIG_INVALID`	YAML أو بنية الإعداد غير صالحة، أو تم توفير أكثر من مصدر إعدادات.
`CONFIG_SCHEMA_INVALID`	JSON Schema للـ Tool غير مدعومة أو غير آمنة.
`CONFIG_SECRET_MISSING`	مفتاح اعتماد مطلوب لخدمة أو Provider غير متاح.
`CONFIG_AUTH_INVALID`	إعداد Auth أو النقل غير آمن.
`CONFIG_URL_INVALID`	URL الـ Tool يخالف قواعد الأمان في Runtime.
`CONFIG_MAPPING_INVALID`	تعارض في Mapping، أو قراءة بيانات غير معرّفة.
`CONFIG_DEPENDENCY_INVALID`	مصدر الـ Dependency أو وجهتها يخالف قواعد تعريفها.
`CONFIG_DEPENDENCY_CYCLE`	توجد حلقة دائرية في الـ Dependencies التلقائية.
`CONFIG_CONFIRMATION_INVALID`	Tool ذات أثر لا تملك Confirmation المطلوب.

أخطاء Routing والـ AI Model

الرمز	المعنى أو الإجراء التالي
`MODEL_NOT_CONFIGURED`	تتطلب `chat()` أو صياغة النتائج بالـ AI Model وجود AI Model.
`MODEL_PROVIDER_ERROR`	فشل الاتصال بطبقة Provider أو التعامل معها.
`MODEL_RESPONSE_MALFORMED`	تعذّر تحليل Response Provider أو الـ AI Model بأمان.
`MODEL_SCHEMA_VIOLATION`	اختيار الـ Tool أو مدخلاتها يخالف Schema المتوقعة.
`MODEL_TOOL_SELECTION_FAILED`	اختار الـ AI Model Tool خارج مجموعة المرشحين المسموحة.
`ROUTING_NO_MATCH`	لم تتطابق أي Tool، والمحادثة معطّلة.

أخطاء الـ Input والاستكمال

الرمز	المعنى أو الإجراء التالي
`INPUT_SCHEMA_VIOLATION`	الـ Input المقدّمة تخالف Schema الـ Tool.
`INPUT_SELECTION_STALE`	انتهت صلاحية Selection أو لم يعد يطابق السياق. حدّث الخيارات.
`INPUT_SELECTION_INVALID`	الخيار ليس ضمن المجموعة الحالية.
`CONFIRMATION_STALE`	انتهت صلاحية Confirmation، أو تغيّرت العملية المجهّزة أو السياق. جهّز العملية مجددًا.

أخطاء Auth والـ Session

الرمز	المعنى أو الإجراء التالي
`AUTH_REQUIRED`	بيانات اعتماد الخدمة المطلوبة غير متاحة.
`AUTH_REJECTED`	أعادت API المستقبِلة 401 أو 403. يحدد التطبيق المضيف تجربة تسجيل الدخول أو الصلاحيات.
`SESSION_ID_INVALID`	صيغة Session ID غير صالحة.
`SESSION_EXPIRED`	انتهت TTL للـ Session أو تغيّرت الإعدادات. ابدأ مسارًا جديدًا.
`SESSION_CAPACITY`	امتلأت سعة الـ Sessions في الذاكرة. نظّف الـ Sessions أو استخدم تخزينًا مشتركًا.
`SESSION_RUNTIME_DISPOSED`	أُغلق Runtime. توقّف عن إرسال الطلبات إليه.

أخطاء الـ Tools والنقل

الرمز	المعنى أو الإجراء التالي
`TOOL_ABORTED`	إلغاء من التطبيق المضيف أو abort signal.
`TOOL_TIMEOUT`	تجاوزت الخدمة المستقبِلة المهلة.
`TOOL_NETWORK_ERROR`	فشل النقل قبل الحصول على Response آمنة.
`TOOL_REDIRECT_BLOCKED`	حاولت الخدمة إجراء redirect. صحّح REST Endpoint في الإعدادات.
`TOOL_CLIENT_ERROR`	خطأ 4xx غير متعلق بالـ Auth. راجع متطلبات الـ API والقيم المرسلة.
`TOOL_RATE_LIMITED`	أعادت الخدمة 429. أعد المحاولة وفق سياستك فقط.
`TOOL_SERVER_ERROR`	خطأ 5xx من الخدمة. قد يخضع لإعادة المحاولة الآمنة أو circuit breaker.
`TOOL_RESPONSE_MALFORMED`	الـ Response المعلنة كـJSON غير سليمة.
`TOOL_OUTPUT_LIMIT`	تجاوزت الـ Response الحد الأقصى بالبايت.
`TOOL_OUTPUT_SCHEMA_VIOLATION`	خالفت الـ Response Output Schema المعلنة.
`TOOL_CIRCUIT_OPEN`	أوقف الـ Circuit Breaker الطلبات مؤقتًا بسبب تكرار الأعطال.
`TOOL_EXECUTION_UNCERTAIN`	ربما وصلت عملية سابقة ذات أثر إلى backend. تحقّق من النتيجة قبل Retry.

لا تكرّر عملية غير محسومة بلا تحقق

إذا حمل الخطأ details.executionMayHaveOccurred: true أو TOOL_EXECUTION_UNCERTAIN، فلا تعتبر عدم وصول نجاح للعميل دليلًا على أن backend لم ينفّذ شيئًا. استعلم عن حالة العملية، أو طابقها باستخدام idempotency وسجل التدقيق لديك.

رسائل الأخطاء محدودة عمدًا

يتجنّب AGENTO كشف bodies عشوائية من Responses Providers أو API ضمن تفاصيل الخطأ. احتفظ بالسجلات التشغيلية الحساسة داخل بنيتك الموثوقة، وليس في الرسائل الموجّهة للمستخدم.