Skip to main content

Attributes

Custom tools support comprehensive configuration through the @tool decorator:
AttributeTypeDefaultDescription
requires_confirmationboolFalseRequire user confirmation before execution
requires_user_inputboolFalsePrompt user for input during execution
user_input_fieldsList[str] | NoneNoneSpecify which fields require user input
external_executionboolFalseMark tool for external execution
show_resultboolFalseDisplay output to user instead of sending to LLM
stop_after_tool_callboolFalseTerminate agent run after tool execution
sequentialboolFalseEnforce sequential execution (no parallelization)
cache_resultsboolFalseEnable result caching
cache_dirstr | NoneNoneDirectory for cache storage
cache_ttlint | NoneNoneCache time-to-live in seconds
tool_hooksToolHooks | NoneNoneBefore/after execution hooks
max_retriesint0Maximum retry attempts
timeoutint | NoneNoneExecution timeout in seconds
strictboolFalseEnforce strict JSON schema validation
docstring_formatstr"auto"Docstring parsing format: ‘google’, ‘numpy’, ‘sphinx’, ‘auto’
require_parameter_descriptionsboolTrueRequire descriptions for all parameters in docstring

Example Usage

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

# Define hooks
def before_search(query: str):
    print(f"Searching for: {query}")
    return {"logged_query": query}

def after_search(result):
    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("openai/gpt-4o")
task = Task(
    description="Search the database for 'Upsonic' and return the top 5 results",
    tools=[search_database]
)

# Execute
result = agent.do(task)
print(result)