Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Class-based tools automatically register all public methods (not starting with _) as tools. Simply create a class instance and pass it to your agent or task.

​
Example

from upsonic import Agent, Task

class Calculator:
    """A simple calculator class. All public methods become tools."""
    
    def add(self, a: float, b: float) -> float:
        """
        Add two numbers together.

        Args:
            a: First number
            b: Second number

        Returns:
            The sum of a and b
        """
        return a + b
    
    def multiply(self, a: float, b: float) -> float:
        """
        Multiply two numbers.

        Args:
            a: First number
            b: Second number

        Returns:
            The product of a and b
        """
        return a * b
    
    def _private_helper(self):
        """This method won't become a tool (starts with _)."""
        pass

# Create task with the class instance
calculator = Calculator()
task = Task(
    description="Calculate 15 + 27 and then multiply the result by 3",
    tools=[calculator]
)

# Create agent
agent = Agent(model="anthropic/claude-sonnet-4-5", name="Calculator Agent")

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

​
Key Points

  • Public methods only: Methods starting with _ are ignored
  • Automatic registration: All public methods become tools automatically

​
Class Tool vs ToolKit

FeatureClass ToolToolKit
RegistrationAll public methodsOnly @tool decorated methods
ControlLess control over which methods become toolsExplicit control via @tool decorator
Helper methodsMust prefix with _ to hideAny non-decorated method is hidden
Use caseSimple classes where all methods are toolsComplex classes with internal helpers

​
When to Use Each

Use Class Tool when:
  • All public methods should be tools
  • Simple utility classes
  • Quick prototyping
class Calculator:
    def add(self, a: int, b: int) -> int:
        """Add two numbers."""
        return a + b
    
    def multiply(self, a: int, b: int) -> int:
        """Multiply two numbers."""
        return a * b
Use ToolKit when:
  • You need helper methods that shouldn’t be tools
  • You want explicit control over tool registration
  • You have complex internal logic
from upsonic.tools import ToolKit, tool

class DataProcessor(ToolKit):
    def __init__(self, config: dict):
        self.config = config
    
    @tool
    def process(self, data: str) -> str:
        """Process data using configured rules."""
        cleaned = self._clean(data)
        return self._transform(cleaned)
    
    def _clean(self, data: str) -> str:
        """Helper - not a tool."""
        return data.strip()
    
    def _transform(self, data: str) -> str:
        """Helper - not a tool."""
        return data.upper()

​
State Management

Class instances maintain state between tool calls: 
class Counter:
    def __init__(self):
        self.count = 0
    
    def increment(self) -> int:
        """Increment counter and return new value."""
        self.count += 1
        return self.count
    
    def get_count(self) -> int:
        """Get current count."""
        return self.count

counter = Counter()
agent.add_tools(counter)

# Agent can call increment() multiple times
# Each call uses the same instance with shared state

​
Removing Class Tools

Remove individual methods or the entire class: 
calculator = Calculator()
agent.add_tools(calculator)

# Remove single method (keeps other methods)
agent.remove_tools("add")

# Remove entire class instance (removes all methods)
agent.remove_tools(calculator)