tool

func AttachParts ¶

func AttachParts(ctx context.Context, parts ...*ai.Part)

AttachParts attaches additional content parts (e.g., media) to the tool's response. This can be called from any tool to produce a multipart response without changing the function signature, and from a WrapTool hook, before or after it runs the tool: the parts collect for the whole call and land on the response in call order. A nil part is ignored, so a constructor's failed result can be passed without a check.

The parts are folded into the response when the call returns, so they must be attached before then: a goroutine the tool spawns may attach as long as the tool waits for it, and one that outlives the call attaches to nothing. Safe for concurrent use from such goroutines, with no ordering guarantee across them.

func Fail ¶

func Fail(ctx context.Context, err error) error

Fail marks err as a result for the model rather than a failure of the tool loop. The loop answers the tool call with {"error": err.Error()} (see ai.Part.IsToolError) and continues, so the model can correct its input and try again. Return any other error to stop the loop.

Use it for errors the model can act on, such as invalid input or a missing record. A WrapTool hook may also return it. To return every error of a tool you do not own to the model, use the SoftToolErrors middleware in plugins/middleware instead. ai.IsToolFailError reports whether an error was made with Fail.

ctx is the context the tool function or hook received, as for Interrupt.

rows, err := db.Query(ctx, in.SQL)
if errors.Is(err, ErrSyntax) {
	return nil, tool.Fail(ctx, err) // the model fixes the query
}
return rows, err // a lost connection stops the loop

func Interrupt ¶

func Interrupt(ctx context.Context, data any) error

Interrupt returns the error a tool function returns to pause generation and send data to the caller. The interrupted tool request surfaces in ai.ModelResponse.Interrupts; the caller claims it with ai.ResumableToolAction.Interrupted, reads the data with ai.InterruptAs, and restarts the tool with ai.InterruptedCall.Restart or answers it with ai.InterruptedCall.Respond. Middleware returns it from a WrapTool hook to hold a tool call without executing it.

func(ctx context.Context, in TransferInput, resume *Confirmation) (*TransferOutput, error) {
	if resume == nil {
		return nil, tool.Interrupt(ctx, TransferInterrupt{Reason: "large_amount", Amount: in.Amount})
	}
	...
}

ctx is the context the tool function or hook received. It names the stage raising the interrupt, and the restart that answers it reaches that stage alone: for a tool function, its resume parameter; for a WrapTool hook, ResumeData in that hook, after which the tool runs as a fresh call and may interrupt on its own (see Released).

data must serialize to a JSON object (a struct or a map): it lands on the interrupted tool request as ai.ToolInterrupt data, which the wire protocol encodes as a JSON object, and it is converted to that object here, so the data has the same shape in process as after a wire hop. For a value that serializes to a JSON scalar or array (e.g. a string, number, or slice) Interrupt returns a plain error instead of an interrupt, which fails the tool call with a message naming the constraint; wrap such values in a struct or map field instead.

func OriginalInput ¶

func OriginalInput[In any](ctx context.Context) (In, bool)

OriginalInput extracts the typed original input if the caller provided a new one when restarting the call (via ai.InterruptedCall.RestartWithInput or ai.Part.ToToolRestartWithInput). Returns the zero value and false if no new input was provided, the tool is not being resumed, or the type doesn't match.

func Released ¶

func Released(ctx context.Context) bool

Released reports, in a WrapTool hook, whether the call is a restart that answers a later stage, a hook after this one or the tool's own interrupt, and the interrupted call records that this hook let it through (see ai.ToolInterrupt.ReleasedBy). A hook that holds calls for approval passes such a restart on rather than holding it again. False in a fresh call, in the hook the restart answers (see ResumeData), in a hook the interrupted call does not record, such as one added to the chain since, in every hook when the restart replaced the call's input, and for an interrupt that does not record which stage raised it, whose answer every stage reads instead.

func ResumeData ¶

func ResumeData[T any](ctx context.Context) (T, bool)

ResumeData extracts typed resume data (sent via ai.InterruptedCall.Restart or ai.Part.ToToolRestart) from the context of a restarted tool call, in the stage the restart answers: the tool function when the tool interrupted, or the WrapTool hook that raised the interrupt. Returns the zero value and false if the call is not a resumption, the restart answers another stage, or the data does not decode into T.

Data the caller built as a T is returned as is. Any other data is read by its JSON shape, so a struct of another type with the same fields decodes the same in process as after a wire hop.

Tool functions created with ai.NewResumableTool receive the resume data as a parameter and don't need this; it is for middleware (e.g. a WrapTool hook deciding whether the call it held was approved).

func SendChunk ¶

func SendChunk(ctx context.Context, chunk *ai.ModelResponseChunk)

SendChunk streams an ai.ModelResponseChunk during tool execution, e.g. progress for a slow tool. The tool builds the chunk itself and has full control over its contents; set its Role to ai.RoleTool so the client can tell it from the model's own output.

This is best-effort: if no streaming callback is available (e.g., the tool is called via a non-streaming Generate), the call is a no-op. The tool's final return value is always the authoritative response.