LlmEx.Tools.ToolBehaviour behaviour (LlmEx v0.1.0)

View Source

Behaviour for LlmEx tools.

This module defines the behaviour for all tools in the LlmEx system. Tools can be stateful or stateless, and must implement the required callbacks.

Declarative Tool Definition

Tools can be defined using a declarative API similar to Phoenix.Component's attr macro:

defmodule MyTool do
  use LlmEx.Tools.ToolBehaviour

  tool_name "my_tool"
  tool_description "A simple tool that does something useful"

  param :action, :string, required: true,
                         enum: ["start", "stop", "pause"],
                         description: "The action to perform"
  param :amount, :integer, description: "The amount to process"

  # ... rest of implementation
end

State Management

Tools can maintain state between calls. The state is passed to the handle_call/2 callback and returned as part of the result. For example:

def handle_call(arguments, state) do
  # ... process arguments
  new_state = %{state | count: state.count + 1}
  {:ok, result, new_state}
end

Summary

Callbacks

Handles a call to the tool with the given arguments and current state.

Initializes the tool's state.

Returns the tool definition for the tools/list endpoint.

Callbacks

handle_call(map, map)

@callback handle_call(map(), map()) :: {:ok, map(), map()} | {:error, any()}

Handles a call to the tool with the given arguments and current state.

This function is called when a client requests the tool to be executed. It should process the arguments and return {:ok, result, new_state} where result is a map that will be returned to the client and new_state is the updated state of the tool.

Examples

def handle_call(arguments, state) do
  # Create a result object with text content
  result = %{
    "content" => [%{"type" => "text", "text" => "Example response"}],
    "isError" => false
  }
  {:ok, result, state}
end

init(map)

@callback init(map()) :: {:ok, term()} | {:error, term()}

Initializes the tool's state.

This function is called when the tool is first registered with the system. It should return {:ok, state} where state can be any term that represents the tool's initial state.

Examples

def init(_args) do
  {:ok, %{count: 0}}
end

tool_definition()

@callback tool_definition() :: map()

Returns the tool definition for the tools/list endpoint.

This function should return a map with the tool's name, description, and input schema.

Examples

def tool_definition do
  %{
    "name" => "echo",
    "description" => "Echoes back the input arguments",
    "inputSchema" => %{
      "type" => "object",
      "properties" => %{
        "message" => %{
          "type" => "string",
          "description" => "The message to echo"
        }
      },
      "required" => ["message"]
    }
  }
end