tools

Tool registration and execution for agentic workflows.

class ToolDefinition(name, description, parameters=<factory>, implementation='', enabled=True)[source]

Bases: object

Declarative tool definition.

Parameters:

name (str)
description (str)
parameters (dict[str, Any])
implementation (str)
enabled (bool)

name

Unique identifier for this tool.

Type:: str

description

Human-readable description sent to the LLM.

Type:: str

parameters

JSON Schema describing the tool’s parameters.

Type:: dict[str, Any]

implementation

Implementation reference string (python:<module>.<function>).

Type:: str

enabled

Whether this tool is available for use.

Type:: bool

name: str

description: str

parameters: dict[str, Any]

implementation: str = ''

enabled: bool = True

to_openai_tool()[source]

Convert to OpenAI function-calling tool schema.

Returns:: Dictionary in OpenAI tool format.
Return type:: dict[str, Any]

to_dict()[source]

Convert to dictionary for serialization.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]

Create from dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with tool definition fields.
Returns:: A new ToolDefinition instance.
Return type:: ToolDefinition

class ToolRegistry[source]

Bases: object

Registry of tools available for agentic execution.

Usage:

registry = ToolRegistry() registry.register(ToolDefinition(

name=’calculate’, description=’Perform a calculation’, parameters={…},

)) registry.register_executor(‘calculate’, my_calc_fn)

schema = registry.get_tools_schema([‘calculate’]) result = registry.execute_tool(‘calculate’, {‘expr’: ‘2+2’})

register(definition)[source]

Register a tool definition.

Parameters:: definition (ToolDefinition) – The tool definition to register.
Raises:: ValueError – If a tool with the same name is already registered.
Return type:: None

register_executor(name, executor)[source]

Register a callable executor for a tool.

Parameters:

name (str) – Tool name (must already be registered via register()).
executor (Callable[[...], str]) – Callable that accepts a dict of arguments and returns a string.

Raises:

ValueError – If the tool is not registered.

Return type:

None

get_tool(name)[source]

Get a tool definition by name.

Parameters:: name (str) – Tool name.
Returns:: The tool definition.
Raises:: KeyError – If the tool is not registered.
Return type:: ToolDefinition

has_tool(name)[source]

Check if a tool is registered.

Parameters:: name (str)
Return type:: bool

get_registered_names()[source]

Get list of registered tool names.

Return type:: list[str]

get_enabled_names()[source]

Get list of enabled tool names.

Return type:: list[str]

get_tools_schema(tool_names)[source]

Get OpenAI-format tool schemas for the specified tools.

Parameters:: tool_names (list[str]) – List of tool names to include.
Returns:: List of tool schema dictionaries in OpenAI function-calling format.
Return type:: list[dict[str, Any]]

execute_tool(name, arguments)[source]

Execute a tool by name with the given arguments.

Resolution order: 1. Registered executor (from register_executor()) 2. python: implementation (dynamic import)

Parameters:

name (str) – Tool name.
arguments (dict[str, Any]) – Arguments to pass to the tool.

Returns:

Tool execution result as a string.

Raises:

KeyError – If the tool is not registered.
RuntimeError – If tool execution fails.

Return type:

str

static load_python_callable(path)[source]

Load a Python callable from a dotted module.function path.

Parameters:: path (str) – Dotted path like ‘my_package.my_module.my_function’.
Returns:: The callable or None.
Return type:: Callable[[…], Any] | None

Classes

class ToolDefinition(name, description, parameters=<factory>, implementation='', enabled=True)[source]

Bases: object

Declarative tool definition.

Parameters:

name (str)
description (str)
parameters (dict[str, Any])
implementation (str)
enabled (bool)

name

Unique identifier for this tool.

Type:: str

description

Human-readable description sent to the LLM.

Type:: str

parameters

JSON Schema describing the tool’s parameters.

Type:: dict[str, Any]

implementation

Implementation reference string (python:<module>.<function>).

Type:: str

enabled

Whether this tool is available for use.

Type:: bool

name: str

description: str

parameters: dict[str, Any]

implementation: str = ''

enabled: bool = True

to_openai_tool()[source]

Convert to OpenAI function-calling tool schema.

Returns:: Dictionary in OpenAI tool format.
Return type:: dict[str, Any]

to_dict()[source]

Convert to dictionary for serialization.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]

Create from dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with tool definition fields.
Returns:: A new ToolDefinition instance.
Return type:: ToolDefinition

class ToolRegistry[source]

Bases: object

Registry of tools available for agentic execution.

Usage:

registry = ToolRegistry() registry.register(ToolDefinition(

name=’calculate’, description=’Perform a calculation’, parameters={…},

)) registry.register_executor(‘calculate’, my_calc_fn)

schema = registry.get_tools_schema([‘calculate’]) result = registry.execute_tool(‘calculate’, {‘expr’: ‘2+2’})

register(definition)[source]

Register a tool definition.

Parameters:: definition (ToolDefinition) – The tool definition to register.
Raises:: ValueError – If a tool with the same name is already registered.
Return type:: None

register_executor(name, executor)[source]

Register a callable executor for a tool.

Parameters:

name (str) – Tool name (must already be registered via register()).
executor (Callable[[...], str]) – Callable that accepts a dict of arguments and returns a string.

Raises:

ValueError – If the tool is not registered.

Return type:

None

get_tool(name)[source]

Get a tool definition by name.

Parameters:: name (str) – Tool name.
Returns:: The tool definition.
Raises:: KeyError – If the tool is not registered.
Return type:: ToolDefinition

has_tool(name)[source]

Check if a tool is registered.

Parameters:: name (str)
Return type:: bool

get_registered_names()[source]

Get list of registered tool names.

Return type:: list[str]

get_enabled_names()[source]

Get list of enabled tool names.

Return type:: list[str]

get_tools_schema(tool_names)[source]

Get OpenAI-format tool schemas for the specified tools.

Parameters:: tool_names (list[str]) – List of tool names to include.
Returns:: List of tool schema dictionaries in OpenAI function-calling format.
Return type:: list[dict[str, Any]]

execute_tool(name, arguments)[source]

Execute a tool by name with the given arguments.

Resolution order: 1. Registered executor (from register_executor()) 2. python: implementation (dynamic import)

Parameters:

name (str) – Tool name.
arguments (dict[str, Any]) – Arguments to pass to the tool.

Returns:

Tool execution result as a string.

Raises:

KeyError – If the tool is not registered.
RuntimeError – If tool execution fails.

Return type:

str

static load_python_callable(path)[source]

Load a Python callable from a dotted module.function path.

Parameters:: path (str) – Dotted path like ‘my_package.my_module.my_function’.
Returns:: The callable or None.
Return type:: Callable[[…], Any] | None