Implement a retry_strategy object for retrying operations on the agent

[zastrowm]

Overview

Implement a configurable retry_strategy parameter for the Agent class to replace hardcoded retry logic with a flexible, hook-based retry system. This will allow users to configure retry behavior and implement custom retry strategies.

Current State

The SDK currently has hardcoded retry logic in event_loop.py:

• MAX_ATTEMPTS = 6
• INITIAL_DELAY = 4 seconds
• MAX_DELAY = 240 seconds (4 minutes)
• Exponential backoff for ModelThrottledException
• Emits EventLoopThrottleEvent during retries

Related Issues and PRs

• [FEATURE] make event loop settings configurable strands-agents/sdk-python#283
• [FEATURE] Make event loop try/retry logic sleep times configurable strands-agents/sdk-python#527
• [FEATURE] Retries for ServiceUnavailableException (503 errors) strands-agents/sdk-python#370
• feat: allow hooks to retry model invocations on exceptions strands-agents/sdk-python#1405 (Hook-based retry support)

---

Implementation Requirements

1. Create Retry Strategy Classes

Location: src/strands/agent/retry.py (or similar appropriate location)

Create a base retry strategy and built-in implementations:

ModelRetryStrategy (Default)

• Implements HookProvider protocol
• Configurable parameters:
  • max_attempts (default: 6)
  • initial_delay (default: 4 seconds)
  • max_delay (default: 240 seconds)
• Implements exponential backoff for ModelThrottledException
• Registers callback for AfterModelCallEvent
• Sets event.retry = True on throttling exceptions (respecting max_attempts)
• Includes logging for retry attempts (using SDK logging standards)
• Supports async sleep during backoff delays
• Must emit EventLoopThrottleEvent for backwards compatibility (this might be hardcoded to the agent loop if needed since hooks cannot emit events)

Naming: Choose a better name than "ModelRetrys" - something that represents model retries but isn't throttling-specific (e.g., ModelRetryStrategy, RetryStrategy, etc.)

NoopRetryStrategy

• Implements HookProvider protocol
• No-op implementation for users who want to explicitly disable retries
• register_hooks() does nothing

2. Update Agent Class

Location: src/strands/agent/agent.py

Add retry_strategy parameter to Agent.__init__():

def __init__(
    self,
    # ... existing parameters ...
    retry_strategy: Optional[HookProvider] = None,
    # ... other parameters ...
):

Behavior:

• If retry_strategy is None: Default to ModelRetryStrategy() with current defaults (6 attempts, 4s initial, 240s max)
• Store as read-only property: self._retry_strategy
• Register retry_strategy as a hook like any other HookProvider
• Type hint as HookProvider (or create more specific RetryStrategy protocol if needed)

Integration:

• May need to access retry_strategy from event loop for backwards compatibility (emitting EventLoopThrottleEvent)
• Works alongside other hooks - retry_strategy is just another registered hook

3. Refactor Event Loop

Location: src/strands/event_loop/event_loop.py

Remove:

• MAX_ATTEMPTS = 6
• INITIAL_DELAY = 4
• MAX_DELAY = 240
• Hardcoded throttling retry logic in _handle_model_execution()

Refactor:

• Move retry logic from event loop to ModelRetryStrategy hook
• Keep the retry loop structure but rely on hooks setting AfterModelCallEvent.retry
• Ensure EventLoopThrottleEvent is still emitted (may need special handling for built-in ModelRetryStrategy)
• The event loop should be simpler - just invoke hooks and respect the retry field

4. Backwards Compatibility

Critical Requirement: Existing code relying on EventLoopThrottleEvent must continue to work.

Approach:

• ModelRetryStrategy must emit EventLoopThrottleEvent during retries
• May need to check if retry_strategy is the built-in ModelRetryStrategy for special event handling
• Default behavior (when retry_strategy=None) must be identical to current behavior

5. Testing

Location: tests/strands/agent/ and tests/strands/event_loop/

Required Test Scenarios:

1. Default behavior: Verify that not specifying retry_strategy uses default ModelRetryStrategy with 6 attempts
2. Custom retry strategy: Test a user-implemented custom retry strategy
3. Backwards compatibility: Verify that EventLoopThrottleEvent is emitted as before
4. NoopRetryStrategy: Test that retries can be disabled
5. Configured parameters: Test ModelRetryStrategy with custom max_attempts, initial_delay, max_delay
6. Integration with other hooks: Verify retry_strategy works alongside other hooks (no special interaction tests needed, just basic compatibility)

Files to Modify

1. src/strands/hooks/retry.py (new file)

   • Create ModelRetryStrategy class
   • Create NoopRetryStrategy class
   • Implement HookProvider protocol
   • Handle retry logic and event emission

2. src/strands/agent/agent.py

   • Add retry_strategy parameter to __init__()
   • Add _retry_strategy read-only property
   • Register retry_strategy as hook

3. src/strands/event_loop/event_loop.py

   • Remove hardcoded constants
   • Refactor _handle_model_execution() to rely on hooks
   • Simplify retry loop logic

4. tests/strands/hooks/test_retry.py (new file)

   • Test ModelRetryStrategy with default and custom parameters
   • Test NoopRetryStrategy
   • Test custom retry strategy implementation

5. tests/strands/agent/test_agent_retry_strategy.py (new file or add to existing)

   • Test Agent initialization with retry_strategy
   • Test backwards compatibility
   • Test EventLoopThrottleEvent emission

6. tests/strands/event_loop/test_event_loop_retry.py (update existing)

   • Update existing retry tests to work with new system
   • Test backwards compatibility

7. Documentation (location TBD)

   • User guide for retry_strategy feature
   • Examples of custom retry strategies

---

Acceptance Criteria

• ModelRetryStrategy class implements HookProvider and handles throttling retries
• NoopRetryStrategy class implements HookProvider with no-op behavior
• Agent accepts retry_strategy parameter (defaults to ModelRetryStrategy)
• Hardcoded retry constants removed from event_loop.py
• Event loop refactored to rely on hook-based retries
• EventLoopThrottleEvent still emitted for backwards compatibility
• Tests pass for default behavior with same retry characteristics as before
• Tests pass for custom retry strategy implementation
• Tests verify backwards compatibility (EventLoopThrottleEvent emission)
• Tests pass for NoopRetryStrategy
• Tests pass for configured retry parameters
• Documentation created for retry_strategy feature
• All existing tests continue to pass
• Code follows SDK patterns (logging, type hints, docstrings)
• Pre-commit hooks pass (formatting, linting, type checking)

---

Technical Approach

Implementation Strategy

1. Create retry strategy classes with HookProvider protocol
2. Integrate into Agent by adding retry_strategy parameter and registering as hook
3. Refactor event loop to remove hardcoded logic and rely on hooks
4. Ensure backwards compatibility by emitting EventLoopThrottleEvent
5. Write comprehensive tests covering all scenarios
6. Document the feature with examples

Key Design Decisions

• Hook-based approach: Retry strategies are HookProviders, registered like any other hook
• Read-only property: Store as _retry_strategy for potential backwards compat access
• Default behavior preserved: None defaults to ModelRetryStrategy with current settings
• Explicit disable: Use NoopRetryStrategy instead of None to disable retries
• Backwards compatible: EventLoopThrottleEvent emission preserved

Integration Points

• Retry strategies integrate via the existing hook system
• No special handling needed for interaction with other hooks
• Event loop continues to respect AfterModelCallEvent.retry field
• ModelRetryStrategy sets retry field based on its configuration

---

Notes

• The name "ModelRetrys" should be improved to something more generic that represents model retries without being throttling-specific
• This feature enables users to implement sophisticated retry logic beyond throttling (rate limiting, circuit breakers, custom backoff strategies, etc.)
• The hook-based approach maintains consistency with SDK patterns and provides maximum flexibility

[zastrowm]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed the repository structure and current retry implementation to understand the context for this feature. Here's what I found:

Current State

• Retry Logic Location: src/strands/event_loop/event_loop.py in _handle_model_execution()
• Hardcoded Constants:
  • MAX_ATTEMPTS = 6
  • INITIAL_DELAY = 4 seconds
  • MAX_DELAY = 240 seconds (4 minutes)
• Current Retry Behavior:
  • Automatic exponential backoff retry for ModelThrottledException
  • Hooks can request retries by setting AfterModelCallEvent.retry = True
• Hook System:
  • HookProvider protocol: objects with register_hooks(registry) method
  • Agent already accepts hooks parameter: list[HookProvider]
  • Well-established pattern in the codebase

Implementation Files

• Agent class: src/strands/agent/agent.py
• Event loop: src/strands/event_loop/event_loop.py
• Hooks system: src/strands/hooks/events.py, src/strands/hooks/registry.py
• Hook events: AfterModelCallEvent already has writable retry field

---

Clarifying Questions

1. Scope and Behavior

Q1: Should ModelRetrys replace ALL the hardcoded retry logic in event_loop.py, or only handle throttling exceptions? Currently the event loop has:

• Exponential backoff retry for ModelThrottledException (6 attempts, 4s initial delay, 240s max)
• Support for hooks to request retries via AfterModelCallEvent.retry

Q2: What parameters should ModelRetrys expose for configuration? Should it support:

• max_attempts (currently 6)
• initial_delay (currently 4 seconds)
• max_delay (currently 240 seconds)
• Ability to specify which exceptions to retry on?
• Custom backoff strategies (exponential, linear, constant)?

Q3: Should multiple retry strategies be supported simultaneously, or just one per agent?

2. Backward Compatibility

Q4: What should the default behavior be for retry_strategy when not specified?

• Option A: Default to current behavior (ModelRetrys with max_attempts=6)
• Option B: No retries by default (breaking change)
• Option C: Something else?

Q5: The issue mentions "special case the built-in ModelRetrys object to stream retry events back so that we preserve backwards compatibility." Can you clarify:

• What specific retry events need to be streamed?
• What existing behavior depends on these events?
• Is there an existing event type for retry notifications (EventLoopThrottleEvent?), or do we need to create one?

Q6: How should we handle the transition from hardcoded constants to configurable retry_strategy?

• Should we deprecate the constants but keep them as fallback defaults?
• Should we remove them entirely in this PR?

3. Integration with Existing Hooks

Q7: How should retry_strategy interact with:

• The existing hooks parameter?
• Hooks that set AfterModelCallEvent.retry = True?

Should they:

• Work together (retry_strategy retries, AND other hooks can request retries)?
• Be mutually exclusive?
• Have precedence rules?

Q8: If a user provides both retry_strategy=ModelRetrys(max_attempts=3) AND hooks=[CustomHook()] where CustomHook also handles AfterModelCallEvent, how should the retry logic be coordinated?

4. Implementation Details

Q9: Should ModelRetrys as a HookProvider:

• Handle retries for ALL exceptions, or just specific ones (throttling, network errors, etc.)?
• Include logging/metrics for retry attempts?
• Support async sleep during backoff delays?

Q10: Should the Agent class:

• Accept retry_strategy as a separate parameter that gets internally added to hooks?
• Validate that retry_strategy implements HookProvider?
• Support None to explicitly disable retries?

5. Testing and Documentation

Q11: Are there specific test scenarios you'd like covered beyond basic functionality?

• Custom retry strategies?
• Interaction with existing hooks?
• Backward compatibility tests?

Q12: Should this feature be documented in HOOKS.md or in a separate retry strategy guide?

---

Please respond to these questions on this issue when you have a chance. Based on my analysis, this implementation will likely require modifications to:

• src/strands/agent/agent.py (add retry_strategy parameter)
• src/strands/event_loop/event_loop.py (refactor retry logic)
• Create new src/strands/hooks/retry.py or similar for ModelRetrys class
• Tests in tests/strands/agent/ and tests/strands/event_loop/
• Documentation in docs/HOOKS.md

[zastrowm]

/strands

Clarifying Questions

1. Scope and Behavior

Q1: Should ModelRetrys replace ALL the hardcoded retry logic in event_loop.py, or only handle throttling exceptions? Currently the event loop has:

• Exponential backoff retry for ModelThrottledException (6 attempts, 4s initial delay, 240s max)
• Support for hooks to request retries via AfterModelCallEvent.retry

It should handle the Exponential backoff retry

Q2: What parameters should ModelRetrys expose for configuration? Should it support:

• max_attempts (currently 6)
• initial_delay (currently 4 seconds)
• max_delay (currently 240 seconds)

For now, keep it to these 3 properites

• Ability to specify which exceptions to retry on?

Not for now

• Custom backoff strategies (exponential, linear, constant)?

Keep the existing strategy for now

Q3: Should multiple retry strategies be supported simultaneously, or just one per agent?

2. Backward Compatibility

Q4: What should the default behavior be for retry_strategy when not specified?

• Option A: Default to current behavior (ModelRetrys with max_attempts=6)
• Option B: No retries by default (breaking change)
• Option C: Something else?

Option A - default to current behavior

Q5: The issue mentions "special case the built-in ModelRetrys object to stream retry events back so that we preserve backwards compatibility." Can you clarify:

• What specific retry events need to be streamed?
• What existing behavior depends on these events?
• Is there an existing event type for retry notifications (EventLoopThrottleEvent?), or do we need to create one?

Yeah, it's the EventLoopThrottleEvent; callers could be relying on that event being emitted

Q6: How should we handle the transition from hardcoded constants to configurable retry_strategy?

• Should we deprecate the constants but keep them as fallback defaults?
• Should we remove them entirely in this PR?

Remove them entirely

3. Integration with Existing Hooks

Q7: How should retry_strategy interact with:

• The existing hooks parameter?
• Hooks that set AfterModelCallEvent.retry = True?

Should they:

• Work together (retry_strategy retries, AND other hooks can request retries)?
• Be mutually exclusive?
• Have precedence rules?

Work together. _retry_strategy should be a read-only property on the Agent and should register hooks like normal. As part of the implementation, we may need to access retry_strategy for the backwards compatibility check (e.g. if we need to emit that event)

Q8: If a user provides both retry_strategy=ModelRetrys(max_attempts=3) AND hooks=[CustomHook()] where CustomHook also handles AfterModelCallEvent, how should the retry logic be coordinated?

it doesn't matter; we should just be registering ModelRetrys callbacks like a normal hook. IF they add more hooks, that's fine, the hook system handle it

4. Implementation Details

Q9: Should ModelRetrys as a HookProvider:

• Handle retries for ALL exceptions, or just specific ones (throttling, network errors, etc.)?

For now, just the throttling similar to how it is right now

• Include logging/metrics for retry attempts?

Logging can be done in ModelRetries

• Support async sleep during backoff delays?

Yes

Also, come up with a better name than ModelRetrys; we want something non-specific to throttling, but that represents the idea that it's focused on model retries right now

Q10: Should the Agent class:

• Accept retry_strategy as a separate parameter that gets internally added to hooks?
• Validate that retry_strategy implements HookProvider?

It should be typed as a RetryStrategy

• Support None to explicitly disable retries?

None should default to ModelRetrys; if we need to disable it, we can add a NoopRetryStrategy

5. Testing and Documentation

Q11: Are there specific test scenarios you'd like covered beyond basic functionality?

• Custom retry strategies?
• Interaction with existing hooks?
• Backward compatibility tests?

A custom retry strategy. No interaction with existing hooks is needed. Yes verify backwards compatibility that the streaming event is emitted as it was in the past.

Q12: Should this feature be documented in HOOKS.md or in a separate retry strategy guide?

Not in HOOKS.md; this should just be a separate feature.

Please respond to these questions on this issue when you have a chance. Based on my analysis, this implementation will likely require modifications to:

• src/strands/agent/agent.py (add retry_strategy parameter)
• src/strands/event_loop/event_loop.py (refactor retry logic)
• Create new src/strands/hooks/retry.py or similar for ModelRetrys class
• Tests in tests/strands/agent/ and tests/strands/event_loop/
• Documentation in docs/HOOKS.md

[github-actions]

Task Refinement Complete

Summary

I've completed the task refinement for issue #15. The issue description has been updated with comprehensive implementation requirements based on your responses to the clarifying questions.

What Was Accomplished

1. Repository Analysis

• Analyzed current retry implementation in event_loop.py
• Reviewed hook system architecture and patterns
• Identified integration points and potential conflicts

2. Requirements Clarification

• Posted 12 clarifying questions covering scope, compatibility, integration, implementation, and testing
• Received detailed responses from maintainer
• Resolved all ambiguities regarding feature implementation

3. Issue Description Update

The updated issue description now includes:

• Clear overview of current state and goals
• Detailed implementation requirements for each component:
  • ModelRetryStrategy class (with better naming suggestion)
  • NoopRetryStrategy class
  • Agent class integration
  • Event loop refactoring
  • Backwards compatibility approach
• Files to modify with specific guidance for each
• Comprehensive acceptance criteria (14 checkpoints)
• Technical approach with design decisions documented

Implementation Scope

This task is appropriately scoped for a single pull request:

• Estimated effort: ~1 week for a single developer
• Changes are cohesive and interdependent
• Core components: retry strategy classes, Agent integration, event loop refactoring
• Well-defined boundaries with existing code

Key Design Decisions

1. Hook-based approach: Retry strategies implement HookProvider protocol
2. Backwards compatible: Defaults to current behavior (6 attempts), emits EventLoopThrottleEvent
3. Flexible: Users can implement custom retry strategies beyond throttling
4. Clean integration: Works alongside existing hooks without special handling
5. Explicit disable: NoopRetryStrategy for users who want no retries

Testing Requirements

• Default behavior verification
• Custom retry strategy test
• Backwards compatibility test (EventLoopThrottleEvent)
• NoopRetryStrategy test
• Configured parameters test
• Basic integration with other hooks

Ready for Implementation

✅ This issue is now ready for implementation. The requirements are clear, comprehensive, and validated by the maintainer.

[zastrowm]

/strands implement

[zastrowm]

/strands implement

Continue, your last attempt got throttled