Arcade TDK

3.6.1 · active · verified Thu Apr 16

Arcade TDK (Toolkit Development Kit) is a Python library designed for defining and building custom tools for AI agents within the Arcade AI Platform. It provides decorators and utilities to easily expose Python functions as agent-callable tools, handling aspects like input/output schemas and execution context. The library maintains an active release cadence, with updates appearing every few weeks or months as part of the broader Arcade AI ecosystem.

Common errors

```
ModuleNotFoundError: No module named 'arcade_tdk'
```
cause The `arcade-tdk` package is not installed or the virtual environment is not active.

fix Run `pip install arcade-tdk` to install the library. If using a virtual environment, ensure it is activated.
```
from arcade_tdk.tool import tool
ImportError: cannot import name 'tool' from 'arcade_tdk.tool'
```
cause Incorrect casing or `tool` is not directly exposed at that path, or a version mismatch where the import path changed.

fix Verify the exact import path from official documentation or recent examples. As of 3.6.1, `from arcade_tdk.tool import tool` is correct. If the error persists, check for breaking changes in newer versions of the library.
```
TypeError: 'ToolContext' object is not iterable
```
cause Attempting to pass ToolContext as a regular argument or iterating over it when it's meant to be an object for attribute access.

fix Ensure `ToolContext` is used as a parameter for accessing properties like `context.user_id` or `context.tool_name`, not as an iterable. It is intended to be passed by the Arcade runtime.

Warnings

gotcha Do not confuse `arcade-tdk` with the `arcade` game development library. They are entirely separate projects with different purposes and import paths.
Fix: Ensure you are installing `arcade-tdk` for AI tool development and `arcade` for game development, and use the correct import statements for each.
gotcha `arcade-tdk` is for *defining* tools, but an `arcadepy` (or `arcade` client) library is typically used by AI agents to *interact with and execute* these tools via the Arcade AI Platform. You need both to have a full agent-tool ecosystem.
Fix: When building an AI agent that uses Arcade tools, ensure you also install and use the `arcadepy` client library to connect to the Arcade platform and execute the tools you've defined with `arcade-tdk`.
breaking The Arcade AI Platform, including `arcade-tdk`, is under active development. While explicit breaking changes are not extensively documented in public search results, frequent updates suggest that API changes between minor versions are possible.
Fix: Always refer to the official Arcade AI documentation or GitHub releases for specific upgrade guides between versions. Pin your `arcade-tdk` version to avoid unexpected changes in production.

Install

pip install arcade-tdk Install stable version

Imports

tool
wrong:
```
from arcade.tool import tool
```
correct:
```
from arcade_tdk.tool import tool
```
The 'arcade' library is for game development, not the Arcade AI Platform TDK.
ToolContext
```
from arcade_tdk.tool import ToolContext
```
Used for accessing runtime information and secrets within a tool.
ToolExecutionError
```
from arcade_tdk.errors import ToolExecutionError
```
Indicates a tool execution failure to the LLM and developer.
RetryableToolError
```
from arcade_tdk.errors import RetryableToolError
```
Indicates a transient tool execution failure, suggesting the LLM should retry.

Quickstart

Defines a simple tool `add_numbers` using the `@tool` decorator. The function parameters are type-hinted and include a `ToolContext` for runtime information. This tool would then be hosted on an Arcade MCP server for consumption by AI agents.

from arcade_tdk.tool import tool, ToolContext
from typing import Annotated

@tool(
    description="Adds two numbers together."
)
def add_numbers(
    first_number: Annotated[float, "The first number to add."],
    second_number: Annotated[float, "The second number to add."],
    context: ToolContext # Required for Arcade platform functionality
) -> Annotated[float, "The sum of the two numbers."]:
    """Adds two numbers together."""
    print(f"Adding {first_number} and {second_number} for user {context.user_id}")
    return first_number + second_number

# In a real application, this tool would be served via an MCP server 
# and consumed by an AI agent using the `arcadepy` client.
# For example, an agent might call:
# client.tools.execute('my_toolkit.add_numbers', first_number=5, second_number=3, user_id='test_user')

# Example of how you might verify the function signature (not executed at runtime by TDK itself)
if __name__ == "__main__":
    # This part is for demonstration and would not typically be run directly for tool definition.
    # The Arcade platform handles discovery and execution.
    result = add_numbers(first_number=10, second_number=20, context=ToolContext(user_id='demo_user', tool_name='add_numbers'))
    print(f"Direct call result: {result}")

view raw JSON →