Skip to main content

Tools

Tools are the building blocks of the Arklex framework, providing functionality for various operations such as intent detection, slot filling, and task execution.

Overview​

Tools in the Arklex framework are designed to be modular and reusable components that can be combined to create complex workflows. Each tool has a well-defined interface for input and output. Powered through the slot filling mechanism, the framework handles the translation between MessageState and the specified parameter and return values, allowing smoother development of custom methods and integration of API.

Tool Structure​

Each tool in the Arklex framework follows a standard structure:

from arklex.env.tools.tools import BaseTool
from arklex.utils.graph_state import MessageState
from arklex.utils.slot import Slot

class MyTool(BaseTool):
    def __init__(self):
        super().__init__(
            name="my_tool",
            description="Description of my tool"
        )

    def _get_required_slots(self) -> List[Slot]:
        return [
            Slot(
                name="param1",
                description="Description of parameter 1",
                required=True,
                type="string"
            ),
            Slot(
                name="param2",
                description="Description of parameter 2",
                required=False,
                type="integer"
            )
        ]

    def _execute_impl(self, message_state: MessageState) -> Any:
        # Tool implementation
        return result

Slot Definition​

Slots are used to define the parameters that a tool requires. Each slot has the following attributes:

  • name: The name of the parameter
  • type: The type of the parameter (string, integer, float, boolean)
  • required: Whether the parameter is required
  • enum: The candidate values for the slot. This is used to aid the slot filler to check if the extracted value is valid.
  • description: A string describing the parameter. This will be used to aid the extraction component of slot filling. Adding examples often help the slot filling.

Tool Registration​

Tools can be registered using the @tool decorator:

from arklex.env.tools.tools import tool

@tool(name="my_tool", description="Description of my tool")
def my_tool(param1: str, param2: int = 0) -> str:
    # Tool implementation
    return result

Tool Execution​

Tools are executed through the environment:

from arklex.env.env import Environment

# Initialize environment
env = Environment(workers=[], tools=[my_tool])

# Execute tool
result = env.execute_tool("my_tool", message_state)

Best Practices​

  1. Tool Design

    • Keep tools focused and single-purpose
    • Use clear parameter names
    • Provide detailed descriptions
    • Handle errors gracefully

  2. Slot Definition

    • Use clear slot names
    • Provide detailed descriptions
    • Include examples when helpful
    • Define appropriate types

  3. Error Handling

    • Validate input parameters
    • Handle edge cases
    • Provide clear error messages
    • Log errors appropriately

  4. Testing

    • Write unit tests
    • Test edge cases
    • Test error handling
    • Test integration

Integration​

Tools integrate with:

  • Environment
  • Message Processing
  • Slot Filling
  • State Management
  • Logging System