Behaviour for hosted (server-side) tool implementations.

Hosted tools execute inside the agentic loop without any client involvement. When the model calls a tool whose name is registered in config :open_responses, :hosted_tools, the loop dispatches it here, collects the result, and continues sampling — all transparently.

Implementing a tool

defmodule MyApp.Tools.TimeZone do
  @behaviour OpenResponses.Tool

  @impl OpenResponses.Tool
  def execute(%{"timezone" => tz}, _context) do
    case DateTime.now(tz) do
      {:ok, dt} -> {:ok, Calendar.strftime(dt, "%Y-%m-%d %H:%M:%S %Z")}
      {:error, _} -> {:error, "Unknown timezone: #{tz}"}
    end
  end
end

Registering a tool

config :open_responses, :hosted_tools, %{
  "get_time" => MyApp.Tools.TimeZone
}

The key is the tool name the model uses. See the Tool Dispatch guide.