Typed function tools¶
agent.Func builds a tool from a Go function with a typed input, a typed output, and typed host dependencies.
agent.AIFunc builds a typed function that a model computes, and exposes it as a tool.
Func¶
type Inventory struct{ db *sql.DB }
type ReserveIn struct {
SKU string `json:"sku" description:"Product SKU"`
Quantity int `json:"quantity" description:"Units to reserve"`
Note string `json:"note,omitempty"`
}
reserve := agent.Func("reserve", "Reserve units of a SKU",
func(rc agent.RunContext[*Inventory], in ReserveIn) (Receipt, error) {
return reserveStock(rc, rc.Deps.db, in, rc.IdempotencyKey)
},
agent.Capability(types.ToolCapabilityWrite),
agent.Approval("Reserve stock"),
agent.Idempotent(),
)
a, err := agent.New(cfg, agent.WithDeps(&Inventory{db: db}))
if err != nil {
return err
}
| Behavior | Rule |
|---|---|
| Schema | Derived from In with types.SchemaFrom. json, description and enum tags apply. A field without omitempty is required. In must be a struct. |
| Arguments | Decoded strictly into In. An unknown property or a value of the wrong type is a tool error that wraps types.ErrInvalidToolArguments, so the model can correct the call. |
| Result | A string is returned as is. Any other Out is encoded as JSON. |
| Dependencies | RunContext.Deps comes from agent.ContextWithDeps on the run's context, else from agent.WithDeps. A missing or mistyped value is a tool error. Use agent.NoDeps for a function that needs none. |
Options:
| Option | Effect |
|---|---|
agent.Capability(c) |
Sets ToolDef.Capability, which capability gates and approval policies judge. |
agent.Approval(msg) / agent.Markers(...) |
Wraps the tool in a types.MarkedTool, so every call waits for a decision. |
agent.Idempotent() |
Declares types.IdempotentTool. The local durable engine repeats such a call after a crash instead of waiting for Reconcile. |
RunContext¶
RunContext[D] embeds the call's context.Context and adds:
| Field | Source |
|---|---|
Deps |
Host dependencies, typed as D |
Call |
Tool call ID, tool name, owning agent, root run ID (RunID()), branch (Branch()) |
Workspace |
The run's workspace, nil when none is configured |
IdempotencyKey |
The durable runner's key for this step, stable across replays. Empty without a durable runner that supplies one. |
Approval |
Whether a gate or marker held the call, the approver the host named in Resolution.Approver, and the grant that approved it, if any |
Knobs |
The agent's types.ToolContext |
types.ToolContext keeps working for existing tools. agent.NewRunContext[D](ctx) builds the same value inside any tool.
Versions¶
A Func tool reports a version: types.DefinitionHash of its name, description, parameter schema and capability.
Changing In changes the version.
registry.ToolSet.Registerregisters a versioned tool with that version. Registering it again unchanged returns the current revision. A changed schema adds a revision.ToolSet.AtVersionfinds the revision a transcript names.- The loop records the version in
ToolExecEndDelta.VersionandToolResultPart.ToolVersion, so the tree names the schema that produced each result. eval.AgentRun.AddProvenancerecords versions ineval.Provenance.Tools.eval.ConfigDriftreports a tool that ran at different versions in two runs.
AIFunc¶
type Ticket struct{ Body string `json:"body"` }
type Triage struct{ Priority string `json:"priority" enum:"low,high"` }
triage, err := agent.AIFunc[Ticket, Triage]("triage", "Triage a support ticket", agent.AIConfig{
Prompt: "Triage this ticket:\n{{.Body}}",
Preset: bundle, // or Provider: adapter
Repair: 1,
})
out, err := triage.Call(ctx, Ticket{Body: "Checkout returns 500"})
tool := triage.Tool()
- The prompt is a
text/templaterendered with the input. A missing field is an error. - Each call runs
agent.Structured[Out]on a new agent, so calls are independent and safe to run concurrently. Outmust be a struct. Its schema constrains the answer.Repairre-asks the model after an invalid answer.- The version hashes the prompt, the system prompt, both schemas, the output mode and the configuration hash. The configuration hash is
AIConfig.ConfigHash, else the preset's configuration key (apreset.Bundlereports one), else the preset name and catalog revision, else the provider name and model. Tool()declares the read capability and reports the AIFunc version, so the tree and eval provenance record it like a Func version.