tool

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package tool provides tool definitions, handlers, registries, and toolsets for building LLM-callable tools in agentic-go agents.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Auto 

func Auto[TInput any, TOutput any](
	handler func(input TInput) (TOutput, error),
	opts ...AutoToolOption,
) (core.Tool, core.ToolHandler, error)

Auto creates a plain tool by reflecting on the handler function's input type. Name is inferred from TInput type name (CamelCase -> snake_case, "Input" suffix stripped). Description is inferred from a `tool` struct tag on a `struct{}` field of TInput.

func AutoWithDeps 

func AutoWithDeps[TInput any, TOutput any, DepsT any](
	handler func(ctx core.RunContext[DepsT], input TInput) (TOutput, error),
	opts ...AutoToolOption,
) (core.Tool, core.ToolHandler, error)

AutoWithDeps creates a deps-aware tool with auto-inferred metadata.

func DeferredTool 

func DeferredTool[TInput any, TOutput any](
	name, description string,
	handler func(ctx context.Context, input TInput) (<-chan TOutput, error),
	opts ...DeferredToolOption,
) (core.Tool, core.ToolHandler, error)

DeferredTool creates a tool that executes asynchronously. The handler returns a channel that will receive the result.

func DeferredToolWithApproval 

func DeferredToolWithApproval[TInput any, TOutput any](
	name, description string,
	handler func(ctx context.Context, input TInput) (TOutput, error),
	approvalFn ApprovalFunc,
	opts ...DeferredToolOption,
) (core.Tool, core.ToolHandler, error)

DeferredToolWithApproval creates a tool that requires human approval before execution.

func MustAuto 

func MustAuto[TInput any, TOutput any](
	handler func(input TInput) (TOutput, error),
	opts ...AutoToolOption,
) (core.Tool, core.ToolHandler)

MustAuto is like Auto but panics on error.

func MustAutoWithDeps 

func MustAutoWithDeps[TInput any, TOutput any, DepsT any](
	handler func(ctx core.RunContext[DepsT], input TInput) (TOutput, error),
	opts ...AutoToolOption,
) (core.Tool, core.ToolHandler)

MustAutoWithDeps is like AutoWithDeps but panics on error.

func MustDeferredTool 

func MustDeferredTool[TInput any, TOutput any](
	name, description string,
	handler func(ctx context.Context, input TInput) (<-chan TOutput, error),
	opts ...DeferredToolOption,
) (core.Tool, core.ToolHandler)

MustDeferredTool is like DeferredTool but panics on error.

func MustDeferredToolWithApproval 

func MustDeferredToolWithApproval[TInput any, TOutput any](
	name, description string,
	handler func(ctx context.Context, input TInput) (TOutput, error),
	approvalFn ApprovalFunc,
	opts ...DeferredToolOption,
) (core.Tool, core.ToolHandler)

MustDeferredToolWithApproval is like DeferredToolWithApproval but panics on error.

func MustNewToolFromStruct 

func MustNewToolFromStruct(name, description string, input interface{}) core.Tool

MustNewToolFromStruct is like NewToolFromStruct but panics on error.

func MustToolPlain 

func MustToolPlain[TInput any, TOutput any](
	name, description string,
	handler func(input TInput) (TOutput, error),
	opts ...ToolOption,
) (core.Tool, core.ToolHandler)

MustToolPlain is like ToolPlain but panics on error.

func MustToolWithDeps 

func MustToolWithDeps[TInput any, TOutput any, DepsT any](
	name, description string,
	handler func(ctx core.RunContext[DepsT], input TInput) (TOutput, error),
	opts ...ToolOption,
) (core.Tool, core.ToolHandler)

MustToolWithDeps is like ToolWithDeps but panics on error.

func NewToolFromStruct 

func NewToolFromStruct(name, description string, input interface{}) (core.Tool, error)

NewToolFromStruct creates a Tool definition from a struct type using JSON schema generation. The input parameter should be an instance of the struct type (can be zero value).

Supported struct tags:

  • json: field name in JSON schema
  • description: field description
  • required: marks field as required (use `required:"true"`)
  • enum: comma-separated list of allowed values
  • minimum: minimum value for numeric fields
  • maximum: maximum value for numeric fields
  • minLength: minimum length for string fields
  • maxLength: maximum length for string fields
  • pattern: regex pattern for string validation

func RegisterToolset 

func RegisterToolset(registry ToolRegistry, set Toolset) error

RegisterToolset registers all tools from a Toolset into a ToolRegistry.

func ToolPlain 

func ToolPlain[TInput any, TOutput any](
	name, description string,
	handler func(input TInput) (TOutput, error),
	opts ...ToolOption,
) (core.Tool, core.ToolHandler, error)

ToolPlain creates a plain tool (no dependencies) from a struct and handler function.

func ToolWithDeps 

func ToolWithDeps[TInput any, TOutput any, DepsT any](
	name, description string,
	handler func(ctx core.RunContext[DepsT], input TInput) (TOutput, error),
	opts ...ToolOption,
) (core.Tool, core.ToolHandler, error)

ToolWithDeps creates a tool that has access to agent-level dependencies.

Types

type ApprovalFunc 

type ApprovalFunc func(ctx context.Context, toolCall core.ToolUse) (approved bool, err error)

ApprovalFunc is called when a deferred tool needs human approval. It receives the tool call details and returns whether to proceed.

type AutoToolOption 

type AutoToolOption func(*autoToolConfig)

AutoToolOption configures auto-registration behavior.

func WithDescription 

func WithDescription(desc string) AutoToolOption

WithDescription overrides the auto-inferred description.

func WithName 

func WithName(name string) AutoToolOption

WithName overrides the auto-inferred tool name.

type DeferredStatus 

type DeferredStatus int

DeferredStatus represents the state of an asynchronous tool call. 

const (
	DeferredPending DeferredStatus = iota
	DeferredApproved
	DeferredRejected
	DeferredTimedOut
)

type DeferredToolOption 

type DeferredToolOption func(*deferredToolConfig)

DeferredToolOption configures deferred tool behavior.

func WithApproval 

func WithApproval(fn ApprovalFunc) DeferredToolOption

WithApproval sets a human-in-the-loop approval function.

func WithDeferredTimeout 

func WithDeferredTimeout(d time.Duration) DeferredToolOption

WithDeferredTimeout sets the maximum wait time for a deferred tool.

type DeferredToolResult 

type DeferredToolResult struct {
	ToolUseID string
	ToolName  string
	Status    DeferredStatus
	Content   interface{}
	Error     error
}

DeferredToolResult represents the eventual result of an async tool call.

type DepsToolHandler 

type DepsToolHandler[TInput any, TOutput any, DepsT any] struct {
	// contains filtered or unexported fields
}

DepsToolHandler implements ToolHandler for tools that need access to agent dependencies.

func (*DepsToolHandler[TInput, TOutput, DepsT]) Execute 

func (h *DepsToolHandler[TInput, TOutput, DepsT]) Execute(
	ctx context.Context,
	input map[string]interface{},
	agentDeps any,
) (interface{}, error)

Execute implements ToolHandler.

func (*DepsToolHandler[TInput, TOutput, DepsT]) Name 

func (h *DepsToolHandler[TInput, TOutput, DepsT]) Name() string

Name implements ToolHandler.

func (*DepsToolHandler[TInput, TOutput, DepsT]) ToolConfig 

func (h *DepsToolHandler[TInput, TOutput, DepsT]) ToolConfig() *core.ToolConfig

ToolConfig implements ConfigurableToolHandler.

type FuncToolset 

type FuncToolset struct {
	// contains filtered or unexported fields
}

FuncToolset is a simple Toolset backed by a slice of tool/handler pairs.

func NewToolset 

func NewToolset() *FuncToolset

NewToolset creates a new FuncToolset from tool/handler pairs.

func (*FuncToolset) Add 

func (ts *FuncToolset) Add(tool core.Tool, handler core.ToolHandler) *FuncToolset

Add adds a tool and handler to the toolset.

func (*FuncToolset) ToolsAndHandlers 

func (ts *FuncToolset) ToolsAndHandlers() ([]core.Tool, []core.ToolHandler)

ToolsAndHandlers implements Toolset.

type NoDeps added in v0.2.0 

type NoDeps = core.NoDeps

NoDeps is the empty dependency type for tools that do not use RunContext dependencies. It matches core.NoDeps and the root [agentic.NoDeps] alias.

type PlainToolHandler 

type PlainToolHandler[TInput any, TOutput any] struct {
	// contains filtered or unexported fields
}

PlainToolHandler implements ToolHandler for tools that don't need dependencies.

func (*PlainToolHandler[TInput, TOutput]) Execute 

func (h *PlainToolHandler[TInput, TOutput]) Execute(
	ctx context.Context,
	input map[string]interface{},
	deps any,
) (interface{}, error)

Execute implements ToolHandler.

func (*PlainToolHandler[TInput, TOutput]) Name 

func (h *PlainToolHandler[TInput, TOutput]) Name() string

Name implements ToolHandler.

func (*PlainToolHandler[TInput, TOutput]) ToolConfig 

func (h *PlainToolHandler[TInput, TOutput]) ToolConfig() *core.ToolConfig

ToolConfig implements ConfigurableToolHandler.

type ToolOption 

type ToolOption func(*core.ToolConfig)

ToolOption configures individual tool behavior.

func WithToolMaxRetries 

func WithToolMaxRetries(n int) ToolOption

WithToolMaxRetries sets the max retry count for a specific tool. This overrides the agent's global MaxRetries for this tool only.

type ToolRegistry 

type ToolRegistry interface {
	// Register adds a tool and its handler to the registry.
	Register(tool core.Tool, handler core.ToolHandler) error

	// Get retrieves a handler by tool name.
	Get(name string) (core.ToolHandler, bool)

	// Execute runs a single tool call and returns the result.
	Execute(ctx context.Context, toolCall core.ToolUse, deps any) (core.ToolExecutionResult, error)

	// ExecuteBatch runs multiple tool calls and returns all results.
	ExecuteBatch(ctx context.Context, toolCalls []core.ToolUse, deps any) ([]core.ToolExecutionResult, error)

	// Tools returns all registered tool definitions.
	Tools() []core.Tool

	// Has returns true if a tool with the given name is registered.
	Has(name string) bool

	// Count returns the number of registered tools.
	Count() int
}

ToolRegistry manages the registration and execution of tools.

func NewRegistry 

func NewRegistry() ToolRegistry

NewRegistry creates a new ToolRegistry.

type Toolset 

type Toolset interface {
	// ToolsAndHandlers returns all tools and their handlers in this set.
	ToolsAndHandlers() ([]core.Tool, []core.ToolHandler)
}

Toolset is a composable collection of tools and their handlers.

func CombineToolsets 

func CombineToolsets(sets ...Toolset) Toolset

CombineToolsets merges multiple toolsets into one.

func FilterToolset 

func FilterToolset(set Toolset, predicate func(toolName string) bool) Toolset

FilterToolset filters a toolset based on a predicate on the tool name.

func PrefixToolset 

func PrefixToolset(set Toolset, prefix string) Toolset

PrefixToolset adds a prefix to all tool names in a toolset. The prefix is joined with "__" (e.g., prefix "math" + tool "add" -> "math__add").

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.