Tools and dependencies¶
Purpose¶
Give the model executable capabilities whose execution receives a typed, application-owned dependency value.
When to use¶
Whenever the answer depends on state the model cannot know — a database handle, a tenant name, a logger — or an action the model cannot perform.
How it works¶
A tool.Tool[Deps] is a typed value: inspectable metadata (name,
description, JSON Schema) plus an Exec function receiving the caller's
context, the run's Deps value, and raw model-produced arguments.
Golem executes requested calls sequentially and appends every exchange —
the assistant's tool-call message and each tool result — to the result's
Messages in execution order.
Arguments are untrusted model output and stay raw JSON: decoding and validating them is the tool author's explicit job. Golem never uses reflection to infer schemas or arguments.
Parts and definitive failures¶
Exec returns a tool.Result — the result Text plus optional
Parts (model.Part, the same shape prompt parts use). Parts are
evidence the call produced: a screenshot, a fetched PDF. They are
stored on the tool message and ride the durable JSON, and each adapter
places them where its API carries them — inside the tool result on
Anthropic and Bedrock, framed onto one attributed user message on
OpenAI, Azure, and Gemini. An adapter that cannot carry a part kind
fails the run before any request; see the multimodal
guide for each adapter's kind matrix.
A failure the model should see — the resource doesn't exist, the
operation isn't supported — is a &tool.Failed{Reason}, not a plain
error: the reason becomes the tool's result on a message flagged
Failed, the model decides what to do next, and the run continues
without consuming the tool's retry budget. Returning
*model.ModelRetry instead asks the model to correct the call and
consume budget; any other error still aborts the run at the tool
stage.
Cancelling the run from a tool¶
A tool that must end the whole run — a policy veto, an exhausted
budget, a stop gesture forwarded through the dependencies — returns
&tool.Canceled{Reason}. The run stops deliberately, not as a
failure: Run reports RunError with StageCanceled (match the
sentinel with errors.As to read the reason), no retry budget is
touched, and the evidence stays on RunError.Partial. Inside the
batch, execution order governs: calls before the cancelling call keep
their recorded results, the cancelling call and everything after it
are closed with a synthesized no-result result, and later calls never
start. The transcript is provider-valid immediately, so
RunWithHistory resumes it without repair — see Resuming a failed
run. A tool
cannot be force-stopped once running — the group it runs in finishes,
and only work that had not started is prevented. A delegated sub-agent
that cancels cancels the delegating run the same way.
Per-step tool preparation¶
WithPrepareTools filters or rewrites the tool specs advertised to the
model before every request, including correction rounds. It is the
per-step counterpart to WithTools: registration stays static, while
advertisement can follow the caller's role, the step reached, or state
the tool calls left behind.
Preparation sees the specs after deferred-tool discovery has revealed tools from history, so it can hide a revealed tool on a later step without unregistering it. It may drop specs and rewrite a spec's description or schema, but it cannot add a callable tool: every returned name must already be advertised this turn, duplicate names are rejected, and every schema must be valid JSON. When tool-mode output is active the output tool must remain. A prepare error, or an invalid result, fails the run before the request is sent.
Output limits¶
Tool results persist in history, so an oversized result is re-sent on
every later request. WithToolOutputLimit(maxBytes) caps result text
once, when the tool returns: the model sees the head and tail plus a
marker naming the original size, and that reduced form is what persists
and what later requests re-send. Result parts are untouched.
agent, _ := golem.New[struct{}, string](client, decoder,
golem.WithTools[struct{}, string](readLog),
golem.WithToolOutputLimit[struct{}, string](400),
)
A tool can set tool.Tool.MaxOutputBytes to override the agent cap;
zero inherits it, and an unset agent cap disables truncation. The cap is
bytes, determined once, and cuts on UTF-8 boundaries.
When truncation loses too much, spill the full payload instead:
store := tool.NewMemorySpill() // or an application SpillStore
agent, _ := golem.New[struct{}, string](client, decoder,
golem.WithTools[struct{}, string](readLog),
golem.WithToolOutputSpill[struct{}, string](store, 4_000),
)
WithToolOutputSpill(store, threshold) stores text at or above the
threshold and replaces it with a marker naming the handle, total size,
and a short preview. The agent registers a read_tool_result tool so the
model can page the payload back with offset and limit; reads are
capped at tool.MaxSpillReadLimit. The read tool is exempt from the
policy, so reading a spill cannot spill again. A store write failure
falls back to WithToolOutputLimit.
To condense rather than preserve, use an application summarizer:
agent, _ := golem.New[struct{}, string](client, decoder,
golem.WithTools[struct{}, string](readLog),
golem.WithToolOutputSummary[struct{}, string](summarizeLog, 4_000),
)
WithToolOutputSummary(fn, threshold) calls fn synchronously with the
tool name and text; a nil or empty summary, or an error, falls back to
WithToolOutputLimit. Spill and summary modes are mutually exclusive.
Example¶
Run examples/tools:
OPENAI_API_KEY=sk-... go run ./examples/tools
type roster struct{ PlayerName string }
getPlayerName := tool.MustNew(tool.Tool[roster]{
Name: "get_player_name",
Description: "Get the player's name.",
Schema: json.RawMessage(`{"type":"object"}`),
Exec: func(ctx context.Context, deps roster, args json.RawMessage) (tool.Result, error) {
return tool.Text(deps.PlayerName), nil
},
})
agent, _ := golem.New[roster, string](client, decoder,
golem.WithTools[roster, string](getPlayerName),
)
result, _ := agent.Run(ctx, golem.RunContext[roster]{Deps: roster{PlayerName: "Anne"}}, "who wins?")
examples/tool-output-limit runs offline and shows a 9 KB log reduced to
its head and tail:
golem.WithToolOutputLimit[struct{}, string](400)
examples/tool-output-spill runs offline, spills a 28 KB log, and reads
it back through read_tool_result:
golem.WithToolOutputSpill[struct{}, string](tool.NewMemorySpill(), 200)
examples/tool-preparation runs offline and hides a destructive tool from
a non-admin caller:
agent, _ := golem.New[actor, string](client, decoder,
golem.WithTools[actor, string](readFile, deleteFile),
golem.WithPrepareTools[actor, string](func(_ context.Context, runCtx golem.RunContext[actor], specs []model.ToolSpec) ([]model.ToolSpec, error) {
if runCtx.Deps.Role == "admin" {
return specs, nil
}
return keep(specs, "read_file"), nil
}),
)
API surface¶
tool.New(tool.Tool[Deps]) (Tool[Deps], error)andtool.MustNew— reject missing names, invalid schema JSON, nil Exec, and duplicate names at registration.golem.WithTools[Deps, Output](tools ...tool.Tool[Deps])golem.PrepareToolsFunc[Deps]andgolem.WithPrepareTools[Deps, Output](fn)— filter or rewrite the advertised specs per requestgolem.WithToolOutputLimit[Deps, Output](maxBytes int)— cap tool result text;tool.Tool.MaxOutputBytesoverrides itgolem.WithToolOutputSpill[Deps, Output](store tool.SpillStore, threshold int)— store full text and registerread_tool_resultgolem.WithToolOutputSummary[Deps, Output](fn golem.ToolOutputSummaryFunc, threshold int)— condense oversized textgolem.SpillReadToolName,golem.ToolOutputSummaryFunctool.SpillStore,tool.MemorySpill,tool.NewMemorySpill()— the lossless store port and offline implementationgolem.WithParallelToolCalls[Deps, Output]()enables concurrent calls in one model response;tool.Tool.Sequentialmakes one tool a barrier.golem.WithToolChoice[Deps, Output](name)advertises only the selected registered tool for runs where the application must constrain availability.tool.Tool[Deps]{Name, Description, Schema, Exec}—Execreturns(tool.Result, error).tool.Result{Text, Parts}andtool.Text(s)— the result shape and the text-only helper.&tool.Failed{Reason}— a definitive failure recorded as the tool's result; the retry budget is untouched.&tool.Canceled{Reason}— a deliberate stop: the run ends at the cancellation stage with evidence onRunError.Partial.
Gotchas¶
Execmust honorctxand return errors rather than logging them.- Tool failures abort the run at the
toolstage unless they wrapmodel.ModelRetry(correction; see Self-correction), are a*tool.Failed(definitive; recorded as the result, budget untouched), or are a*tool.Canceled(deliberate stop; ends the run at thecanceledstage). - Tool metadata must be inspectable without executing the tool.
- Prepared specs cannot add a callable tool, duplicate a name, or drop the
active output tool; the run fails before the request instead of sending
a request the loop cannot dispatch. See
docs/adr/0045-per-step-tool-preparation.md. - The output cap keeps only text; a tool that returns an image or
document part keeps the full part even when its text is truncated. See
docs/adr/0050-tool-output-limits.md. - Spill takes precedence over truncation when the store accepts the write; the marker is not itself truncated. Summaries run synchronously inside the tool loop, so a slow summarizer delays the run.
read_tool_resultis reserved while spill is enabled. A registered tool with that name failsNew. Seedocs/adr/0054-tool-output-spill.md.- Preparation runs after deferred-tool discovery, so removing the
runner-owned
search_toolsspec disables discovery for that request; the deferred tools stay declared but unreachable. - Any tool that can return
*tool.Canceledholds the authority to end the run; read a tool returning it as part of that tool's contract.