View Source SwarmEx.Tool behaviour (SwarmEx v0.1.0)

Defines the behavior and functionality for agent tools.

Tools are capabilities that agents can use to perform specific tasks. Each tool must implement this behavior to be usable within the SwarmEx system.

Tool Configuration

Tools can be configured with the following options:

  • :timeout - Maximum time in milliseconds to wait for tool execution (default: 5000)
  • :retries - Number of retry attempts for failed executions (default: 3)
  • :validate_args - Whether to validate arguments before execution (default: true)

Example

defmodule MyTool do
  @behaviour SwarmEx.Tool

  @impl true
  def execute(args) do
    # Perform tool operation
    {:ok, result}
  end

  @impl true
  def validate(args) do
    # Validate incoming arguments
    :ok
  end

  @impl true
  def cleanup(args) do
    # Cleanup any resources
    :ok
  end
end

Summary

Functions

Safely executes a tool with the given arguments and options.

Retrieves the configuration for a registered tool.

Registers a tool configuration in the runtime. This allows for dynamic tool configuration and validation.

Validates that a module implements the Tool behavior correctly.

Types

@type args() :: term()
@type cleanup_result() :: :ok | {:error, term()}
@type options() :: [
  timeout: non_neg_integer(),
  retries: non_neg_integer(),
  validate_args: boolean()
]
@type result() :: {:ok, term()} | {:error, term()}
@type t() :: module()
@type validation_result() :: :ok | {:error, term()}

Callbacks

@callback cleanup(args()) :: cleanup_result()
@callback execute(args()) :: result()
@callback validate(args()) :: validation_result()

Functions

Link to this function

execute(tool, args, opts \\ [])

View Source
@spec execute(t(), args(), options()) :: result()

Safely executes a tool with the given arguments and options.

Options

  • :timeout - Maximum time in milliseconds to wait (default: 5000)
  • :retries - Number of retry attempts (default: 3)
  • :validate_args - Whether to validate arguments (default: true)

Examples

iex> SwarmEx.Tool.execute(MyTool, args, timeout: 10_000)
{:ok, result}

iex> SwarmEx.Tool.execute(InvalidTool, bad_args)
{:error, :validation_failed}
@spec get_config(t()) :: {:ok, keyword()} | {:error, term()}

Retrieves the configuration for a registered tool.

Examples

iex> SwarmEx.Tool.get_config(MyTool)
{:ok, [max_retries: 5]}

iex> SwarmEx.Tool.get_config(UnregisteredTool)
{:error, :not_registered}
Link to this function

register(tool, config \\ [])

View Source
@spec register(
  t(),
  keyword()
) :: :ok | {:error, term()}

Registers a tool configuration in the runtime. This allows for dynamic tool configuration and validation.

Examples

iex> SwarmEx.Tool.register(MyTool, max_retries: 5)
:ok
@spec validate_tool(t()) :: :ok | {:error, term()}

Validates that a module implements the Tool behavior correctly.

Returns :ok if the tool is valid, {:error, reason} otherwise.

Examples

iex> SwarmEx.Tool.validate_tool(MyTool)
:ok

iex> SwarmEx.Tool.validate_tool(InvalidModule)
{:error, :invalid_tool}