Skip to main content
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("openai/gpt-4o")
result = agent.do(task)
print(result)

​
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("openai/gpt-4o")
result = agent.do(task)
print(result)

​
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="openai/gpt-4o")

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

​
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="openai/gpt-4o")

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

​
Available Tool Configurations

ConfigurationTypeDescription
requires_confirmationboolPause for user confirmation before execution
requires_user_inputboolPrompt user for input during execution
user_input_fieldsList[str]Fields to prompt user for when requires_user_input is True
external_executionboolHandle execution externally (advanced use-cases)
show_resultboolDisplay result directly to user without LLM processing
stop_after_tool_callboolTerminate agent after this tool call
sequentialboolRequire sequential execution (no parallelization)
cache_resultsboolCache the result based on arguments
cache_dirOptional[str]Directory to store cache files
cache_ttlOptional[int]Time-to-live for cache entries in seconds
tool_hooksOptional[ToolHooks]Custom functions to run before/after tool execution
max_retriesOptional[int]Maximum number of retries allowed for this tool (default: 5)
timeoutOptional[float]Timeout for tool execution in seconds (default: 30.0)
strictOptional[bool]Enforce strict JSON schema validation on tool parameters
docstring_formatstrFormat of the docstring: ‘google’, ‘numpy’, ‘sphinx’, or ‘auto’
require_parameter_descriptionsboolRaise 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("openai/gpt-4o")

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

# Execute task with dynamically added tools
result = agent.do(task)
print(result)

# 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("openai/gpt-4o")
result = agent.do(task)
print(result)

# 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