اختر السياسة بحسب نوع فشل REST Endpoint
اقرأ Side Effects قبل تفعيل Retry الكتابة. فشل قراءة قبل وصول البيانات يختلف عن حجز انتهت مهلته بعد أن قبلته API.
ابدأ لاستعلام availability عبر GET بمحاولتين إجمالًا، ومهلة قصيرة، وحد Response مناسب لعينة فعلية. أما POST للحجز فأبقِه على محاولة واحدة حتى يدعم backend آلية idempotency، أو تكون العملية نفسها idempotent فعلًا.
# Merge into request on a read-only tool.
timeout_ms: 5000
max_response_bytes: 262144
retry:
attempts: 2
backoff_ms: 300
multiplier: 2
jitter: true
إذا جاءت 503 ثم 200، يسمح الإعداد بإعادة واحدة ويستهلك وحدتين من ميزانية tool calls. أما 401 فلا تُعاد. وإذا كانت API بطيئة دائمًا، فلكل محاولة مهلة مستقلة؛ قد تتجاوز العملية الكاملة خمس ثوانٍ بسبب تراكم المحاولات والانتظار.
عندما تكتب idempotent: true، فأنت تؤكد أن الـ API تدعم تكرار العملية دون تكرار أثرها. لا يضيف هذا الخيار منع التكرار إلى الـ API. كذلك لا تكفي attempts: 3 للسماح بتكرار عملية كتابة غير آمنة؛ تبقى لها محاولة واحدة. وقد يوقف الـ Circuit Breaker المحاولات قبل بلوغ العدد المحدد.
اختبر أثر كل حد
الافتراضي للمهلة 8000 مللي ثانية، ولحجم الـ Response 1 MiB، وللمحاولات واحدة. تسمح الزيادة بإكمال عمل أكبر، لكنها تزيد الانتظار واستهلاك الذاكرة وحمل API. يبدأ backoff افتراضيًا من 500 مللي ثانية، بمعامل 2 وjitter مفعّل؛ يختار jitter انتظارًا بين نصف المدة المحسوبة وكاملها، بعد تقييدها بحد 60 ثانية.
يوقف الـ Circuit Breaker الطلبات مؤقتًا بعد العدد المحدد من الأعطال المؤقتة، بما فيها محاولات الإعادة الفاشلة. العتبة الافتراضية خمسة، ومدة إعادة الاختبار 30 ثانية. تُحفظ الحالة لكل Tool داخل Runtime واحدة، وليس عبر جميع workers.
اختبر 503 ثم 200، و401، و429، وredirect، واستجابة ضخمة، وJSON غير صالح، والإلغاء. وللكتابة، تأكد من إعادة استخدام idempotency header نفسه ضمن الإعادات، وإذا لم تعرف هل وصل الـ Request ونُفّذ، فتحقق من النتيجة لدى الـ API؛ غياب Response ناجح لا يثبت أن الكتابة لم تحدث.
يشكّل HttpExecutor طبقة مستقلة في Runtime، ووظيفته تتجاوز استدعاء fetch(config.url).
أمان الطلب
قبل التنفيذ وأثناءه، يفرض AGENTO:
- الالتزام بـorigin الثابت في الإعدادات.
- منع اسم المستخدم وكلمة المرور داخل URL.
- HTTPS لبيانات الاعتماد، إلا عند تعطيله صراحةً للتطوير المحلي.
- معالجة redirects يدويًا ورفض 3xx.
- مهلة زمنية محددة.
- دعم الإلغاء.
- حدًا لحجم الـ Response بالبايت.
- بناء method و
headersوqueryوbodyبطريقة حتمية.
Timeout
request:
timeout_ms: 8000
تشمل المهلة جلب الـ Response وقراءة body. ويمكن أيضًا تمرير AbortSignal من التطبيق المضيف:
await runtime.chat({
sessionId,
message,
signal: request.signal,
});
سياسة Retry
request:
retry:
attempts: 3
backoff_ms: 500
multiplier: 2
jitter: true
idempotent: true
تعني attempts إجمالي عدد المحاولات، وليس عدد المحاولات الإضافية. وتحدد Schema سقفًا قدره 5.
تُسمح محاولات Retry التلقائية عندما تكون العملية آمنة:
- للقراءة فقط؛ أو
- معلنة صراحةً بأنها
idempotent؛ أو - معدّة لاستخدام idempotency key.
في غير هذه الحالات، تحصل عملية Side Effect على محاولة واحدة.
تشمل الأعطال المؤقتة مشاكل الشبكة وانتهاء المهلة، واستجابات 429 و5xx.
Idempotency key
request:
idempotency:
header: Idempotency-Key
source: generated
ينشئ AGENTO المفتاح ضمن تجهيز العملية. يجب أن يطبّق backend سلوك idempotency فعليًا؛ إرسال header وحده لا يوفّر هذا الضمان.
Circuit breaker
request:
circuit_breaker:
threshold: 5
reset_ms: 30000
تُحفظ حالة circuit breaker لكل Runtime وTool. أخطاء الصلاحيات أو العميل المعتادة من فئة 4xx لا تُحتسب كعدم استقرار للخادم. وبعد إعادة الضبط، يُسمح بطلب اختبار واحد.
قراءة الـ Response
- تعيد 204 و205 وHEAD القيمة
null. - تُحلّل الـ Responses ذات نوع محتوى JSON.
- يُعامل JSON غير السليم كخطأ مستقل في Runtime.
- تبقى الـ Responses النصية نصوصًا.
- تُرفض redirects من فئة 3xx.
- تُحوّل 401 و403 إلى
AUTH_REJECTED. - تُحوّل 429 إلى خطأ Tool خاص بتجاوز معدل الطلبات.
- تُعالج 5xx كأخطاء خادم.
الحد الأقصى لحجم الـ Response
request:
max_response_bytes: 1048576
يقرأ AGENTO body تدريجيًا، ويتوقف عند تجاوز حد البايت. يحمي ذلك الذاكرة ويحدّ من العمل اللاحق المتجه إلى الـ AI Model.