Documentation
¶
Overview ¶
Package tool defines the tool component interfaces that allow language models to invoke external capabilities, and helpers for interrupt/resume within tools.
Interface Hierarchy ¶
BaseTool — Info() only; for passing tool metadata to a ChatModel ├── InvokableTool — standard: args as JSON string, returns string ├── StreamableTool — standard streaming: args as JSON string, returns StreamReader[string] ├── EnhancedInvokableTool — multimodal: args as *schema.ToolArgument, returns *schema.ToolResult └── EnhancedStreamableTool— multimodal streaming
Choosing an Interface ¶
Implement InvokableTool for most tools — arguments arrive as a JSON string automatically decoded from the model's tool call, and the result is a string sent back to the model.
Implement EnhancedInvokableTool when the tool needs to return structured multimodal content (images, audio, files) rather than plain text. When a tool implements both a standard and an enhanced interface, ToolsNode prioritises the enhanced interface.
Creating Tools ¶
The [utils] sub-package provides constructors that eliminate boilerplate:
- [utils.InferTool] / [utils.InferStreamTool] — infer parameter schema from Go struct tags
- [utils.NewTool] / [utils.NewStreamTool] — manual ToolInfo + typed function
Interrupt / Resume ¶
Tools can pause execution and wait for external input using Interrupt, StatefulInterrupt, and CompositeInterrupt. Use GetInterruptState and GetResumeContext inside the tool to distinguish first-run from resumed-run.
See https://www.cloudwego.io/docs/eino/core_modules/components/tools_node_guide/ See https://www.cloudwego.io/docs/eino/core_modules/components/tools_node_guide/how_to_create_a_tool/
Index ¶
- func CompositeInterrupt(ctx context.Context, info any, state any, errs ...error) error
- func GetImplSpecificOptions[T any](base *T, opts ...Option) *T
- func GetInterruptState[T any](ctx context.Context) (wasInterrupted bool, hasState bool, state T)
- func GetResumeContext[T any](ctx context.Context) (isResumeTarget bool, hasData bool, data T)
- func Interrupt(ctx context.Context, info any) error
- func StatefulInterrupt(ctx context.Context, info any, state any) error
- type BaseTool
- type CallbackInput
- type CallbackOutput
- type EnhancedInvokableTool
- type EnhancedStreamableTool
- type InvokableTool
- type Option
- type StreamableTool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompositeInterrupt ¶ added in v0.7.22
CompositeInterrupt creates an interrupt that aggregates multiple sub-interrupts. Use this when a tool internally executes a graph or other interruptible components.
Parameters:
- ctx: The context passed to InvokableRun/StreamableRun
- info: User-facing information for this tool's interrupt
- state: Internal state to persist for this tool
- errs: Interrupt errors from sub-components (graphs, other tools, etc.)
Example:
func (t *MyTool) InvokableRun(ctx context.Context, args string, opts ...Option) (string, error) {
result, err := t.internalGraph.Invoke(ctx, input)
if err != nil {
if _, ok := tool.IsInterruptError(err); ok {
return "", tool.CompositeInterrupt(ctx, "graph interrupted", myState, err)
}
return "", err
}
return result, nil
}
func GetImplSpecificOptions ¶
GetImplSpecificOptions provides tool author the ability to extract their own custom options from the unified Option type. T: the type of the impl specific options struct. This function should be used within the tool implementation's InvokableRun or StreamableRun functions. It is recommended to provide a base T as the first argument, within which the tool author can provide default values for the impl specific options. eg.
type customOptions struct {
conf string
}
defaultOptions := &customOptions{}
customOptions := tool.GetImplSpecificOptions(defaultOptions, opts...)
func GetInterruptState ¶ added in v0.7.22
GetInterruptState checks if the tool was previously interrupted and retrieves saved state.
Returns:
- wasInterrupted: true if this tool was part of a previous interruption
- hasState: true if state was saved and successfully cast to type T
- state: the saved state (zero value if hasState is false)
Example:
func (t *MyTool) InvokableRun(ctx context.Context, args string, opts ...Option) (string, error) {
wasInterrupted, hasState, state := tool.GetInterruptState[MyState](ctx)
if wasInterrupted && hasState {
// Continue from saved state
return continueFrom(state), nil
}
// First run
return "", tool.StatefulInterrupt(ctx, "need input", MyState{Step: 1})
}
func GetResumeContext ¶ added in v0.7.22
GetResumeContext checks if this tool is the explicit target of a resume operation.
Returns:
- isResumeTarget: true if this tool was explicitly targeted for resume
- hasData: true if resume data was provided
- data: the resume data (zero value if hasData is false)
Use this to differentiate between:
- Being resumed as the target (should proceed with work)
- Being re-executed because a sibling was resumed (should re-interrupt)
Example:
func (t *MyTool) InvokableRun(ctx context.Context, args string, opts ...Option) (string, error) {
wasInterrupted, _, _ := tool.GetInterruptState[any](ctx)
if !wasInterrupted {
return "", tool.Interrupt(ctx, "need confirmation")
}
isTarget, hasData, data := tool.GetResumeContext[string](ctx)
if !isTarget {
// Not our turn - re-interrupt
return "", tool.Interrupt(ctx, nil)
}
if hasData {
return data, nil
}
return "default result", nil
}
func Interrupt ¶ added in v0.7.22
Interrupt pauses tool execution and signals the orchestration layer to checkpoint. The tool can be resumed later with optional data.
Parameters:
- ctx: The context passed to InvokableRun/StreamableRun
- info: User-facing information about why the tool is interrupting (e.g., "needs user confirmation")
Returns an error that should be returned from InvokableRun/StreamableRun.
Example:
func (t *MyTool) InvokableRun(ctx context.Context, args string, opts ...Option) (string, error) {
if needsConfirmation(args) {
return "", tool.Interrupt(ctx, "Please confirm this action")
}
return doWork(args), nil
}
func StatefulInterrupt ¶ added in v0.7.22
StatefulInterrupt pauses tool execution with state preservation. Use this when the tool has internal state that must be restored on resume.
Parameters:
- ctx: The context passed to InvokableRun/StreamableRun
- info: User-facing information about the interrupt
- state: Internal state to persist (must be gob-serializable)
Example:
func (t *MyTool) InvokableRun(ctx context.Context, args string, opts ...Option) (string, error) {
wasInterrupted, hasState, state := tool.GetInterruptState[MyState](ctx)
if !wasInterrupted {
// First run - interrupt with state
return "", tool.StatefulInterrupt(ctx, "processing", MyState{Step: 1})
}
// Resumed - continue from saved state
return continueFrom(state), nil
}
Types ¶
type BaseTool ¶
BaseTool provides the metadata that a ChatModel uses to decide whether and how to call a tool. Info returns a schema.ToolInfo containing the tool name, description, and parameter JSON schema.
BaseTool alone is sufficient when passing tool definitions to a ChatModel via WithTools — the model only needs the schema to generate tool calls. To also execute the tool, implement InvokableTool or StreamableTool.
type CallbackInput ¶
type CallbackInput struct {
// ArgumentsInJSON is the arguments in json format for the tool.
ArgumentsInJSON string
// Extra is the extra information for the tool.
Extra map[string]any
}
CallbackInput is the input for the tool callback.
func ConvCallbackInput ¶
func ConvCallbackInput(src callbacks.CallbackInput) *CallbackInput
ConvCallbackInput converts the callback input to the tool callback input.
type CallbackOutput ¶
type CallbackOutput struct {
// Response is the response for the tool.
Response string
// ToolOutput is the multimodal output for the tool. Used when the tool returns structured data.
ToolOutput *schema.ToolResult
// Extra is the extra information for the tool.
Extra map[string]any
}
CallbackOutput is the output for the tool callback.
func ConvCallbackOutput ¶
func ConvCallbackOutput(src callbacks.CallbackOutput) *CallbackOutput
ConvCallbackOutput converts the callback output to the tool callback output.
type EnhancedInvokableTool ¶ added in v0.7.31
type EnhancedInvokableTool interface {
BaseTool
InvokableRun(ctx context.Context, toolArgument *schema.ToolArgument, opts ...Option) (*schema.ToolResult, error)
}
EnhancedInvokableTool is a tool that returns structured multimodal results.
Unlike InvokableTool, arguments arrive as a schema.ToolArgument (not a raw JSON string) and the result is a schema.ToolResult which can carry text, images, audio, video, and file content.
When a tool implements both a standard and an enhanced interface, ToolsNode prioritises the enhanced interface.
type EnhancedStreamableTool ¶ added in v0.7.31
type EnhancedStreamableTool interface {
BaseTool
StreamableRun(ctx context.Context, toolArgument *schema.ToolArgument, opts ...Option) (*schema.StreamReader[*schema.ToolResult], error)
}
EnhancedStreamableTool is the streaming variant of EnhancedInvokableTool.
It streams schema.ToolResult chunks, enabling incremental multimodal output. The caller is responsible for closing the returned schema.StreamReader.
type InvokableTool ¶
type InvokableTool interface {
BaseTool
// InvokableRun executes the tool with arguments encoded as a JSON string.
InvokableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (string, error)
}
InvokableTool is a tool that can be executed by ToolsNode.
InvokableRun receives the model's tool call arguments as a JSON-encoded string and returns a plain string result that is sent back to the model as a tool message. The framework handles JSON decoding automatically when using the [utils.InferTool] or [utils.NewTool] constructors.
type Option ¶
type Option struct {
// contains filtered or unexported fields
}
Option defines call option for InvokableTool or StreamableTool component, which is part of component interface signature. Each tool implementation could define its own options struct and option funcs within its own package, then wrap the impl specific option funcs into this type, before passing to InvokableRun or StreamableRun.
func WrapImplSpecificOptFn ¶
WrapImplSpecificOptFn wraps the impl specific option functions into Option type. T: the type of the impl specific options struct. Tool implementations are required to use this function to convert its own option functions into the unified Option type. For example, if the tool defines its own options struct:
type customOptions struct {
conf string
}
Then the tool needs to provide an option function as such:
func WithConf(conf string) Option {
return WrapImplSpecificOptFn(func(o *customOptions) {
o.conf = conf
}
}
.
type StreamableTool ¶
type StreamableTool interface {
BaseTool
StreamableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (*schema.StreamReader[string], error)
}
StreamableTool is a streaming variant of InvokableTool.
StreamableRun returns a schema.StreamReader that yields string chunks incrementally. The caller (ToolsNode) is responsible for closing the reader.
Source Files
Directories