In Agency Swarm, tools are Python classes that inherit from BaseTool. They are defined using Pydantic, a data validation library. Each BaseTool must implement the run method, which is the main method that will be called when the tool is invoked by an agent.

​
Step-by-step Guide

To create a custom tool, typically you need to follow these steps:

1

Add Import Statements

On top of your tool file, import the necessary modules and classes.

from agency_swarm.tools import BaseTool
from pydantic import Field, model_validator
# ... other imports
2

Define the Tool Class and Docstring

Create a new class that inherits from BaseTool. Write a clear docstring describing the tool’s purpose. This docstring is crucial as it helps agents understand how to use the tool.

class Calculator(BaseTool):
    """
    A simple calculator tool that evaluates mathematical expressions.
    """
3

Define Input Fields

Use Pydantic fields to define the inputs your tool will accept.

expression: str = Field(..., description="The mathematical expression to evaluate.")
4

Implement the run Method

Add the functionality that will be executed when the tool is called.

def run(self):
    # Implement the tool's functionality
    result = eval(self.expression)
    return str(result)

The run method should return a string, which is the tool’s output that the agent will see and use in its response.

5

Test the Tool Independently

Test the tool independently to ensure it behaves as expected. We recommend adding a if __name__ == "__main__": block at the end of the tool file:

if __name__ == "__main__":
    calc = Calculator(expression="2 + 2 * 3")
    print(calc.run())  # Output should be '8'
6

Add the Tool to an Agent

After your tool works as expected, simply add it to an agent’s list of tools.

from agency_swarm import Agent
from .tools.calculator import Calculator

agent = Agent(
    name="MathAgent",
    tools=[Calculator],
    # Other agent parameters
)

​
Full Code Example

Below is the full code example for a calculator tool above.

# calculator.py
from agency_swarm.tools import BaseTool
from pydantic import Field, model_validator

class Calculator(BaseTool):
    """
    A simple calculator tool that evaluates mathematical expressions.
    """
    expression: str = Field(..., description="The mathematical expression to evaluate.")

    @model_validator(mode="after")
    def validate_expression(self):
        if self.expression.endswith("/0"):
            raise ValueError("Division by zero is not permitted")

    def run(self):
        result = eval(self.expression)
        return str(result)

if __name__ == "__main__":
    calc = Calculator(expression="2 + 2 * 3")
    print(calc.run())  # Output should be '8'

​
Next Steps