[ANNOUNCEMENT] Upcoming Breaking Changes

[zastrowm]

This is a centralized tracking issue for potentially breaking changes planned for a future release. The changes documented here and in linked issues may require action from users to maintain compatibility when upgrading to a later version.

Related Breaking Change Issues

• Update default model to be Claude 4 Sonnet #467

Please refer to the linked issues for specific details about each breaking change.

[zastrowm]

Version 0.2.0 has been released and had the following breaking changes:

• Use region from boto3 session when possible (#299)
  • This change updates the region behavior of the BedrockModelProvider to better align with the Boto3 default region behavior instead of us-west-2.
• refactor: remove kwargs spread after agent call (#289)
  • Previously, strands used certain parameters that were passed into the agent invocation call. For example, agent("Hello!", system_prompt="Some New Prompt") would previously override the system prompt defined during the agent’s initialization. Now, this behavior has been removed, so you can alter the agent’s system prompt by overriding the agents system_prompt attribute.
    • Before: agent("Hello!", system_prompt="Some New Prompt")
    • After: agent.system_prompt = "Some New Prompt"
• Remove FunctionTool (#325)
  • Previously, FunctionTool was deprecated in favor of DecoratedFunctionTool but it was kept in for backwards compatibility. This removes the FunctionTool class in favor of using the @tool decorator. Check out the strands agents tool documentation for instructions on building a tool.
• Implement native async iterator support (#83)
  • #295: We no longer yield any callback events carried out in tool invocations from stream_async.
  • #323: callback_handler is no longer passed to tools.
• refactor tracer (#286)
  • The OTEL setup process has changed. Before, Strands would try to automatically setup and OTEL exporter using the STRANDS_OTEL_ENABLE_CONSOLE_EXPORT environment variable. This has been removed, and replaced with a function call. See the docs here for more info: https://strandsagents.com/latest/user-guide/observability-evaluation/traces/#code-configuration

[zastrowm]

Version 0.3.0 was released with the following breaking change notes:

• Model Providers:

  • OpenAI and LiteLLM model providers no longer accept base64 encoded images. These providers will now handle base64 encoding of image bytes automatically. See issue #252.
  • Model providers now implement asynchronous functions. Custom model providers must be updated accordingly. See PR#306.
  • The API interface for model providers has been simplified to require only a single stream method implementation. See PR#400.
  • Model provider API interfaces have been relocated to the strands.models subpackage for improved organization. See PR#409.

• Other breaking changes:

  • All classes or protocols requiring subclassing or implementation now include an additional kwargs argument for forward compatibility. See PR#413.
  • The max_parallel_tools parameter has been removed from the Agent class. Tools are now automatically invoked on thread-pools. See PR#391.
  • The load_tools_from_directory parameter of the Agent class now defaults to False meaning. Tools are no longer automatically loaded from the tools directory. To restore the old behavior, explicitly set this parameter to True . See PR#419.
  • The event_loop_cycle function is no longer available as a top-level import from strands, reflecting its internal nature. Direct event loop invocation is not recommended. See PR#415.
  • Automatic removal of dangling tool messages during Agent lifecycle has been discontinued to support future features. See PR#418.
  • AgentTool now implements a stream API instead of invoke and requires asynchronous implementation. See PR#345.

---

List of items that were previously mentioned in the issue description.

• [FEATURE] Model Providers - Always Base64 Encode Images #252
• models - openai - do not accept b64 images #368: OpenAI and LiteLLM model provider are no longer accepting base64 encoded images. The providers will base64 encode the image bytes on your behalf.
• [FEATURE] Implement native async iterator support  #83: This task includes the following breaking changes:
  • remove thread pool wrapper #339: We removed the ParallelToolExecutorInterface in favor of operating with a concurrent.futures.ThreadPoolExecutor directly for parallel tool execution. This will impact customers who are implementing a ParallelToolExecutorInterface for direct invocation of the event_loop_cycle. Instead, customers should pass in an instance of concurrent.futures.ThreadPoolExecutor into the thread_pool keyword arg (docs <IN_RELEASE>). If custom logic is desired, you will have to derive from concurrent.futures.ThreadPoolExecutor. This is not a practice we recommend however.
  • async model stream interface #306: The Model interface stream and structured_output methods are expected to be async.
  • iterative tools #345: The AgentTool interface no longer includes invoke. Instead, customers will override the async stream method.
    • Note, customers still cannot define an iterative (generator) based tool. The support is only internal to the SDK. We are waiting on support for strongly typed events before allowing customers to define their tools as generators.
  • async tools support #391: Agent.__call__ and Agent.structured_output run in a separate thread. Consequently, thread local context vars will not be accessible in Python decorated and module based tools.
    • This PR also removed the max_parallel_tools parameter from Agent.__init__. Instead, customers will rely on the default thread pool settings of the async event loop.
• [REFACTOR] Unify Model Interface Around Single Entry Point (model.stream) #400: We removed format_request, format_chunk and converse from the model interface and instead brought to focus the stream method, which now includes the parameters messages, tool_specs, and system_prompt. Consequently, when deriving a custom model provider, you will only override set_config, get_config, and stream.
• models - move abstract class #409: This PR introduces the following breaking changes:
  • We moved types/models/model.py::Model to models/model.py::Model. Thus, when deriving a custom model provider, you will import from from strands.models import Model.
  • We also removed types/models/openai.py::OpenAIModel. Model provider should be standalone and not derive logic from another.
• refactor: Update interfaces to include kwargs to enable backwards compatibility #413 This PR adds **kwargs parameter to all interfaces to enable backwards compatibility and future extensibility. Additionally, it updates the AgentTool.stream function signature. It removes the old kwargs argument and renames it to invocation_state.