إعادة المحاولة والتأمل

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

نظرة عامة

عند فشل استدعاء أداة، يتمثل السلوك الافتراضي في إعادة الخطأ إلى LLM وتركه يقرر ما يجب فعله. يضيف مكوّن Retry & Reflect الإضافي آلية استرداد منظمة:

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

التثبيت

[dependencies]
adk-retry-reflect = "2.1.0"

# Or via umbrella crate (included in standard tier)
adk-rust = { version = "2.1.0", features = ["standard"] }

البدء السريع

use adk_retry_reflect::RetryReflectPlugin;
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let plugin = RetryReflectPlugin::builder()
    .max_retries(3)
    .initial_backoff_ms(500)
    .backoff_multiplier(2.0)
    .build();

let agent = LlmAgentBuilder::new("resilient_agent")
    .model(model)
    .instruction("You are a helpful assistant with access to external APIs.")
    .tool(Arc::new(flaky_api_tool))
    .plugin(Arc::new(plugin))
    .build()?;

الإعداد

use adk_retry_reflect::{RetryReflectPlugin, RetryReflectConfig};

let plugin = RetryReflectPlugin::builder()
    // Retry settings
    .max_retries(3)                    // Maximum retry attempts [default: 3]
    .initial_backoff_ms(500)           // First retry delay in ms [default: 500]
    .backoff_multiplier(2.0)           // Multiply delay each retry [default: 2.0]
    .max_backoff_ms(30_000)            // Cap delay at this value [default: 30000]

    // Circuit breaker
    .circuit_breaker_threshold(5)      // Open circuit after N failures [default: 5]
    .circuit_breaker_reset_ms(60_000)  // Reset circuit after this duration [default: 60000]

    // Reflection
    .reflection_prompt(                // Custom reflection prompt template
        "The tool '{tool_name}' failed with: {error}. \
         Analyze what went wrong and provide corrected arguments."
    )

    // Scope
    .include_tools(&["api_call", "db_query"])  // Only retry these tools
    .exclude_tools(&["exit_loop"])             // Never retry these tools

    .build();

مرجع الإعداد

قاطع الدائرة

يمنع قاطع الدائرة حلقات إعادة المحاولة اللانهائية عندما تكون الأداة معطّلة باستمرار:

Closed (normal) ─── failure count >= threshold ──→ Open (all calls fail fast)
       ↑                                                    │
       └──────── reset_ms elapsed, next call succeeds ──────┘
                              (Half-Open)

عندما تكون الدائرة مفتوحة:

• تفشل استدعاءات الأداة فورًا مع ظهور خطأ قاطع الدائرة
• لا تتم محاولة إعادة المحاولة
• بعد circuit_breaker_reset_ms، يُسمح بمرور الاستدعاء التالي (نصف مفتوح)
• إذا نجح، تُغلق الدائرة؛ وإذا فشل، تظل الدائرة مفتوحة

كيفية عمل الانعكاس

عندما يفشل استدعاء أداة، تُدخل الإضافة مطالبة انعكاس في المحادثة:

[User]: What's the weather in NYC?
[Model]: *calls get_weather({"city": "nyc", "units": "kelvin"})*
[Tool Error]: Invalid units. Supported: celsius, fahrenheit
[Plugin injects]: The tool 'get_weather' failed with: "Invalid units. 
    Supported: celsius, fahrenheit". Analyze what went wrong and provide 
    corrected arguments.
[Model]: *calls get_weather({"city": "NYC", "units": "celsius"})*
[Tool Success]: {"temperature": 22, "condition": "sunny"}

تمنح مطالبة الانعكاس LLM سياقًا صريحًا حول الفشل، بحيث يمكنه تصحيح نفسه بدلًا من تكرار الخطأ نفسه.

متى يُستخدم

مناسب لـ:

• الأدوات التي تستدعي APIs خارجية مع حالات فشل مؤقتة
• الأدوات التي قد يقدّم فيها LLM وسيطات غير صحيحة قليلًا
• استعلامات قاعدة البيانات التي قد تفشل بسبب مشكلات الاتصال
• عمليات الملفات على مساحة تخزين متصلة بالشبكة

غير مناسب لـ:

• الأدوات المعطّلة بشكل حتمي (أصلح الأداة بدلًا من ذلك)
• الأدوات طويلة التشغيل التي تكون إعادة المحاولة معها مكلفة
• الأدوات ذات الآثار الجانبية غير القابلة للتكرار بأمان (مثل إرسال رسائل البريد الإلكتروني)
• أدوات تدفق التحكم مثل exit_loop

الدمج مع الإضافات الأخرى

تحترم إعادة المحاولة والانعكاس ترتيب أولوية الإضافات:

use adk_plugin::PluginManager;

let agent = LlmAgentBuilder::new("agent")
    .model(model)
    .plugin(Arc::new(logging_plugin))         // Priority 1 (runs first)
    .plugin(Arc::new(retry_reflect_plugin))   // Priority 2
    .plugin(Arc::new(guardrail_plugin))       // Priority 3 (runs last)
    .build()?;

قابلية المراقبة

تُصدر الإضافة مقاطع تتبّع لمحاولات إعادة المحاولة:

WARN adk_retry_reflect: tool call failed, retrying
    tool_name=get_weather attempt=1 max=3 backoff_ms=500
    error="Invalid units"

INFO adk_retry_reflect: retry succeeded
    tool_name=get_weather attempt=2

WARN adk_retry_reflect: circuit breaker opened
    tool_name=broken_api failures=5 reset_ms=60000

ذات صلة

• الإضافات — بنية نظام الإضافات
• أدوات الدوال — إنشاء الأدوات
• التقييم — اختبار مرونة الوكيل

---

السابق: ← ACP الأدوات | التالي: عُقد الإجراءات →