strands.tools.tools

Core tool implementations.

This module provides the base classes for all tool implementations in the SDK, including function-based tools and Python module-based tools, as well as utilities for validating tool uses and normalizing tool schemas.

InvalidToolUseNameException

class InvalidToolUseNameException(Exception)

Defined in: src/strands/tools/tools.py:27

Exception raised when a tool use has an invalid name.

validate_tool_use

def validate_tool_use(tool: ToolUse) -> None

Defined in: src/strands/tools/tools.py:33

Validate a tool use request.

Arguments:

• tool - The tool use to validate.

validate_tool_use_name

def validate_tool_use_name(tool: ToolUse) -> None

Defined in: src/strands/tools/tools.py:42

Validate the name of a tool use.

Arguments:

• tool - The tool use to validate.

Raises:

• InvalidToolUseNameException - If the tool name is invalid.

normalize_schema

def normalize_schema(schema: dict[str, Any]) -> dict[str, Any]

Defined in: src/strands/tools/tools.py:104

Normalize a JSON schema to match expectations.

This function recursively processes nested objects to preserve the complete schema structure. Uses a copy-then-normalize approach to preserve all original schema properties.

Arguments:

• schema - The schema to normalize.

Returns:

The normalized schema.

normalize_tool_spec

def normalize_tool_spec(tool_spec: ToolSpec) -> ToolSpec

Defined in: src/strands/tools/tools.py:133

Normalize a complete tool specification by transforming its inputSchema.

Arguments:

• tool_spec - The tool specification to normalize.

Returns:

The normalized tool specification.

PythonAgentTool

class PythonAgentTool(AgentTool)

Defined in: src/strands/tools/tools.py:157

Tool implementation for Python-based tools.

This class handles tools implemented as Python functions, providing a simple interface for executing Python code as SDK tools.

__init__

def __init__(tool_name: str, tool_spec: ToolSpec, tool_func: ToolFunc) -> None

Defined in: src/strands/tools/tools.py:168

Initialize a Python-based tool.

Arguments:

• tool_name - Unique identifier for the tool.
• tool_spec - Tool specification defining parameters and behavior.
• tool_func - Python function to execute when the tool is invoked.

tool_name

@property
def tool_name() -> str

Defined in: src/strands/tools/tools.py:183

Get the name of the tool.

Returns:

The name of the tool.

tool_spec

@property
def tool_spec() -> ToolSpec

Defined in: src/strands/tools/tools.py:192

Get the tool specification for this Python-based tool.

Returns:

The tool specification.

supports_hot_reload

@property
def supports_hot_reload() -> bool

Defined in: src/strands/tools/tools.py:201

Check if this tool supports automatic reloading when modified.

Returns:

Always true for function-based tools.

tool_type

@property
def tool_type() -> str

Defined in: src/strands/tools/tools.py:210

Identifies this as a Python-based tool implementation.

Returns:

“python”.

stream

@override
async def stream(tool_use: ToolUse, invocation_state: dict[str, Any],
                 **kwargs: Any) -> ToolGenerator

Defined in: src/strands/tools/tools.py:219

Stream the Python function with the given tool use request.

Arguments:

• tool_use - The tool use request.
• invocation_state - Context for the tool invocation, including agent state.
• **kwargs - Additional keyword arguments for future extensibility.

Yields:

Tool events with the last being the tool result.