Documentation
¶
Overview ¶
Package tool provides runtime helpers for use inside tool functions.
APIs in this package are under active development and may change in any minor version release. Use with caution in production environments.
Index ¶
- func AttachParts(ctx context.Context, parts ...*ai.Part)
- func Interrupt(data any) error
- func InterruptAs[T any](p *ai.Part) (T, bool)
- func NewPartsContext(ctx context.Context) (context.Context, func() []*ai.Part)
- func OriginalInput[In any](ctx context.Context) (In, bool)
- func Respond(interruptedPart *ai.Part, output any) (*ai.Part, error)
- func Resume[Res any](interruptedPart *ai.Part, data Res) (*ai.Part, error)
- func SendChunk(ctx context.Context, chunk *ai.ModelResponseChunk)
- func SendPartial(ctx context.Context, output any)
- func SetOriginalInput(ctx context.Context, input any) context.Context
- type InterruptError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AttachParts ¶
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.
func Interrupt ¶
Interrupt interrupts tool execution and sends data to the caller. The caller can read this data with InterruptAs and resume the tool with Resume.
data must serialize to a JSON object (a struct or a map), since it is carried as structured metadata on the interrupted tool request. A value that serializes to a JSON scalar or array (e.g. a string, number, or slice) makes the tool fail when it returns; wrap such values in a struct or map field instead.
func InterruptAs ¶
InterruptAs extracts typed interrupt data from an interrupted tool request ai.Part. Returns the zero value and false if the part is not an interrupt or the type doesn't match.
func NewPartsContext ¶
NewPartsContext returns a context with a parts collector. This is internal plumbing used by the aix package.
func OriginalInput ¶
OriginalInput returns the original input if the caller replaced it during restart. Returns the zero value and false if the input was not replaced or the tool is not being resumed.
func Respond ¶
Respond creates a tool response ai.Part for an interrupted tool request. Instead of re-executing the tool (as Resume does), this provides a pre-computed result directly.
This is a convenience alternative to [aix.Tool.Respond] that does not require access to the tool definition.
func Resume ¶
Resume creates a restart ai.Part for resuming an interrupted tool call. The interruptedPart must be an interrupted tool request (as received via InterruptAs or ai.ModelResponse.Interrupts). The data is delivered to the tool function's resume parameter when it is re-executed.
This is a convenience alternative to [aix.InterruptibleTool.Resume] that does not require access to the tool definition.
data must serialize to a JSON object (a struct or a map); see Interrupt for the rationale. A value that serializes to a JSON scalar or array returns an error.
func SendChunk ¶
func SendChunk(ctx context.Context, chunk *ai.ModelResponseChunk)
SendChunk streams a raw ai.ModelResponseChunk during tool execution. Unlike SendPartial, which wraps arbitrary data in a partial tool response, SendChunk gives the tool full control over the chunk contents.
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.
func SendPartial ¶
SendPartial streams a partial tool response during tool execution. The output is arbitrary structured data (e.g., progress information) that will be delivered to the client as a partial ai.ToolResponse.
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.
Example:
tool.SendPartial(ctx, map[string]any{"step": "uploading", "progress": 50})
Types ¶
type InterruptError ¶
type InterruptError struct {
Data any
}
InterruptError is returned by Interrupt to signal tool interruption.
func (*InterruptError) Error ¶
func (e *InterruptError) Error() string
Source Files