Creating a Toolkit

Generate a toolkit template

Run the following command to start creating your toolkit:

git init
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.

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.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, 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 arcade new):

[[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 `arcade new`
[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:

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 <your.email@example.com>"]
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