Skip to content
SDKs
PY sdk-python TS sdk-typescript
Organizations
strands-agents strands-labs

strands.tools.registry

Tool registry.

This module provides the central registry for all tools available to the agent, including discovery, validation, and invocation capabilities.

ToolRegistry

Section titled “ToolRegistry”
class ToolRegistry()

Defined in: src/strands/tools/registry.py:31

Central registry for all tools available to the agent.

This class manages tool registration, validation, discovery, and invocation.

__init__

Section titled “__init__”
def __init__() -> None

Defined in: src/strands/tools/registry.py:37

Initialize the tool registry.

process_tools

Section titled “process_tools”
def process_tools(tools: list[Any]) -> list[str]

Defined in: src/strands/tools/registry.py:45

Process tools list.

Process list of tools that can contain local file path string, module import path string, imported modules, @tool decorated functions, or instances of AgentTool.

Arguments:

  • tools - List of tool specifications. Can be:

    1. Local file path to a module based tool: ./path/to/module/tool.py
    2. Module import path

    2.1. Path to a module based tool: strands_tools.file_read 2.2. Path to a module with multiple AgentTool instances (@tool decorated): tests.fixtures.say_tool 2.3. Path to a module and a specific function: tests.fixtures.say_tool:say

    1. A module for a module based tool
    2. Instances of AgentTool (@tool decorated functions)
    3. Dictionaries with name/path keys (deprecated)

Returns:

List of tool names that were processed.

load_tool_from_filepath

Section titled “load_tool_from_filepath”
def load_tool_from_filepath(tool_name: str, tool_path: str) -> None

Defined in: src/strands/tools/registry.py:155

DEPRECATED: Load a tool from a file path.

Arguments:

  • tool_name - Name of the tool.
  • tool_path - Path to the tool file.

Raises:

  • FileNotFoundError - If the tool file is not found.
  • ValueError - If the tool cannot be loaded.

get_all_tools_config

Section titled “get_all_tools_config”
def get_all_tools_config() -> dict[str, Any]

Defined in: src/strands/tools/registry.py:190

Dynamically generate tool configuration by combining built-in and dynamic tools.

Returns:

Dictionary containing all tool configurations.

register_tool

Section titled “register_tool”
def register_tool(tool: AgentTool) -> None

Defined in: src/strands/tools/registry.py:230

Register a tool function with the given name.

Arguments:

  • tool - The tool to register.

replace

Section titled “replace”
def replace(new_tool: AgentTool) -> None

Defined in: src/strands/tools/registry.py:283

Replace an existing tool with a new implementation.

This performs a swap of the tool implementation in the registry. The replacement takes effect on the next agent invocation.

Arguments:

  • new_tool - New tool implementation. Its name must match the tool being replaced.

Raises:

  • ValueError - If the tool doesn’t exist.

get_tools_dirs

Section titled “get_tools_dirs”
def get_tools_dirs() -> list[Path]

Defined in: src/strands/tools/registry.py:309

Get all tool directory paths.

Returns:

A list of Path objects for current working directory’s ”./tools/“.

discover_tool_modules

Section titled “discover_tool_modules”
def discover_tool_modules() -> dict[str, Path]

Defined in: src/strands/tools/registry.py:329

Discover available tool modules in all tools directories.

Returns:

Dictionary mapping tool names to their full paths.

reload_tool

Section titled “reload_tool”
def reload_tool(tool_name: str) -> None

Defined in: src/strands/tools/registry.py:354

Reload a specific tool module.

Arguments:

  • tool_name - Name of the tool to reload.

Raises:

  • FileNotFoundError - If the tool file cannot be found.
  • ImportError - If there are issues importing the tool module.
  • ValueError - If the tool specification is invalid or required components are missing.
  • Exception - For other errors during tool reloading.

initialize_tools

Section titled “initialize_tools”
def initialize_tools(load_tools_from_directory: bool = False) -> None

Defined in: src/strands/tools/registry.py:454

Initialize all tools by discovering and loading them dynamically from all tool directories.

Arguments:

  • load_tools_from_directory - Whether to reload tools if changes are made at runtime.

get_all_tool_specs

Section titled “get_all_tool_specs”
def get_all_tool_specs() -> list[ToolSpec]

Defined in: src/strands/tools/registry.py:565

Get all the tool specs for all tools in this registry..

Returns:

A list of ToolSpecs.

register_dynamic_tool

Section titled “register_dynamic_tool”
def register_dynamic_tool(tool: AgentTool) -> None

Defined in: src/strands/tools/registry.py:575

Register a tool dynamically for temporary use.

Arguments:

  • tool - The tool to register dynamically

Raises:

  • ValueError - If a tool with this name already exists

validate_tool_spec

Section titled “validate_tool_spec”
def validate_tool_spec(tool_spec: ToolSpec) -> None

Defined in: src/strands/tools/registry.py:590

Validate tool specification against required schema.

Arguments:

  • tool_spec - Tool specification to validate.

Raises:

  • ValueError - If the specification is invalid.

NewToolDict

Section titled “NewToolDict”
class NewToolDict(TypedDict)

Defined in: src/strands/tools/registry.py:640

Dictionary type for adding or updating a tool in the configuration.

Attributes:

  • spec - The tool specification that defines the tool’s interface and behavior.

cleanup

Section titled “cleanup”
def cleanup(**kwargs: Any) -> None

Defined in: src/strands/tools/registry.py:708

Synchronously clean up all tool providers in this registry.