Skip to content

[CHORE] Remove graduated experimental shims (steering, tools.ToolProvider, hooks aliases) #3333

Description

@yonib05

Problem Statement

Several features have already graduated out of strands.experimental into the production namespace, but the experimental locations still exist as DeprecationWarning shims that re-export from production. Per the SDK graduation lifecycle (versioning-and-support.mdx: X.Y = graduate + deprecate; X.Y+1 = experimental version removed), these shims are now eligible for removal.

They were introduced on 2026-05-26 in the monorepo convergence (#2317), so they have been deprecated for multiple minor releases.

Shims to remove (strands-py/src/strands/experimental/)

  • steering/ — entire subtree is a DeprecationWarning shim re-exporting from strands.vended_plugins.steering. Files: __init__.py, core/{__init__,action,context,handler}.py, context_providers/{__init__,ledger_provider}.py, handlers/__init__.py, handlers/llm/{__init__,llm_handler,mappers}.py.
  • tools/__init__.pyToolProvider moved to strands.tools; __getattr__ warns and re-exports. __all__ is already empty.
  • hooks/multiagent/ (__init__.py, events.py) — deprecated, re-exports from strands.hooks.multiagent.
  • hooks/__init__.py non-bidi aliasesBeforeToolInvocationEvent, AfterToolInvocationEvent, BeforeModelInvocationEvent, AfterModelInvocationEvent are deprecated aliases resolved via __getattr__. Keep the live Bidi* events (still experimental, see [FEATURE][EPIC] Bidirectional Streaming - Move out of Experimental #1722); remove only the graduated aliases from __all__.
  • bidi/tools/stop_conversation.py — deprecated tool (.. deprecated::, warns on use); use strands_tools.stop. Note this one is gated on the bidi graduation ([FEATURE][EPIC] Bidirectional Streaming - Move out of Experimental #1722) since it lives under bidi/.

Also remove

  • The corresponding alias-only tests that exist purely to assert the deprecation warnings fire:
    • tests/strands/experimental/steering/test_steering_aliases.py
    • tests/strands/experimental/tools/test_tool_provider_alias.py
    • tests/strands/experimental/hooks/test_hook_aliases.py (non-bidi alias cases only)

Out of scope

Acceptance criteria

  • Importing a removed symbol from its old experimental.* path raises ImportError/AttributeError (not a silent success).
  • No production code imports from the removed shim paths (rg clean).
  • CHANGELOG / migration note points users at the production import paths.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area-devxDeveloper experience improvementsarea-toolTool behavior/apichoreMaintenance tasks, dependency updates, CI changes, refactoring with no user-facing impactpythonPull requests that update python code

    Type

    Fields

    Language

    Python

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions