Agentix.Tool (Agentix v0.1.0)

Copy Markdown View Source

A tool definition: its schema, who executes it, and how it is gated.

Two orthogonal axes:

  • executor — who produces the result: :server (your code, dispatched in a monitored task), :human (elicitation — the answer is the result), :client (browser/socket execution), :provider (provider-hosted, resolves in-stream — never dispatched locally).
  • approval — :auto or :requires_approval (a two-phase gate). Legal only on :server and :client; gating :human is circular and :provider has no pre-exec suspend point, so both raise at definition time.

streaming? is a property (a tool emitting progress during its own execution), orthogonal to the executor. retention controls compaction eviction.

Schema pass-through

parameter_schema is handed verbatim to ReqLLM.Tool.new/1 (it already compiles NimbleOptions / JSON-Schema). Agentix never re-compiles or re-validates it. The %ReqLLM.Tool{} produced for the provider carries a never-invoked stub callback (__provider_stub__/1) — Agentix drives dispatch itself and never lets ReqLLM auto-execute a tool. %ReqLLM.Tool{} is never persisted (its compiled field is not JSON-serializable); tools are rebuilt from config on revival.

Summary

Types

approval()
executor()
t()

Functions

new(attrs)

Builds a tool from attrs. Raises ArgumentError on: an unknown key, an invalid executor/approval, a gated :human/:provider (illegal matrix), or a :server tool without a callback.

pending_kind(tool, arg2)

The renderer kind for the call's current pending phase: :approval when gated (the first suspension), else :elicitation for :human / :client_exec for :client.

to_reqllm(tools)

Builds the %ReqLLM.Tool{} list to hand the provider for schema/serialization. Each carries the never-invoked __provider_stub__/1 callback; the loop owns dispatch. :provider tools are included so the model can call them.

Types

approval()

@type approval() :: :auto | :requires_approval

executor()

@type executor() :: :server | :human | :client | :provider

t()

@type t() :: %Agentix.Tool{
  approval: approval(),
  callback: (map(), Agentix.Turn.t() -> {:ok, term()} | {:error, term()}) | nil,
  description: String.t(),
  executor: executor(),
  name: String.t(),
  parameter_schema: keyword() | map(),
  retention: map() | nil,
  streaming?: boolean()
}

Functions

new(attrs)

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

Builds a tool from attrs. Raises ArgumentError on: an unknown key, an invalid executor/approval, a gated :human/:provider (illegal matrix), or a :server tool without a callback.

pending_kind(tool, arg2)

@spec pending_kind(t(), :approval | :exec) :: :approval | :elicitation | :client_exec

The renderer kind for the call's current pending phase: :approval when gated (the first suspension), else :elicitation for :human / :client_exec for :client.

to_reqllm(tools)

@spec to_reqllm([t()]) :: [ReqLLM.Tool.t()]

Builds the %ReqLLM.Tool{} list to hand the provider for schema/serialization. Each carries the never-invoked __provider_stub__/1 callback; the loop owns dispatch. :provider tools are included so the model can call them.