[FEATURE] Allow hooks to retry model invocations

[zastrowm]

Problem Statement

In sdk-typescript, we allow model retries - that was implemented as part of strands-agents/sdk-typescript#222

Folks would like to retry on arbitrary exceptions (see strands-agents#370) and I think we should let them.

Proposed Solution

Allow AfterModelCall hook callbacks to set a field to retry model invocation. For now it should only be allowed if an exception is thrown.

This does not replace our existing retry-strategy, but makes it more flexible

Use Case

Retrying model calls on exceptions

Implementation Requirements

Based on repository analysis and clarification discussion, here are the detailed requirements:

Technical Approach

Hook System Enhancement:

• Add writable retry_model field to AfterModelCallEvent (boolean, default False)
• Field should only be checked when exception attribute is present (not on successful calls)
• Implement _can_write() method to allow modification of retry_model field
• Multiple hooks can set/unset the field; final value is read after all callbacks execute

Retry Logic:

• Hooks determine their own retry parameters (count, delay, conditions)
• Hook-initiated retries are independent from existing throttle retry logic
• Existing throttle retry can be conceptually viewed as a built-in retry mechanism
• No validation on exception types - hooks decide what to retry
• No maximum retry limit enforced by framework (hooks manage their own limits)
• Hooks should implement their own delay logic (no delay parameter on event)

Integration with Existing Code:

• Modify _handle_model_execution() in src/strands/event_loop/event_loop.py
• Check retry_model field after invoking AfterModelCallEvent callbacks
• If retry_model=True and exception exists, continue retry loop
• Existing throttle retry logic should remain unchanged

Files to Modify

• src/strands/hooks/events.py - Add retry_model field and _can_write() to AfterModelCallEvent
• src/strands/event_loop/event_loop.py - Integrate hook-initiated retries into _handle_model_execution()
• tests/strands/agent/hooks/test_agent_events.py - Add unit tests for retry functionality

Acceptance Criteria

• AfterModelCallEvent has writable retry_model: bool = False field
• retry_model is only checked when exception is present (not on successful calls)
• Hook callbacks can set retry_model=True to retry the model call
• Multiple hooks can modify the field; final value after all callbacks is used
• Retry logic integrates seamlessly with existing throttle retry mechanism
• Unit tests demonstrate retry behavior with mock exceptions (e.g., ServiceUnavailableException)
• Unit tests verify retry only happens when exception exists
• Unit tests verify hooks control their own retry logic (count, delay, conditions)
• Existing throttle retry tests continue to pass
• No integration tests required for this feature

Scope

• In Scope: Regular model calls via Agent.__call__() and Agent.stream_async()
• Out of Scope: structured_output invocations (per existing AfterModelCallEvent behavior)

Example Usage

A hook provider might implement retry logic like this:

class RetryOnServiceUnavailable(HookProvider):
    def __init__(self, max_retries=3):
        self.max_retries = max_retries
        self.retry_counts = {}
    
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(AfterModelCallEvent, self.handle_retry)
    
    async def handle_retry(self, event: AfterModelCallEvent) -> None:
        if event.exception and "ServiceUnavailable" in str(event.exception):
            request_id = id(event)  # Use some request identifier
            count = self.retry_counts.get(request_id, 0)
            
            if count < self.max_retries:
                self.retry_counts[request_id] = count + 1
                await asyncio.sleep(2 ** count)  # Exponential backoff
                event.retry_model = True
            else:
                # Max retries reached, let exception propagate
                self.retry_counts.pop(request_id, None)

Related Issues

• [FEATURE] Retries for ServiceUnavailableException (503 errors) strands-agents/sdk-python#370 - Users requesting retries for ServiceUnavailableException (503 errors)

Additional Context

The existing retry mechanism only handles ModelThrottledException with exponential backoff (MAX_ATTEMPTS=6, INITIAL_DELAY=4s, MAX_DELAY=240s). This feature enables users to implement custom retry logic for any exception type via hooks, providing the flexibility requested in issue strands-agents#370 without hardcoding specific exception types into the framework.

[zastrowm]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Context

I've analyzed the repository structure and current retry implementation to better understand this feature request:

Current State

• Retry Logic: Currently in src/strands/event_loop/event_loop.py in the _handle_model_execution() function
• Existing Retry Support: Only for ModelThrottledException with exponential backoff
• Retry Constants: MAX_ATTEMPTS=6, INITIAL_DELAY=4s, MAX_DELAY=240s
• Hook System: AfterModelCallEvent already fires after model calls with exception attribute when errors occur
• Writable Hook Pattern: Exists in other hooks (e.g., BeforeToolCallEvent.cancel_tool, AfterToolCallEvent.result)

Related Issues

• Issue [FEATURE] Retries for ServiceUnavailableException (503 errors) strands-agents/sdk-python#370 requests retries for ServiceUnavailableException (503 errors) from certain models
• This feature would enable users to implement custom retry logic via hooks instead of hardcoding exception types

Files to Modify

Based on my analysis, implementation would likely involve:

• src/strands/hooks/events.py - Add retry field to AfterModelCallEvent
• src/strands/event_loop/event_loop.py - Integrate hook-initiated retries into retry loop
• tests/strands/agent/hooks/test_agent_events.py - Add tests for retry functionality
• docs/HOOKS.md - Document the new writable property

Clarifying Questions

1. Retry Field Design

• Should the retry field be a simple boolean flag (retry_model_call: bool = False) or allow a string message similar to BeforeToolCallEvent.cancel_tool (bool | str)?
• Proposed field name: retry_model_call - does this align with naming conventions?

2. Retry Behavior & Limits

• Should hook-initiated retries share the same retry limit (MAX_ATTEMPTS=6) as throttling retries?
  • Example: If a model is throttled 2 times, should a user only get 4 more retry attempts or reset to 6?
• Should hook-initiated retries use the same exponential backoff (INITIAL_DELAY=4s, MAX_DELAY=240s)?
• If users should control delay, should AfterModelCallEvent accept a delay parameter?

3. Multiple Hooks

• What should happen if multiple hook callbacks set retry_model_call=True?
  • Should all be honored (could cause issues)?
  • Should only the first be honored?
  • Should the last one win?

4. Validation & Safety

• Should there be any validation on which exception types can be retried?
• Should there be a maximum number of consecutive hook-initiated retries to prevent infinite loops?

5. Scope

• This feature only applies to regular model calls, not structured_output (per existing AfterModelCallEvent behavior) - correct?
• The issue states "only be allowed if an exception is thrown" - should we validate this and prevent retries on successful calls?

6. Documentation & Testing

• Should this feature be documented in docs/HOOKS.md under "Writable Properties"?
• Should there be example code showing common use cases (e.g., retrying on ServiceUnavailableException)?
• Unit tests mirroring existing throttling tests are expected - are integration tests with real model providers also needed?

---

These questions will help ensure the implementation aligns with your expectations and the existing codebase patterns. Please let me know your thoughts when you have a chance!

[zastrowm]

/strands

Repository Analysis & Clarifying Questions

Repository Context

Related Issues

• Issue [[FEATURE] Retries for ServiceUnavailableException (503 errors) strands-agents/sdk-python#370]([FEATURE] Retries for ServiceUnavailableException (503 errors) strands-agents/sdk-python#370) requests retries for ServiceUnavailableException (503 errors) from certain models
• This feature would enable users to implement custom retry logic via hooks instead of hardcoding exception types

Files to Modify

Based on my analysis, implementation would likely involve:

• src/strands/hooks/events.py - Add retry field to AfterModelCallEvent
• src/strands/event_loop/event_loop.py - Integrate hook-initiated retries into retry loop
• tests/strands/agent/hooks/test_agent_events.py - Add tests for retry functionality
• docs/HOOKS.md - Document the new writable property

Clarifying Questions

1. Retry Field Design

• Should the retry field be a simple boolean flag (retry_model_call: bool = False) or allow a string message similar to BeforeToolCallEvent.cancel_tool (bool | str)?

Simple boolean

• Proposed field name: retry_model_call - does this align with naming conventions?

Let's go with retry_model

2. Retry Behavior & Limits

• Should hook-initiated retries share the same retry limit (MAX_ATTEMPTS=6) as throttling retries?

  • Example: If a model is throttled 2 times, should a user only get 4 more retry attempts or reset to 6?

• Should hook-initiated retries use the same exponential backoff (INITIAL_DELAY=4s, MAX_DELAY=240s)?

• If users should control delay, should AfterModelCallEvent accept a delay parameter?

Let hooks determine their own parameters. The existing retry parameters could conceptually be considered a ThrottleRetryHook that is built into the system right now

To that end, no delay parameter; it's up to hooks to delay themselves

3. Multiple Hooks

• What should happen if multiple hook callbacks set retry_model_call=True?

  • Should all be honored (could cause issues)?
  • Should only the first be honored?
  • Should the last one win?

Any hook can set or unset this parameter. It's at the end of hook execution that the parameter should be read

4. Validation & Safety

• Should there be any validation on which exception types can be retried?

No

• Should there be a maximum number of consecutive hook-initiated retries to prevent infinite loops?

No, not at this time

5. Scope

• This feature only applies to regular model calls, not structured_output (per existing AfterModelCallEvent behavior) - correct?

Correct

• The issue states "only be allowed if an exception is thrown" - should we validate this and prevent retries on successful calls?

Yes, we should only check retry logic on the exceptional case

6. Documentation & Testing

• Should this feature be documented in docs/HOOKS.md under "Writable Properties"?

No

• Should there be example code showing common use cases (e.g., retrying on ServiceUnavailableException)?

If the snippet is small enough. Otherwise, add a unit test to validate a similar scenario (mocking where necessary)

• Unit tests mirroring existing throttling tests are expected - are integration tests with real model providers also needed?

No integration test needed for this case

These questions will help ensure the implementation aligns with your expectations and the existing codebase patterns. Please let me know your thoughts when you have a chance!

[github-actions]

Task Refinement Complete

Summary

The task refinement for issue #5 is complete and the issue is ready for implementation.

What Was Accomplished

1. Repository Analysis: Analyzed current retry implementation, hook system patterns, and existing tests
2. Clarification Discussion: Asked and received answers to all clarifying questions about:
   • Retry field design and naming
   • Retry behavior and limits
   • Multiple hooks handling
   • Validation and safety requirements
   • Scope and testing requirements
3. Updated Issue Description: Added comprehensive implementation requirements including:
   • Technical approach
   • Files to modify
   • Acceptance criteria
   • Example usage code
   • Scope definition

Ready for Implementation

The issue now contains all information needed for a developer to implement this feature:

• Clear technical specifications based on existing patterns
• Specific files and functions to modify
• Detailed acceptance criteria
• Example code showing expected usage
• Testing requirements (unit tests only, no integration tests)

Key Design Decisions

• Field name: retry_model (boolean)
• Hooks control their own retry logic (count, delay, conditions)
• Independent from throttle retry mechanism
• Only checked when exception exists
• No framework-enforced retry limits
• Last hook wins (field read after all callbacks execute)

Estimated Implementation Scope

This feature can be implemented in a single pull request by a developer familiar with the codebase. The changes are focused on:

• 1 new field in AfterModelCallEvent
• Modification to existing retry loop in _handle_model_execution()
• Unit tests mirroring existing throttle retry tests

The implementation should take approximately 1-2 days including tests and code review.

[zastrowm]

/strands implement