Sycophant.Tool (sycophant v0.4.2)

Defines a tool that can be provided to an LLM.

Tools describe callable functions that the LLM can invoke during generation. Parameters are defined as a Zoi schema, which wire protocol adapters convert to provider-specific JSON Schema.

Auto-execution

When function is set, Sycophant automatically executes the tool when the LLM returns a tool call, feeds the result back, and continues the loop (up to :max_steps iterations). When function is nil, tool calls are returned in response.tool_calls for manual handling.

Examples

# Zoi-defined tool (receives atom keys after validation)
weather_tool = %Sycophant.Tool{
  name: "get_weather",
  description: "Get current weather for a city",
  parameters: Zoi.object(%{city: Zoi.string()}),
  function: fn %{city: city} -> "72F and sunny in #{city}" end
}

# JSON Schema-defined tool (receives string keys)
search_tool = %Sycophant.Tool{
  name: "search",
  description: "Search the web",
  parameters: %{
    "type" => "object",
    "properties" => %{"query" => %{"type" => "string"}},
    "required" => ["query"]
  },
  function: fn %{"query" => q} -> "Results for #{q}" end
}

{:ok, response} = Sycophant.generate_text("openai:gpt-4o-mini", messages,
  tools: [weather_tool, search_tool]
)

Summary

Types

t()

Functions

from_map(data)

Reconstructs a Tool struct from a serialized map.

Types

t()

@type t() :: %Sycophant.Tool{
  description: String.t(),
  function: (map() -> String.t()) | nil,
  name: String.t(),
  parameters: Zoi.schema() | map(),
  resolved_schema: Sycophant.Schema.NormalizedSchema.t() | nil,
  schema_source: :zoi | :json_schema | nil,
  strict: boolean()
}

Functions

from_map(data)

@spec from_map(map()) :: t()

Reconstructs a Tool struct from a serialized map.