Adding Tools - Upsonic AI

Tasks can be equipped with various tools to extend their capabilities. Tools are added through the tools parameter and can include custom functions, built-in tools, or tool collections.

Single Tool

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

@tool
def web_search(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

task = Task(
    description="Search for information about AI",
    tools=[web_search]
)

agent = Agent("anthropic/claude-sonnet-4-5")
agent.print_do(task)

Multiple Tools

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

@tool
def web_search(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

@tool
def data_processor(data: str) -> str:
    """Process and analyze data."""
    return f"Processed: {data}"

task = Task(
    description="Search for information about AI and process the results",
    tools=[web_search, data_processor]
)

agent = Agent("anthropic/claude-sonnet-4-5")
agent.print_do(task)

Tool Collections

from upsonic import Agent, Task
from upsonic.tools.common_tools.financial_tools import YFinanceTools

# Create a tool collection
finance_tools = YFinanceTools(
    stock_price=True,
    company_info=True,
    analyst_recommendations=True
)

task = Task(
    description="Get stock information for AAPL",
    tools=finance_tools.functions()
)

agent = Agent(model="anthropic/claude-sonnet-4-5")
agent.print_do(task)

Tool Configuration

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

@tool(requires_confirmation=True)
def sensitive_operation(data: str) -> str:
    """Perform a sensitive operation that requires confirmation."""
    return f"Processed sensitive data: {data}"

task = Task(
    description="Process sensitive information with data 'Upsonic'",
    tools=[sensitive_operation]
)

agent = Agent(model="anthropic/claude-sonnet-4-5")
agent.print_do(task)

Available Tool Configurations

Configuration	Type	Description
requires_confirmation	bool	Pause for user confirmation before execution
requires_user_input	bool	Prompt user for input during execution
user_input_fields	List[str]	Fields to prompt user for when requires_user_input is True
external_execution	bool	Handle execution externally (advanced use-cases)
show_result	bool	Display result directly to user without LLM processing
stop_after_tool_call	bool	Terminate agent after this tool call
sequential	bool	Require sequential execution (no parallelization)
cache_results	bool	Cache the result based on arguments
cache_dir	Optional[str]	Directory to store cache files
cache_ttl	Optional[int]	Time-to-live for cache entries in seconds
tool_hooks	Optional[ToolHooks]	Custom functions to run before/after tool execution
max_retries	Optional[int]	Maximum number of retries allowed for this tool (default: 5)
timeout	Optional[float]	Timeout for tool execution in seconds (default: 30.0)
strict	Optional[bool]	Enforce strict JSON schema validation on tool parameters
docstring_format	str	Format of the docstring: ‘google’, ‘numpy’, ‘sphinx’, or ‘auto’
require_parameter_descriptions	bool	Raise error if required parameter descriptions are missing

Dynamic Tool Management

You can add or remove tools after task creation:

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

@tool
def web_search(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

@tool
def calculator(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

task = Task(description="Search for AI news and calculate 10 + 20")
agent = Agent("anthropic/claude-sonnet-4-5")

# Add tools dynamically
task.add_tools([web_search, calculator])

# Execute task with dynamically added tools
agent.print_do(task)

# Remove tools (for subsequent executions)
task.remove_tools([web_search], agent=agent)

Accessing Registered Tools

After execution, access registered tools via the registered_task_tools attribute:

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

@tool
def calculator(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

task = Task(description="Calculate 5 + 3", tools=[calculator])
agent = Agent("anthropic/claude-sonnet-4-5")
agent.print_do(task)

# Access registered tools
print(task.registered_task_tools)  # Dict mapping tool names to wrapped tools

Best Practices

Tool Validation: All tools must have type hints and docstrings
Single Responsibility: Each tool should have a clear, focused purpose
Error Handling: Implement proper error handling within tool functions
Configuration: Use tool configurations appropriately for security and user experience
Documentation: Write clear docstrings that explain the tool’s purpose to the LLM

​Single Tool

​Multiple Tools

​Tool Collections

​Tool Configuration

​Available Tool Configurations

​Dynamic Tool Management

​Accessing Registered Tools

​Best Practices