Codex.FunctionTool (Codex SDK v0.16.1)

Copy Markdown View Source

Convenience macro for defining function-backed tools with JSON schemas.

Usage:

defmodule MyTool do
  use Codex.FunctionTool,
    name: "add",
    description: "Adds numbers",
    parameters: %{left: :number, right: :number},
    handler: fn %{"left" => left, "right" => right}, _ctx ->
      {:ok, %{"sum" => left + right}}
    end
end

Options:

  • :name - tool name (defaults to module name)
  • :description - human-friendly description
  • :parameters - map of parameter names to type atoms or schema maps
  • :required - list of required parameter names (defaults to all)
  • :schema - explicit JSON schema (overrides generated schema)
  • :strict? - when true sets "additionalProperties": false (default)
  • :handler - function to invoke (falls back to handle/2 or handle/1)
  • :enabled? - predicate to gate invocation (arity 1 or 2)
  • :on_error - fallback handler invoked with the error (arity 2 or 3)

Summary

Functions

Constructs metadata map used for tool registration.

Builds a JSON schema map from a parameter definition.

Executes the configured handler with normalized arguments.

Types

opts()

@type opts() :: map() | keyword()

Functions

build_metadata(opts)

@spec build_metadata(opts()) :: map()

Constructs metadata map used for tool registration.

build_schema(parameters, opts \\ [])

@spec build_schema(map(), keyword() | map()) :: map()

Builds a JSON schema map from a parameter definition.

execute(module, opts, args, context)

@spec execute(module(), map(), map() | list() | String.t() | nil, map()) ::
  {:ok, term()} | {:error, term()}

Executes the configured handler with normalized arguments.