A record of design and API decisions with their rationale, enabling prior decisions to guide future ones.
Date: Jan 6, 2026
Hooks serve as low-level extensibility primitives for the agent loop. High-level constructs SHOULD be built on top of hooks rather than exposing HookProvider as the sole developer-facing interface. These higher-level constructs should define their own interface with domain-specific methods and type signatures beyond what HookProvider alone provides.
Exposing only HookProvider directly to consumers adds complexity to the implementor while offering no guidance on implementation requirements or type safety for specific use cases.
For example, an Agent-provided retry_strategy should not be implemented as:
def Agent.__init__(
...
retry_strategy: HookProvider
)This is too low-level and gives no guidance on how a retry strategy should be implemented. Instead, a specific interface or base class should be built on top of hooks, providing additional scaffolding:
class RetryStrategy(HookProvider):
def register_hooks(registry):
...
@abstractmethod
def should_retry_model(e: Exception) -> bool:
"""Return true if the model call should be retried based on this exception"""
...
def calculate_retry_delay(attempt: int) -> int:
...Higher-level abstractions require additional interface definitions, but this tradeoff provides an improved developer experience through explicit contracts. Developers with edge cases can still drop to raw HookProvider (and agent.hooks) when needed — optimizing for the common path while preserving that escape hatch.
Date: Jan 16, 2026
Public APIs should expose commonly-used functionality through flat, top-level namespaces rather than requiring users to import from deeply nested module paths.
Fewer imports are simpler to use and more discoverable when using IDE autocompletion & documentation. While inspired by Python's "Flat is better than nested" (PEP 20 - The Zen of Python), this principle applies across SDK languages.
We don't want users continually importing additional modules for common functionality. The goal is to optimize for the 80% case where users need standard features, while still allowing advanced users to import from specific submodules when needed.
For example, we prefer exporting all hook events from a single module:
from strands.hooks import MultiAgentInitializedEventinstead of categorizing them based on their purpose
from strands.hooks.multiagent import MultiAgentInitializedEventthis is even more important when the event names already indicate their grouping (MultiAgentInitializeEvent).
Internal module organization can remain nested for code maintainability — the key is re-exporting public symbols at common locations.
Date: Jan 21, 2026
Internal interfaces that integrate with the agent lifecycle (such as RetryStrategy, SessionManager, and ConversationManager) SHOULD extend HookProvider. When uncertain whether a new interface requires HookProvider, prefer a simple domain interface—it can always be evolved to extend HookProvider later, but the reverse migration breaks existing implementations.
The team considered two approaches for RetryStrategy: extending HookProvider or exposing a simple domain interface with methods like should_retry(exception, attempt) -> bool.
While RetryStrategy is simple enough that a non-HookProvider interface would suffice, extending HookProvider maintains a uniform pattern across all agent constructor parameters that integrate with the lifecycle. Users implementing any of these interfaces learn one composition model. This aligns with the composability tenet: primitives are building blocks with each other.
The tradeoff is that HookProvider exposure can leak implementation details for interfaces with single decision points. Use the following criteria for future interfaces:
Use a simple interface when:
- The interface has a single responsibility expressible as one or two methods
- The interface does not need to respond to multiple lifecycle events
- Consistency with existing interfaces is not a priority
Extend HookProvider when:
- The capability requires responding to multiple distinct lifecycle events
- Users need to customize which events to subscribe to or add callbacks beyond base class defaults
Date: Jan 28, 2026
Small breaking changes that follow the "pay for play" principle are acceptable without a major version bump. Programs can call new APIs to access new features, but programs that choose not to do so are unaffected — old code continues to work as it did before.
Strict semver adherence can slow SDK development when the breaking change only affects users who explicitly adopt new functionality. If existing code paths remain unaffected, the practical impact on users is minimal.
For example, converting a TypedDict to total=False is technically breaking change - code that creates instances of that TypedDict without the new field will still work, but code that reads from the TypedDict and expects the field to always be present would break. However, if the old field is only missing when using a new tool, users who don't adopt that tool never encounter the missing field. The break is "pay for play": you only see it if you opt into the new functionality.
This applies when the breaking change is gated behind new functionality — users who don't touch the new feature never see the break, and those who do will find the breakage more obvious since it's tied to something they just added.
This doesn't apply when existing code breaks without any user action, or when the change affects default behavior. If someone upgrades and their code stops working with no obvious reason why, that's a bad experience we want to avoid.