Nous.Tool (nous v0.13.3)

Tool definition for agent function calling.

A tool represents a function that an AI agent can call to retrieve information or perform actions. Tools are automatically converted to OpenAI function calling schemas.

Example

defmodule MyTools do
  @doc "Search the database for users"
  def search_users(ctx, query) do
    ctx.deps.database
    |> Database.search(query)
    |> format_results()
  end
end

# Create tool from function
tool = Tool.from_function(&MyTools.search_users/2,
  name: "search_users",
  description: "Search for users in the database"
)

# Convert to OpenAI schema
schema = Tool.to_openai_schema(tool)

Summary

Types

category()

t()

Functions

from_function(fun, opts \\ [])

Create a tool from a function.

from_module(module, opts \\ [])

Create a tool from a module implementing Nous.Tool.Behaviour.

to_openai_schema(tool)

Convert tool to OpenAI function calling schema.

Types

category()

@type category() :: :read | :write | :execute | :communicate | :search | nil

t()

@type t() :: %Nous.Tool{
  category: category(),
  description: String.t(),
  function: function(),
  module: module() | nil,
  name: String.t(),
  parameters: map(),
  requires_approval: boolean(),
  retries: non_neg_integer(),
  tags: [atom()],
  takes_ctx: boolean(),
  timeout: non_neg_integer() | nil,
  validate_args: boolean()
}

Functions

from_function(fun, opts \\ [])

@spec from_function(
  function(),
  keyword()
) :: t()

Create a tool from a function.

Automatically extracts function metadata including documentation and generates a JSON schema for the parameters.

Options

:name - Custom tool name (default: function name)
:description - Custom description (default: from @doc)
:parameters - Custom parameter schema (default: auto-generated)
:retries - Number of retries on failure (default: 1)
:timeout - Timeout in milliseconds (default: 30000)
:validate_args - Whether to validate arguments against schema (default: true)
:requires_approval - Whether tool needs human approval before execution (default: false)
:category - Tool category: :read, :write, :execute, :communicate, :search, or nil
:tags - Arbitrary tags for filtering (default: [])

Examples

# Simple tool
tool = Tool.from_function(&MyTools.calculate/2)

# With custom options
tool = Tool.from_function(&MyTools.search/2,
  name: "search_database",
  description: "Search for records",
  retries: 3,
  timeout: 60_000
)

from_module(module, opts \\ [])

@spec from_module(
  module(),
  keyword()
) :: t()

Create a tool from a module implementing Nous.Tool.Behaviour.

Module-based tools are easier to test because dependencies can be injected through the context.

Options

:name - Override tool name from metadata
:description - Override description from metadata
:parameters - Override parameters from metadata
:retries - Number of retries on failure (default: 1)
:timeout - Timeout in milliseconds (default: 30000)
:validate_args - Whether to validate arguments (default: true)
:requires_approval - Whether tool needs human approval before execution (default: false)
:category - Override category from metadata
:tags - Override tags from metadata

Example

defmodule MyApp.Tools.Search do
  @behaviour Nous.Tool.Behaviour

  @impl true
  def metadata do
    %{
      name: "search",
      description: "Search the web",
      parameters: %{
        "type" => "object",
        "properties" => %{
          "query" => %{"type" => "string"}
        },
        "required" => ["query"]
      }
    }
  end

  @impl true
  def execute(ctx, %{"query" => query}) do
    http = ctx.deps[:http_client] || MyApp.HTTP
    {:ok, http.search(query)}
  end
end

# Create tool from module
tool = Tool.from_module(MyApp.Tools.Search)

# Override options
tool = Tool.from_module(MyApp.Tools.Search, timeout: 60_000, retries: 3)

to_openai_schema(tool)

@spec to_openai_schema(t()) :: map()

Convert tool to OpenAI function calling schema.

Example

schema = Tool.to_openai_schema(tool)
# %{
#   "type" => "function",
#   "function" => %{
#     "name" => "search_users",
#     "description" => "Search for users",
#     "parameters" => %{...}
#   }
# }