Decorators

decorators

Tool decorator for converting Python functions into LLM-callable tools.

This module provides the @tool decorator which adds metadata to functions that allows them to be used as tools in LLM function calling.

tool

tool(description: Optional[str] = None, parameters: Optional[Dict[str, Any]] = None, category: str = 'general', requires_confirmation: bool = False, cacheable: bool = False, cache_ttl: int = 300)

A decorator to convert a Python function into a tool with LLM-callable metadata.

The decorated function will have a tool_definition attribute containing an OpenAI-compatible function schema that can be used for LLM function calling.

Parameters:

Name	Type	Description	Default
description	Optional[str]	Optional. Description of the function's purpose. If not provided, extracted from the function's docstring.	None
parameters	Optional[Dict[str, Any]]	Optional. JSON schema for function parameters. If not provided, inferred from the function's signature and type hints.	None
category	str	Tool category for organization (default: "general")	'general'
requires_confirmation	bool	Whether the tool requires user confirmation (default: False)	False
cacheable	bool	Whether results can be cached (default: False)	False
cache_ttl	int	Cache time-to-live in seconds (default: 300)	300

Returns:

Type	Description
	A decorator that adds tool metadata to the function.

Example

@tool(description="Search the web for information") async def web_search(query: str, limit: int = 10) -> str: ''' Search the web.

Args:
    query: The search query
    limit: Maximum results to return
'''
return f"Results for {query}"

The function now has tool_definition attribute:

web_search.tool_definition = {

"type": "function",

"function": {

"name": "web_search",

"description": "Search the web for information",

"parameters": {

"type": "object",

"properties": {

"query": {"type": "string", "description": "The search query"},

"limit":

},

"required": ["query"]

}

}

}

Source code in reactive_agents/core/tools/decorators.py

def tool(
    description: Optional[str] = None,
    parameters: Optional[Dict[str, Any]] = None,
    category: str = "general",
    requires_confirmation: bool = False,
    cacheable: bool = False,
    cache_ttl: int = 300,
):
    """
    A decorator to convert a Python function into a tool with LLM-callable metadata.

    The decorated function will have a `tool_definition` attribute containing
    an OpenAI-compatible function schema that can be used for LLM function calling.

    Args:
        description: Optional. Description of the function's purpose.
                    If not provided, extracted from the function's docstring.
        parameters: Optional. JSON schema for function parameters.
                   If not provided, inferred from the function's signature and type hints.
        category: Tool category for organization (default: "general")
        requires_confirmation: Whether the tool requires user confirmation (default: False)
        cacheable: Whether results can be cached (default: False)
        cache_ttl: Cache time-to-live in seconds (default: 300)

    Returns:
        A decorator that adds tool metadata to the function.

    Example:
        @tool(description="Search the web for information")
        async def web_search(query: str, limit: int = 10) -> str:
            '''
            Search the web.

            Args:
                query: The search query
                limit: Maximum results to return
            '''
            return f"Results for {query}"

        # The function now has tool_definition attribute:
        # web_search.tool_definition = {
        #     "type": "function",
        #     "function": {
        #         "name": "web_search",
        #         "description": "Search the web for information",
        #         "parameters": {
        #             "type": "object",
        #             "properties": {
        #                 "query": {"type": "string", "description": "The search query"},
        #                 "limit": {"type": "integer", "description": "Maximum results to return"}
        #             },
        #             "required": ["query"]
        #         }
        #     }
        # }
    """

    def decorator(func: Callable) -> Callable:
        # Preserve async nature of function
        if inspect.iscoroutinefunction(func):
            @wraps(func)
            async def wrapper(*args, **kwargs):
                return await func(*args, **kwargs)
        else:
            @wraps(func)
            def wrapper(*args, **kwargs):
                return func(*args, **kwargs)

        # Build parameters schema
        inferred_parameters = _build_parameters_schema(func)

        # Get description
        final_description = _get_function_description(func, description)

        # Attach the tool metadata as an attribute
        wrapper.tool_definition = {
            "type": "function",
            "function": {
                "name": func.__name__,
                "description": final_description,
                "parameters": parameters or inferred_parameters,
            },
        }

        # Attach additional metadata for the new Tool class
        wrapper.tool_metadata = {
            "category": category,
            "requires_confirmation": requires_confirmation,
            "cacheable": cacheable,
            "cache_ttl": cache_ttl,
        }

        return wrapper

    return decorator

create_tool_from_function

create_tool_from_function(func: Callable, description: Optional[str] = None, parameters: Optional[Dict[str, Any]] = None, **kwargs) -> Tool

Create a Tool instance directly from a function.

This is a convenience function that combines the @tool decorator with Tool instantiation.

Parameters:

Name	Type	Description	Default
func	Callable	The function to convert to a tool	required
description	Optional[str]	Optional description override	None
parameters	Optional[Dict[str, Any]]	Optional parameters schema override	None
**kwargs		Additional Tool configuration (category, requires_confirmation, etc.)	{}

Returns:

Type	Description
Tool	A configured Tool instance

Example

async def my_search(query: str) -> str: return f"Results for {query}"

tool = create_tool_from_function( my_search, description="Search for things", category="search" )

Source code in reactive_agents/core/tools/decorators.py

def create_tool_from_function(
    func: Callable,
    description: Optional[str] = None,
    parameters: Optional[Dict[str, Any]] = None,
    **kwargs
) -> "Tool":
    """Create a Tool instance directly from a function.

    This is a convenience function that combines the @tool decorator
    with Tool instantiation.

    Args:
        func: The function to convert to a tool
        description: Optional description override
        parameters: Optional parameters schema override
        **kwargs: Additional Tool configuration (category, requires_confirmation, etc.)

    Returns:
        A configured Tool instance

    Example:
        async def my_search(query: str) -> str:
            return f"Results for {query}"

        tool = create_tool_from_function(
            my_search,
            description="Search for things",
            category="search"
        )
    """
    from reactive_agents.core.tools.base import Tool

    # Apply the decorator to get tool_definition
    decorated = tool(description=description, parameters=parameters, **kwargs)(func)

    # Create and return Tool instance
    return Tool(function=decorated)