Attributes

Configuration options for custom tools

Attributes

Custom tools support comprehensive configuration through the @tool decorator:

Attribute	Type	Default	Description
requires_confirmation	bool	False	Require user confirmation before execution
requires_user_input	bool	False	Prompt user for input during execution
user_input_fields	List[str] | None	None	Specify which fields require user input
external_execution	bool	False	Mark tool for external execution
show_result	bool	False	Display output to user instead of sending to LLM
stop_after_tool_call	bool	False	Terminate agent run after tool execution
sequential	bool	False	Enforce sequential execution (no parallelization)
cache_results	bool	False	Enable result caching
cache_dir	str | None	None	Directory for cache storage
cache_ttl	int | None	None	Cache time-to-live in seconds
tool_hooks	ToolHooks | None	None	Before/after execution hooks
max_retries	int	0	Maximum retry attempts
timeout	int | None	None	Execution timeout in seconds
strict	bool	False	Enforce strict JSON schema validation
docstring_format	str	"auto"	Docstring parsing format: ‘google’, ‘numpy’, ‘sphinx’, ‘auto’
require_parameter_descriptions	bool	True	Require descriptions for all parameters in docstring

Example Usage

from upsonic import Agent, Task
from upsonic.tools import tool, ToolHooks

# Define hooks
def before_search(**kwargs):
    print(f"Searching for: {kwargs.get('query')}")
    return {"logged_query": kwargs.get('query')}

def after_search(result, **kwargs):
    print(f"Found {len(result)} results")
    return {"result_count": len(result)}

hooks = ToolHooks(before=before_search, after=after_search)

@tool(
    requires_confirmation=True,
    timeout=30,
    max_retries=2,
    cache_results=True,
    cache_ttl=3600,
    tool_hooks=hooks,
    sequential=True
)
def search_database(query: str, limit: int = 10) -> list:
    """
    Search the database for matching records.
    
    Args:
        query: Search query string
        limit: Maximum number of results to return
    
    Returns:
        List of matching records
    """
    return [f"Record {i}: Found '{query}' in database" for i in range(1, limit + 1)] 

# Create agent and task
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task(
    description="Search the database for 'Upsonic' and return the top 5 results",
    tools=[search_database]
)

# Execute
result = agent.print_do(task)
print("Result:", result)

requires_confirmation=True is designed for interactive environments where a user can respond to confirmation prompts. When running scripts non-interactively, remove this attribute or set it to False to avoid blocking.