Creating a Toolkit

Generate a toolkit template

Run the following command to start creating your toolkit:

uv tool run --from arcade-ai arcade new arithmetic

Enter the optional information when prompted:

• Description: Provide a brief explanation of what your toolkit will do
• Author GitHub username and email: Your contact information
• Generate test and evaluation directories: Whether you want additional directories created for you

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

arithmetic/
├── arcade_arithmetic/       # Core package directory
│   ├── __init__.py
│   └── tools/               # Directory for your tools
│       ├── __init__.py
│       └── hello.py         # Example tool
├── evals/                   # Evaluation directory
│   └── eval_arithmetic.py   # Example evaluation file
├── tests/                   # Test directory
│   ├── __init__.py
│   └── test_arithmetic.py   # Example test file
├── pyproject.toml           # uv project configuration
├── README.md
└── Makefile                 # uv helper commands

Navigate to your toolkit directory:

cd arithmetic

Set up the development environment

An active virtual environment for your shell(s) is required to run the local development commands.

uv venv --seed -p 3.13

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 uv
• bump-version - Bump the version in the pyproject.toml file by a patch version
• check - Run code quality tools
• clean-build - Clean build artifacts
• coverage - Generate coverage report
• install - Install the uv environment and install all packages with dependencies
• install-local - Install Arcade components (CLI, TDK, etc.) from source in editable mode. Only use this when you are developing against the latest unreleased code from the arcade-ai repo main branch instead of the published packages
• test - Test the code with pytest

Define your tools

Create a Python file for your tools in the arcade_arithmetic/tools directory.

The following example shows a simple math toolkit with three tools: add, subtract, and multiply:

# arcade_arithmetic/tools/operations.py
from typing import Annotated
 
from arcade_tdk 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 arcade_arithmetic.tools.operations import add, multiply, subtract
 
__all__ = ["add", "multiply", "subtract"]

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

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, multiply, subtract
 
 
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 your tools locally

Serve your toolkit locally with the Arcade CLI:

arcade serve

You can use the --reload flag to automatically reload the server when you make changes to your toolkit:

arcade serve --reload

Visit http://localhost:8002/worker/health to see that your worker is running.

Connect your toolkit to the Arcade Engine

In another terminal, use a service like ngrok, tailscale, or cloudflare to give your local worker a public URL.

ngrok http 8002

tailscale funnel 8002

cloudflared tunnel --url http://localhost:8002

Then in your Arcade dashboard:

1. Navigate to the Workers page.
2. Click Add Worker.
3. Fill in the form with the following values:
   • ID: my-arithmetic-worker
   • Worker Type: Arcade
   • URL: your public URL from ngrok, tailscale, or cloudflare
   • Secret: dev
   • Timeout and Retry: can be left at default values
4. Click Create.

Now, in the Playground, you can see your tools in action.

Deploy your toolkit to the Arcade Engine

Alternatively, you can deploy your toolkit to Arcade’s cloud instead of tunneling to it locally.

Find the worker.toml file in your toolkit’s root directory (where you ran uv tool run --from arcade-ai arcade new arithmetic):

[[worker]]
 
[worker.config]
id = "demo-worker"  # Choose a unique ID
enabled = true
timeout = 30
retries = 3
secret = "<your-secret>"  # This is randomly generated for you by `uv tool run --from arcade-ai arcade new arithmetic`
[worker.local_source]
packages = ["./arithmetic"]  # Path to your toolkit directory

See Configuring Arcade Deploy for more configuration options.

From the root of your toolkit, deploy your toolkit to Arcade’s cloud with:

This may take a while your first time.

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

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

Build your package:

make build

Publish to PyPI:

uv publish --token YOUR_PYPI_TOKEN_HERE