Planck.Agent.Tool (Planck.Agent v0.1.0)

An executable tool for use in agent turns.

Extends Planck.AI.Tool with an execute_fn — the function called when the LLM requests a tool invocation. The AI tool schema (name, description, parameters) is extracted when building Planck.AI.Context; execute_fn stays agent-side.

Summary

Types

execute_fn()

The function invoked when the LLM requests this tool.

t()

A fully-specified tool: schema fields understood by the LLM plus the execute_fn that runs when the model calls it.

Functions

new(opts)

Build a Planck.Agent.Tool from keyword options.

to_ai_tool(tool)

Convert to a Planck.AI.Tool for use in Planck.AI.Context (drops execute_fn).

Types

execute_fn()

@type execute_fn() :: (agent_id :: String.t(), id :: String.t(), args :: map() ->
                   {:ok, String.t()} | {:error, String.t()})

The function invoked when the LLM requests this tool.

Receives the calling agent_id, the tool call id (an opaque string from the provider, used to correlate results), and args (the JSON-decoded arguments map). Must return {:ok, result} or {:error, reason} where both values are strings — they are placed directly into the model's context as tool result text. Exceptions and exit signals are caught by the agent and converted to error strings automatically.

t()

@type t() :: %Planck.Agent.Tool{
  description: String.t(),
  execute_fn: execute_fn(),
  name: String.t(),
  parameters: map()
}

A fully-specified tool: schema fields understood by the LLM plus the execute_fn that runs when the model calls it.

:name — identifier the model uses to call the tool; must be unique within an agent's tool set
:description — natural-language description sent to the model; quality here directly affects how reliably the model uses the tool
:parameters — JSON Schema object describing the accepted arguments
:execute_fn — the function called with the agent id, tool call id, and decoded args

Functions

new(opts)

@spec new(keyword()) :: t()

Build a Planck.Agent.Tool from keyword options.

Examples

iex> Tool.new(
...>   name: "read_file",
...>   description: "Read a file",
...>   parameters: %{"type" => "object", "properties" => %{"path" => %{"type" => "string"}}, "required" => ["path"]},
...>   execute_fn: fn _agent_id, _id, %{"path" => path} -> File.read(path) end
...> )
%Planck.Agent.Tool{name: "read_file", ...}

to_ai_tool(tool)

@spec to_ai_tool(t()) :: Planck.AI.Tool.t()

Convert to a Planck.AI.Tool for use in Planck.AI.Context (drops execute_fn).