OpenAI.Agents.Tool behaviour (openai_agents v0.1.2)

Defines the behavior for tools that agents can use.

Tools are modules that implement specific functionality that agents can call during their execution.

Example

defmodule MyApp.Tools.GetWeather do
  use OpenAI.Agents.Tool

  @impl true
  def schema do
    %{
      name: "get_weather",
      description: "Get the current weather for a city",
      parameters: %{
        type: "object",
        properties: %{
          city: %{type: "string", description: "The city name"}
        },
        required: ["city"]
      }
    }
  end

  @impl true
  def execute(%{"city" => city}, context) do
    case WeatherAPI.get_weather(city) do
      {:ok, data} -> {:ok, data}
      {:error, reason} -> {:error, "Failed to get weather: #{reason}"}
    end
  end
end

Summary

Functions

Converts a tool module to the OpenAI tool schema format.

Validates a tool module has the required callbacks and schema structure.

Types

context()

@type context() :: any()

params()

@type params() :: map()

result()

@type result() :: {:ok, any()} | {:error, String.t()}

schema()

@type schema() :: %{name: String.t(), description: String.t(), parameters: map()}

Callbacks

execute(params, context)

@callback execute(params(), context()) :: result()

on_error(t, params, context)

(optional)
@callback on_error(Exception.t(), params(), context()) :: result()

schema()

@callback schema() :: schema()

Functions

to_openai_format(tool_module)

@spec to_openai_format(module()) :: map()

Converts a tool module to the OpenAI tool schema format.

validate_tool(tool_module)

@spec validate_tool(module()) :: :ok | {:error, String.t()}

Validates a tool module has the required callbacks and schema structure.