Creating a Toolkit

This guide walks you through the complete process of creating a custom toolkit for Arcade - from initial setup to publishing on PyPI. You’ll build a simple arithmetic toolkit with operations like addition, subtraction, and multiplication.

Prerequisites

Before starting, make sure you have:

Python 3.10 or higher (verify with python --version)
An Arcade account
Arcade CLI installed: pip install arcade-ai
Poetry for package management (the generated Makefile uses Poetry)

Generate a toolkit template

Run the following command to start creating your toolkit:

arcade new

Enter the required information when prompted:

Toolkit name: Choose a descriptive name (e.g., “arithmetic”)
Description: Provide a brief explanation of your toolkit
Author name and email: Your contact information

After completion, a directory with your toolkit name will be created with the following structure:

arithmetic/
├── arcade_arithmetic/       # Core package directory
│   ├── __init__.py          # Package initialization
│   └── tools/               # Directory for your tools
│       └── __init__.py
├── tests/                   # Test directory
├── pyproject.toml           # Poetry project configuration
├── README.md                # Documentation
└── Makefile                 # Helper commands

Navigate to your toolkit directory:

cd <toolkit_name>

Set up the development environment

Install dependencies and pre-commit hooks:

make install

This installs all dependencies specified in pyproject.toml, pre-commit hooks for code quality, and your toolkit in development mode.

The Makefile provides several helpful commands:

build - Build wheel file using poetry
bump-version - Bump the version in pyproject.toml
check - Run code quality tools
clean-build - Clean build artifacts
coverage - Generate coverage report
install - Install the poetry environment and pre-commit hooks
test - Test the code with pytest

Define your tools

Create a Python file for your tools in the arcade_<toolkit_name>/tools directory:

# arcade_arithmetic/tools/operations.py
from typing import Annotated, List
from arcade.sdk import tool
 
@tool
def add(
    a: Annotated[int, "The first number"],
    b: Annotated[int, "The second number"]
) -> Annotated[int, "The sum of the two numbers"]:
    """
    Add two numbers together
 
    Examples:
        add(3, 4) -> 7
        add(-1, 5) -> 4
    """
    return a + b
 
@tool
def subtract(
    a: Annotated[int, "The first number"],
    b: Annotated[int, "The second number"]
) -> Annotated[int, "The difference of the two numbers"]:
    """
    Subtract the second number from the first
 
    Examples:
        subtract(10, 4) -> 6
        subtract(5, 7) -> -2
    """
    return a - b
 
@tool
def multiply(
    a: Annotated[int, "The first number"],
    b: Annotated[int, "The second number"]
) -> Annotated[int, "The product of the two numbers"]:
    """
    Multiply two numbers together
 
    Examples:
        multiply(3, 4) -> 12
        multiply(-2, 5) -> -10
    """
    return a * b

Update the package initialization files to expose your tools:

# arcade_arithmetic/tools/__init__.py
from .operations import add, subtract, multiply
 
__all__ = ["add", "subtract", "multiply"]

# arcade_arithmetic/__init__.py
from arcade_arithmetic.tools import add, subtract, multiply
 
__all__ = ["add", "subtract", "multiply"]

Test your toolkit

Write tests for your tools in the tests directory:

# tests/test_operations.py
import pytest
from arcade_arithmetic.tools.operations import add, subtract, multiply
 
def test_add():
    assert add(3, 4) == 7
    assert add(-1, 5) == 4
    assert add(0, 0) == 0
 
def test_subtract():
    assert subtract(10, 4) == 6
    assert subtract(5, 7) == -2
    assert subtract(0, 0) == 0
 
def test_multiply():
    assert multiply(3, 4) == 12
    assert multiply(-2, 5) == -10
    assert multiply(0, 5) == 0

Run the tests:

make test

Check code quality:

make check

Generate a coverage report (optional):

make coverage

Verify local installation

Your toolkit should already be installed locally from the make install command. Verify it’s properly registered:

arcade show --local

You should see your toolkit listed in the output.

Test with a local worker

Start a local worker to test your toolkit with the Arcade API:

arcade serve

Visit http://localhost:8002/docs to see your tools in the Swagger UI.

Deploy your toolkit to Arcade

Create a worker.toml file in your toolkit’s root directory:

[[worker]]
 
[worker.config]
id = "arithmetic-worker"  # Choose a unique ID
secret = "<your-secret>"  # Replace with a secure secret
 
[worker.local_source]
packages = ["."]  # Path to your toolkit directory

Deploy your worker to Arcade:

arcade deploy

Verify the deployment:

arcade worker list

Package and publish to PyPI

Clean any previous build artifacts:

make clean-build

If you’re updating an existing package, bump the version:

make bump-version

Update the project metadata in pyproject.toml:

[tool.poetry]
name = "arcade-arithmetic"
version = "0.1.0"
description = "Basic arithmetic operations toolkit for Arcade"
authors = ["Your Name <[email protected]>"]
readme = "README.md"
license = "MIT"
repository = "https://github.com/yourusername/arcade-arithmetic"

Create a comprehensive README.md file that explains your toolkit’s purpose, installation, and usage.

Build your package:

make build

Configure Poetry with your PyPI token (recommended for security):

poetry config pypi-token.pypi your-token-here

Publish to PyPI:

poetry publish

Or build and publish in one step:

poetry publish --build

Using your published toolkit

Now that your toolkit is published, you can use it in any Arcade application:

from arcadepy import Arcade
 
# Initialize the Arcade client
client = Arcade(base_url="https://api.arcade.dev")
 
# Create a chat completion that can use your tools
response = client.chat.completions.create(
    messages=[
        {"role": "system", "content": "You are a helpful assistant with arithmetic skills."},
        {"role": "user", "content": "Calculate 12 + 34 and then multiply by 2"}
    ],
    model="gpt-4o",
    tool_choice="generate",
)
 
print(response.choices[0].message.content)

Ongoing toolkit maintenance

As you continue to develop your toolkit, use these Makefile commands to maintain it:

make check - Run code quality checks before committing changes
make test - Run tests to ensure your changes don’t break existing functionality
make coverage - Monitor test coverage as you add new features
make bump-version - Update the version when releasing new changes
make build - Build new distribution packages
make clean-build - Clean up build artifacts when needed

Next steps

Add more tools: Expand your toolkit with more complex operations
Add authentication: Learn how to create tools with authentication
Evaluate your tools: Explore how to evaluate tool performance
Set up CI/CD: Automate testing and deployment with continuous integration

Quickstart Tool Context