{"id":6995,"library":"arcade-tdk","title":"Arcade TDK","description":"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.","status":"active","version":"3.6.1","language":"en","source_language":"en","source_url":"https://github.com/ArcadeAI/arcade-ai","tags":["ai-agents","tool-calling","toolkit","llm","developer-tools","api-integration"],"install":[{"cmd":"pip install arcade-tdk","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The 'arcade' library is for game development, not the Arcade AI Platform TDK.","wrong":"from arcade.tool import tool","symbol":"tool","correct":"from arcade_tdk.tool import tool"},{"note":"Used for accessing runtime information and secrets within a tool.","symbol":"ToolContext","correct":"from arcade_tdk.tool import ToolContext"},{"note":"Indicates a tool execution failure to the LLM and developer.","symbol":"ToolExecutionError","correct":"from arcade_tdk.errors import ToolExecutionError"},{"note":"Indicates a transient tool execution failure, suggesting the LLM should retry.","symbol":"RetryableToolError","correct":"from arcade_tdk.errors import RetryableToolError"}],"quickstart":{"code":"from arcade_tdk.tool import tool, ToolContext\nfrom typing import Annotated\n\n@tool(\n    description=\"Adds two numbers together.\"\n)\ndef add_numbers(\n    first_number: Annotated[float, \"The first number to add.\"],\n    second_number: Annotated[float, \"The second number to add.\"],\n    context: ToolContext # Required for Arcade platform functionality\n) -> Annotated[float, \"The sum of the two numbers.\"]:\n    \"\"\"Adds two numbers together.\"\"\"\n    print(f\"Adding {first_number} and {second_number} for user {context.user_id}\")\n    return first_number + second_number\n\n# In a real application, this tool would be served via an MCP server \n# and consumed by an AI agent using the `arcadepy` client.\n# For example, an agent might call:\n# client.tools.execute('my_toolkit.add_numbers', first_number=5, second_number=3, user_id='test_user')\n\n# Example of how you might verify the function signature (not executed at runtime by TDK itself)\nif __name__ == \"__main__\":\n    # This part is for demonstration and would not typically be run directly for tool definition.\n    # The Arcade platform handles discovery and execution.\n    result = add_numbers(first_number=10, second_number=20, context=ToolContext(user_id='demo_user', tool_name='add_numbers'))\n    print(f\"Direct call result: {result}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you are installing `arcade-tdk` for AI tool development and `arcade` for game development, and use the correct import statements for each.","message":"Do not confuse `arcade-tdk` with the `arcade` game development library. They are entirely separate projects with different purposes and import paths.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions (especially major/minor increments)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install arcade-tdk` to install the library. If using a virtual environment, ensure it is activated.","cause":"The `arcade-tdk` package is not installed or the virtual environment is not active.","error":"ModuleNotFoundError: No module named 'arcade_tdk'"},{"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.","cause":"Incorrect casing or `tool` is not directly exposed at that path, or a version mismatch where the import path changed.","error":"from arcade_tdk.tool import tool\nImportError: cannot import name 'tool' from 'arcade_tdk.tool'"},{"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.","cause":"Attempting to pass ToolContext as a regular argument or iterating over it when it's meant to be an object for attribute access.","error":"TypeError: 'ToolContext' object is not iterable"}]}