[FEATURE] Move ToolProvider out of experimental

[Unshure]

Problem Statement

I would like to move the ToolProvider class out of experimental, and update references of it to remove mentions of experimental

Proposed Solution

No response

Use Case

You can import ToolProvider from outside of the experimental namespace

Alternatives Solutions

No response

Additional Context

No response

---

Implementation Requirements

Based on clarification discussion and repository analysis:

Overview

Move ToolProvider abstract base class from strands.experimental.tools to strands.tools as a stable public API, with backward compatibility via deprecation warning.

Technical Approach

1. Move ToolProvider Class

• Source: src/strands/experimental/tools/tool_provider.py
• Target: src/strands/tools/tool_provider.py
• Target Import: from strands.tools import ToolProvider

2. Update Exports

• Add ToolProvider to src/strands/tools/__init__.py:

  from .tool_provider import ToolProvider
  
  __all__ = [
      # ... existing exports ...
      "ToolProvider",
  ]

3. Backward Compatibility with Deprecation Warning

Update src/strands/experimental/tools/__init__.py following the pattern from hooks/events.py:

"""Experimental tools package."""

import warnings
from typing import Any

from ...tools import ToolProvider

_DEPRECATED_ALIASES = {
    "ToolProvider": ToolProvider,
}

def __getattr__(name: str) -> Any:
    if name in _DEPRECATED_ALIASES:
        warnings.warn(
            f"{name} has been moved to production. "
            f"Use {_DEPRECATED_ALIASES[name].__name__} from strands.tools instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return _DEPRECATED_ALIASES[name]
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

__all__: list[str] = []

4. Update Internal Imports (6 files)

Source files:

File	Current Import	New Import
src/strands/agent/agent.py	from ..experimental.tools import ToolProvider	from ..tools import ToolProvider
src/strands/tools/mcp/mcp_client.py	from ...experimental.tools import ToolProvider	from .. import ToolProvider
src/strands/tools/registry.py	from ..experimental.tools import ToolProvider	from . import ToolProvider
src/strands/experimental/bidi/agent/agent.py	from ...tools import ToolProvider	from ....tools import ToolProvider

Test files:

File	Current Import	New Import
tests/strands/tools/test_registry.py	from strands.experimental.tools import ToolProvider	from strands.tools import ToolProvider
tests/strands/tools/test_registry_tool_provider.py	from strands.experimental.tools.tool_provider import ToolProvider	from strands.tools import ToolProvider

5. Update MCPClient Docstring

Remove experimental warning from src/strands/tools/mcp/mcp_client.py:

Remove this warning block from docstring (lines ~110-112):

Warning:
    This class implements the experimental ToolProvider interface and its methods
    are subject to change.

6. Update Documentation

Update AGENTS.md directory structure to reflect new location:

• Remove: │ │ └── tools/ # Experimental tools
• Remove: │ │ └── tool_provider.py
• Add tool_provider.py under src/strands/tools/ section

Acceptance Criteria

• ToolProvider can be imported from strands.tools
• Old import path strands.experimental.tools.ToolProvider still works but emits DeprecationWarning
• All internal imports updated to use new path
• MCPClient docstring no longer mentions experimental
• AGENTS.md updated with new directory structure
• All existing tests pass with updated imports
• hatch fmt --formatter and hatch fmt --linter pass
• hatch test passes

[Unshure]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and have some questions to ensure proper implementation:

Repository Context

• Current Location: src/strands/experimental/tools/tool_provider.py
• Target Location: src/strands/tools/tool_provider.py
• Class: ToolProvider - Abstract base class with 3 methods: load_tools(), add_consumer(), remove_consumer()
• Existing Implementation: MCPClient in src/strands/tools/mcp/mcp_client.py already inherits from ToolProvider
• Related Exception: ToolProviderException already exists in non-experimental src/strands/types/exceptions.py

Files Requiring Updates

Source files (5 import statements):

1. src/strands/agent/agent.py
2. src/strands/tools/mcp/mcp_client.py
3. src/strands/tools/registry.py
4. src/strands/experimental/bidi/agent/agent.py

Test files (2 import statements):
5. tests/strands/tools/test_registry.py
6. tests/strands/tools/test_registry_tool_provider.py

Documentation:

• AGENTS.md - directory structure references

Clarifying Questions

1. Target Import Path

After moving, what should be the recommended import path for users?

• Option A: from strands.tools import ToolProvider (tools subpackage)
• Option B: from strands import ToolProvider (top-level package)
• Option C: Both options available

2. Backward Compatibility

Should we maintain backward compatibility with the old import path?

• Option A: Keep re-export from strands.experimental.tools with deprecation warning
• Option B: Keep re-export from strands.experimental.tools without deprecation (silent redirect)
• Option C: Remove completely from experimental (breaking change)

3. Documentation Updates

The MCPClient class docstring currently says:

"Warning: This class implements the experimental ToolProvider interface and its methods are subject to change."

Should this warning be:

• Option A: Removed entirely (since ToolProvider is now stable)
• Option B: Updated to clarify that the ToolProvider interface is now stable
• Option C: Left as-is for now

4. Scope Confirmation

This task involves:

• Moving 1 file
• Updating 6 import statements
• Updating exports in __init__.py files
• Updating AGENTS.md directory structure
• Optionally adding deprecation warning

Is this scope appropriate for a single PR, or would you prefer it broken down differently?

[Unshure]

/strands

1. from strands.tools import ToolProvider
2. Yes, you can follow the example here: https://github.com/strands-agents/sdk-python/blob/main/src/strands/experimental/hooks/events.py
3. Option A
4. Single pr

[Unshure]

/strands implement

[github-actions]

Unable to create pull request via API. You can create it manually by clicking here.