Step-by-Step Guide

In Agency Swarm, tools enable agents to perform specific actions and interact with external systems. The framework supports two approaches for creating custom tools depending on the version you’re using. Framework supports 2 methods of creating tools:

Using agency-swarm’s BaseTool class.
Using openai’s @function_tool decorator with async functions.

Explore the sections below to find a method that suits your approach the best.

BaseTool
FunctionTool

In Agency Swarm’s approach, 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.

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

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

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.
    """

Define Input Fields

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

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

Custom Validation Logic (Optional)

You can use Pydantic’s validators to verify the inputs. This can be extremely effective to avoid hallucinations or other errors in production.

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

Implement the run Method

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

async 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.

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:

import asyncio

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

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
)

Using tools folder

Alternatively, you can simply place the tool file in the tools_folder directory and it will be automatically added to the agent.

from agency_swarm import Agent
agent = Agent(
    name="MathAgent",
    tools_folder="./tools",
    # Other agent parameters
)

Each file in the tools_folder should contain a class that is named exactly the same as the file name. For example, Calculator.py should contain a Calculator class.

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")

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

if __name__ == "__main__":
    import asyncio

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

Step-by-step Guide

Add Import Statements

Import the necessary modules for the new function-based approach.

from agency_swarm import function_tool, RunContextWrapper
from pydantic import BaseModel, Field, field_validator
from agency_swarm import MasterContext

Define Args Schema

Create a Pydantic model to define your tool’s input parameters.

class CalculatorArgs(BaseModel):
    expression: str = Field(..., description="The mathematical expression to evaluate")

    @field_validator("expression")
    @classmethod
    def validate_expression(cls, v):
        if "/0" in v:
            raise ValueError("Division by zero is not permitted")
        return v

Create the Tool Function

Define an async function with the @function_tool decorator.

@function_tool
async def calculator_tool(ctx: RunContextWrapper[MasterContext], args: CalculatorArgs) -> str:
    """
    A calculator tool that evaluates mathematical expressions.
    Use this when you need to perform mathematical calculations.
    """
    # Access shared context if needed
    calculation_count = ctx.context.get("calculations", 0)
    ctx.context.set("calculations", calculation_count + 1)

    # Perform the calculation
    result = eval(args.expression)
    return f"Result: {result}"

All parameters of the function tool, except for ctx, are treated as input parameters and included in the tool’s schema.For example, in the tool above, the input model CalculatorArgs is passed as the args parameter, so the input JSON would look like:

{"args": {"expression": "input_expression"}}

args is an example name, you can name your input parameters however you like, and you may define more than one input parameter if needed.

This example mentions tool context, which can be used as a shared storage for all agents and tools. For more info on agent context, refer to this page

Test the Tool

Test your tool function independently.

if __name__ == "__main__":
    import asyncio
    import json

    async def test_tool():
        ctx = MasterContext(user_context={"calculations": 1}, thread_manager=None, agents={})
        run_ctx = RunContextWrapper(context=ctx)

        args = CalculatorArgs(expression="2 + 2 * 3")
        # Wrap in args to comply with oai expected inputs
        args_json = {"args": args.model_dump()}

        result = await calculator_tool.on_invoke_tool(run_ctx, json.dumps(args_json))
        print(result)

    asyncio.run(test_tool())

Add Tool to Agent

Pass the function directly to the agent’s tools list.

from agency_swarm import Agent

agent = Agent(
    name="MathAgent",
    instructions="You are a helpful math assistant",
    tools=[calculator_tool],  # Pass function directly
    model="gpt-5.4-mini"
)

Full Code Example

# calculator_tool.py
from agency_swarm import function_tool, RunContextWrapper
from pydantic import BaseModel, Field, field_validator
from agency_swarm import MasterContext

class CalculatorArgs(BaseModel):
    expression: str = Field(..., description="The mathematical expression to evaluate")

    @field_validator("expression")
    @classmethod
    def validate_expression(cls, v):
        if "/0" in v:
            raise ValueError("Division by zero is not permitted")
        return v

@function_tool
async def calculator_tool(ctx: RunContextWrapper[MasterContext], args: CalculatorArgs) -> str:
    """
    A calculator tool that evaluates mathematical expressions.
    Use this when you need to perform mathematical calculations.
    """
    # Access shared context if needed
    calculation_count = ctx.context.get("calculations", 0)
    ctx.context.set("calculations", calculation_count + 1)

    # Perform the calculation
    result = eval(args.expression)
    return f"Result: {result} (Calculation #{calculation_count + 1})"

if __name__ == "__main__":
    import asyncio
    import json

    async def test_tool():
        ctx = MasterContext(user_context={"calculations": 1}, thread_manager=None, agents={})
        run_ctx = RunContextWrapper(context=ctx)
        args = CalculatorArgs(expression="2 + 2 * 3")
        args_json = {"args": args.model_dump()}
        result = await calculator_tool.on_invoke_tool(run_ctx, json.dumps(args_json))
        print(result)

    asyncio.run(test_tool())

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Step-by-Step Guide

Step-by-step Guide

Full Code Example

Step-by-step Guide

Full Code Example

Next Steps

​Step-by-step Guide

​Full Code Example

​Step-by-step Guide

​Full Code Example

​Next Steps

Step-by-step Guide

Full Code Example

Step-by-step Guide

Full Code Example

Next Steps