This article will guide you step by step through how to build a custom tool & add your tool to the SuperAGI. Using an example provided in a sample repository.

Step 1: Installing SuperAGI Dependencies

Begin with installing all the dependencies, and make sure you have Python installed on your system. After you’ve done this, run pip install superagi-tools to get the SuperAGI BaseToolkitand BaseToolclasses.

Step 2: Creating a New Python File

Create a new Python file (for example,, which will define your tool class. Import all the necessary dependencies required to build your own custom tool using the following commands:

from import BaseTool
from pydantic import BaseModel, Field
from typing import Type

Step 3: Defining the Input Model

Next, create a Pydantic BaseModel class. This class will define the input schema for your tool. You’ll need to specify the fields and their types, as shown below:

class MyToolInput(BaseModel):
message: str = Field(..., description="Message to be processed by the tool")

Step 4: Defining Your Tool Class

Now, you can create a class that inherits from BaseTool.

You’ll need to set required attributes such as name, args_schema, and description. Moreover, you need to implement the _execute method, which contains the logic for your tool. This method takes the input parameters as arguments and returns the tool’s output.

Here’s an example:

class MyTool(BaseTool):
name: str = "My Tool"
args_schema: Type[BaseModel] = MyToolInput
description: str = "Description of my tool"

def _execute(self, message: str = None):
# Tool logic goes here

Step 5: Creating a Toolkit File

Next, create another Python file (for instance, to define your toolkit class. Import the necessary dependencies as follows:

from import BaseToolkit, BaseTool
from typing import Type, List

Step 6: Defining Your Toolkit Class

This class should inherit from BaseToolkit and optionally from ABC if you want to make it abstract.

Set required attributes such as name and description. You should also implement the get_tools method, which returns a list of instances of your tool classes, and the get_env_keys method, which returns a list of environment variable keys required by your toolkit.

Below is an example:

class MyToolkit(BaseToolkit):
name: str = "My Toolkit"
description: str = "Description of my toolkit"

def get_tools(self) -> List[BaseTool]:
return [MyTool()]

def get_env_keys(self) -> List[str]:
return []

Step 7: Configuring the Environment

At this stage, create a configuration file (like config.yaml) to define any environment variables your toolkit or tool might require.


Step 8: Building Your Tool

Now implement the logic within your tool’s _execute method based on your requirements.

You can access the environment variables using the get_tool_config method inherited from BaseTool.

Step 9: Testing Your Tool

After you’ve built your tool, you need to write test cases to verify its functionality. This step ensures that your tool works as expected.

Step 10: Listing Your Tool Dependencies

If your tool requires additional dependencies, list them in a requirements.txt file. This way, anyone who uses your tool can easily install the necessary dependencies.

Step 11: Creating a GitHub Repository

Create a new GitHub Repository with your Toolkit’s name and upload all the files you’ve worked on so far.

Step 12: Linking Your GitHub Repository to SuperAGI

Start SuperAGI using docker-compose up --build. Add your GitHub repository link to SuperAGI’s front end by clicking on the “add custom tool” button at home or navigating to the toolkits section. Paste your toolkit repository and save changes.

The SuperAGI tool manager will take care of the installation of your tool along with its dependencies.

Step 13: Rebuilding SuperAGI

Re-build SuperAGI using Docker and start using your tools:

docker compose down
docker compose up --build

At this point, you should be able to configure your tool settings from the toolkit section and start using them during the agent provisioning.

This concludes our step-by-step guide to building your own custom tool in SuperAGI.

In case you face any challenges in building/adding your custom toolkit to SuperAGI, don’t hesitate to join our discord to work with the community to resolve the issues.