Tools
tool.New, RawTool, Toolset, RunContext, and duplicate-call policy.
The tool package defines typed function tools, raw/dynamic tools, and toolsets.
Schemas for typed tools are derived from the Go input type by reflection and
cached — deterministic, so safe to snapshot.
Typed tools
type Handler[I, O any] func(context.Context, *RunContext, *I) (*O, error)
func New[I, O any](name string, handler Handler[I, O], opts ...Option) (*Tool[I, O], error)I becomes the parameter schema; O is JSON-encoded as the result. Options:
| Option | Effect |
|---|---|
WithDescription(string) | Model-visible tool description. |
WithSchema(Schema) | Override the reflected parameter schema. |
WithFlags(Flag) | Execution hints (FlagIgnoreOnEnter, FlagCancellable). |
WithDuplicateMode(DuplicateMode) | Duplicate-call policy (below). |
Struct-tag schema
Fields map to parameters via struct tags:
| Tag | Meaning |
|---|---|
json:"name,omitempty" | Parameter name; omitempty makes it optional. |
description:"..." | Parameter description. |
enum:"a|b|c" | Allowed values. |
min / max | Numeric bounds (or string length). |
format / pattern | String format / regex. |
title | JSON Schema title. |
type Input struct {
City string `json:"city" description:"city name" min:"1"`
Units string `json:"units,omitempty" enum:"celsius|fahrenheit"`
}Duplicate-call policy
const (
DuplicateAllow DuplicateMode = "allow" // default
DuplicateReject DuplicateMode = "reject"
DuplicateConfirm DuplicateMode = "confirm" // injects a confirm parameter
)RunContext
The handler's *tool.RunContext is its handle on the live turn:
func (r *RunContext) WaitForPlayout(ctx context.Context) error
func (r *RunContext) DisallowInterruptions() errorPlus Session and UserData accessors and ToolCallID. For handoff /
takeover, use the typed helpers rather than the raw callbacks:
agents.RequestHandoff(run, target, returns) and agents.RunTask(ctx, run, task).
WaitForPlayout blocks the turn until this step's audio finishes. Use it only
for "say it, then act" ordering.
Toolsets & raw tools
func NewToolset(opts ToolsetOptions) (*BasicToolset, error)
func NewToolProxyToolset(opts ToolProxyOptions) (*ToolProxyToolset, error)
func NewToolSearchToolset(opts ToolSearchOptions) (*ToolSearchToolset, error)A Toolset provides tools that can change at runtime and share lifecycle. Built
in: tool proxy (forwards to externally-resolved tools, e.g. MCP) and tool
search (exposes a large catalogue behind a search step). For a single dynamic
tool with an explicit (non-reflected) schema, use tool.RawTool.
Entry is the interface a single tool satisfies; AgentOptions.Tools /
AgentSessionOptions.Tools accept an Entry, []tool.Entry, a Toolset, or a
*tool.Context.
Related
- Tools — the guide with worked examples.