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]	`[]`	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	`5`	Maximum retry attempts
`timeout`	float \| None	`30.0`	Execution timeout in seconds
`strict`	bool \| None	`None`	Enforce strict JSON schema validation
`docstring_format`	str	`"auto"`	Docstring parsing format: ‘google’, ‘numpy’, ‘sphinx’, ‘auto’
`require_parameter_descriptions`	bool	`False`	Require descriptions for all parameters in docstring
`instructions`	str \| None	`None`	Instructions for the LLM on how to use this tool, injected into the system prompt
`add_instructions`	bool	`False`	If True, the tool’s instructions will be appended to the agent’s system prompt

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.

​Attributes

​Example Usage

Attributes

Example Usage