Documentation
¶
Overview ¶
Package tools provides tool interfaces, registry, and argument parsing for AI tool calling.
Tool is the executable tool contract: it embeds core.Tool (Name, Description, and Schema) and adds Call. Because it embeds core.Tool, any Tool implementation can be passed directly to ChatBuilder.Tools or stored in ChatRequest.Tools, and every provider transmits its schema:
type Tool interface {
core.Tool
Call(ctx context.Context, args json.RawMessage) (any, error)
}
ToolSchema is an alias of core.ToolSchema; the schema contract is owned by core so providers can consume it without importing this package.
The package also provides a tool Registry, middleware (logging, timeout, rate limiting, cache, validation, retry, circuit breaking, metrics), and the ParseArgs generic helper for decoding tool-call arguments.
Index ¶
- Constants
- Variables
- func ContextWithToolContext(ctx context.Context, tc *ToolContext) context.Context
- func DefaultCacheKey(toolName string, args json.RawMessage) string
- func ParseArgs[T any](call core.ToolCall) (*T, error)
- func ToolSchemaFromContext(ctx context.Context) (json.RawMessage, bool)
- type Cache
- type CacheKeyFunc
- type CircuitBreakerConfig
- type CircuitState
- type Logger
- type MetricsCollector
- type Middleware
- func Chain(middlewares ...Middleware) Middleware
- func ExceptTools(toolNames []string, middleware Middleware) Middleware
- func ForTools(toolNames []string, middleware Middleware) Middleware
- func WithBasicValidation() Middleware
- func WithCache(cache Cache, ttl time.Duration) Middleware
- func WithCacheCustomKey(cache Cache, ttl time.Duration, keyFunc CacheKeyFunc) Middleware
- func WithCircuitBreaker(config CircuitBreakerConfig) Middleware
- func WithDetailedLogging(logger Logger) Middleware
- func WithLogging(logger Logger) Middleware
- func WithMetrics(collector MetricsCollector) Middleware
- func WithRateLimit(ratePerSecond float64) Middleware
- func WithRateLimiter(limiter RateLimiter) Middleware
- func WithRetry(config RetryConfig) Middleware
- func WithTimeout(d time.Duration) Middleware
- func WithValidation(validator SchemaValidator) Middleware
- type RateLimiter
- type Registry
- func (r *Registry) Execute(ctx context.Context, name string, args json.RawMessage) (any, error)
- func (r *Registry) Get(name string) (Tool, bool)
- func (r *Registry) List() []Tool
- func (r *Registry) Register(t Tool) error
- func (r *Registry) RegisterWithMiddleware(t Tool, middlewares ...Middleware) error
- type RegistryOption
- type RetryConfig
- type SchemaValidator
- type Tool
- type ToolCallFunc
- type ToolContext
- type ToolSchema
Constants ¶
const ToolContextSchemaMetadataKey = "schema"
ToolContextSchemaMetadataKey is the metadata key used to store tool schemas.
Variables ¶
var ( // ErrDuplicateTool is returned when attempting to register a tool with a // name that is already registered. ErrDuplicateTool = errors.New("tool already registered") // ErrToolNotFound is returned when attempting to execute an unregistered tool. ErrToolNotFound = errors.New("tool not found") )
var ErrCircuitOpen = errors.New("circuit breaker open: too many failures")
ErrCircuitOpen is returned when the circuit breaker is open.
Functions ¶
func ContextWithToolContext ¶ added in v0.11.0
func ContextWithToolContext(ctx context.Context, tc *ToolContext) context.Context
ContextWithToolContext adds ToolContext to a context.
func DefaultCacheKey ¶ added in v0.11.0
func DefaultCacheKey(toolName string, args json.RawMessage) string
DefaultCacheKey generates a cache key by hashing tool name and arguments.
func ParseArgs ¶
ParseArgs parses tool call arguments into a typed struct. It unmarshals the JSON arguments from the ToolCall into the target type T.
Example:
type WeatherArgs struct {
Location string `json:"location"`
Unit string `json:"unit"`
}
args, err := tools.ParseArgs[WeatherArgs](toolCall)
if err != nil {
return nil, err
}
// Use args.Location, args.Unit
func ToolSchemaFromContext ¶ added in v0.12.0
func ToolSchemaFromContext(ctx context.Context) (json.RawMessage, bool)
ToolSchemaFromContext retrieves a tool schema from context.
Types ¶
type Cache ¶ added in v0.11.0
Cache is the interface for caching tool results.
func NewMemoryCache ¶ added in v0.11.0
func NewMemoryCache() Cache
NewMemoryCache creates a new in-memory cache.
type CacheKeyFunc ¶ added in v0.11.0
type CacheKeyFunc func(toolName string, args json.RawMessage) string
CacheKeyFunc generates a cache key from tool name and arguments.
type CircuitBreakerConfig ¶ added in v0.11.0
type CircuitBreakerConfig struct {
FailureThreshold int // Failures before opening.
SuccessThreshold int // Successes in half-open to close.
OpenDuration time.Duration // How long to stay open.
}
CircuitBreakerConfig configures circuit breaker behavior.
func DefaultCircuitBreakerConfig ¶ added in v0.11.0
func DefaultCircuitBreakerConfig() CircuitBreakerConfig
DefaultCircuitBreakerConfig returns sensible circuit breaker defaults.
type CircuitState ¶ added in v0.11.0
type CircuitState int
CircuitState represents the state of a circuit breaker.
const ( CircuitClosed CircuitState = iota // Normal operation. CircuitOpen // Failing, reject calls. CircuitHalfOpen // Testing if recovered. )
func (CircuitState) String ¶ added in v0.11.0
func (s CircuitState) String() string
String returns the string representation of a CircuitState.
type MetricsCollector ¶ added in v0.11.0
type MetricsCollector interface {
// RecordCall records a tool call with its outcome.
RecordCall(toolName string, duration time.Duration, err error)
}
MetricsCollector receives tool execution metrics.
type Middleware ¶ added in v0.11.0
type Middleware func(next ToolCallFunc) ToolCallFunc
Middleware wraps a ToolCallFunc to add behavior before and/or after execution. Middleware functions receive the next handler in the chain and return a new handler.
func Chain ¶ added in v0.11.0
func Chain(middlewares ...Middleware) Middleware
Chain combines multiple middleware into a single middleware. Middleware are executed in the order provided (first middleware is outermost).
func ExceptTools ¶ added in v0.11.0
func ExceptTools(toolNames []string, middleware Middleware) Middleware
ExceptTools applies middleware to all tools except those with the specified names.
func ForTools ¶ added in v0.11.0
func ForTools(toolNames []string, middleware Middleware) Middleware
ForTools applies middleware only to tools with the specified names.
func WithBasicValidation ¶ added in v0.11.0
func WithBasicValidation() Middleware
WithBasicValidation creates middleware that performs basic JSON validation.
func WithCache ¶ added in v0.11.0
func WithCache(cache Cache, ttl time.Duration) Middleware
WithCache creates middleware that caches tool results.
func WithCacheCustomKey ¶ added in v0.11.0
func WithCacheCustomKey(cache Cache, ttl time.Duration, keyFunc CacheKeyFunc) Middleware
WithCacheCustomKey creates caching middleware with a custom key function.
func WithCircuitBreaker ¶ added in v0.11.0
func WithCircuitBreaker(config CircuitBreakerConfig) Middleware
WithCircuitBreaker creates middleware that implements the circuit breaker pattern.
func WithDetailedLogging ¶ added in v0.11.0
func WithDetailedLogging(logger Logger) Middleware
WithDetailedLogging creates middleware that logs tool calls with arguments. WARNING: May log sensitive data. Use only in development.
func WithLogging ¶ added in v0.11.0
func WithLogging(logger Logger) Middleware
WithLogging creates middleware that logs tool calls.
func WithMetrics ¶ added in v0.11.0
func WithMetrics(collector MetricsCollector) Middleware
WithMetrics creates middleware that records tool execution metrics.
func WithRateLimit ¶ added in v0.11.0
func WithRateLimit(ratePerSecond float64) Middleware
WithRateLimit creates middleware that rate limits tool calls. Uses a token bucket algorithm with the specified rate (calls per second).
func WithRateLimiter ¶ added in v0.11.0
func WithRateLimiter(limiter RateLimiter) Middleware
WithRateLimiter creates middleware using a custom rate limiter.
func WithRetry ¶ added in v0.11.0
func WithRetry(config RetryConfig) Middleware
WithRetry creates middleware that retries failed tool calls.
func WithTimeout ¶ added in v0.11.0
func WithTimeout(d time.Duration) Middleware
WithTimeout creates middleware that enforces a timeout on tool execution.
func WithValidation ¶ added in v0.11.0
func WithValidation(validator SchemaValidator) Middleware
WithValidation creates middleware that validates arguments against the tool's schema.
type RateLimiter ¶ added in v0.11.0
type RateLimiter interface {
// Allow returns true if the request should proceed.
Allow() bool
// Wait blocks until the request can proceed or context is canceled.
Wait(ctx context.Context) error
}
RateLimiter is the interface for rate limiting.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages a collection of tools indexed by name. Registry is safe for concurrent use.
func NewRegistry ¶
func NewRegistry(opts ...RegistryOption) *Registry
NewRegistry creates a new tool registry with optional configuration.
func (*Registry) Execute ¶ added in v0.11.0
Execute finds a tool by name and calls it with the given arguments. Returns an error wrapping ErrToolNotFound if the tool is not registered, or returns the tool's execution error unchanged.
func (*Registry) Get ¶
Get retrieves a tool by name. Returns the tool and true if found, or nil and false if not found.
func (*Registry) List ¶
List returns all registered tools. The returned slice is a copy and safe to modify.
func (*Registry) Register ¶
Register adds a tool to the registry. If registry middleware is configured, it's automatically applied. Returns ErrDuplicateTool if a tool with the same name is already registered.
func (*Registry) RegisterWithMiddleware ¶ added in v0.11.0
func (r *Registry) RegisterWithMiddleware(t Tool, middlewares ...Middleware) error
RegisterWithMiddleware adds a tool with additional per-tool middleware. Per-tool middleware executes inside registry middleware.
type RegistryOption ¶ added in v0.11.0
type RegistryOption func(*Registry)
RegistryOption configures a Registry.
func WithRegistryMiddleware ¶ added in v0.11.0
func WithRegistryMiddleware(middlewares ...Middleware) RegistryOption
WithRegistryMiddleware applies middleware to all tools registered in the registry. Middleware are applied in the order provided when tools are registered.
type RetryConfig ¶ added in v0.11.0
type RetryConfig struct {
MaxAttempts int
InitialWait time.Duration
MaxWait time.Duration
Multiplier float64
Retryable func(error) bool // Returns true if error is retryable.
}
RetryConfig configures retry behavior.
func DefaultRetryConfig ¶ added in v0.11.0
func DefaultRetryConfig() RetryConfig
DefaultRetryConfig returns sensible retry defaults.
type SchemaValidator ¶ added in v0.11.0
type SchemaValidator interface {
Validate(schema json.RawMessage, data json.RawMessage) error
}
SchemaValidator validates arguments against a JSON schema.
type Tool ¶
type Tool interface {
core.Tool
// Call executes the tool with the given arguments.
// The args parameter contains the raw JSON arguments from the model.
// Returns the tool's result or an error if execution fails.
Call(ctx context.Context, args json.RawMessage) (any, error)
}
Tool defines the interface for executable AI-callable tools. Tools provide a schema for argument validation and a Call method for execution.
Tool embeds core.Tool, so any type implementing Tool can be passed directly to ChatBuilder.Tools (or ChatRequest.Tools) and providers will transmit its schema.
func ApplyMiddleware ¶ added in v0.11.0
func ApplyMiddleware(tool Tool, middlewares ...Middleware) Tool
ApplyMiddleware wraps a tool with middleware. Returns a new tool that executes middleware around the original.
type ToolCallFunc ¶ added in v0.11.0
ToolCallFunc is the function signature for tool execution. Middleware wraps this function to add behavior.
type ToolContext ¶ added in v0.11.0
type ToolContext struct {
// ToolName is the name of the tool being called.
ToolName string
// CallID is a unique identifier for this invocation (if available).
CallID string
// Iteration is the current workflow loop iteration (if provided by caller).
Iteration int
// Schema is the tool's JSON schema for this invocation.
Schema json.RawMessage
// Metadata allows middleware to share data with each other.
Metadata map[string]any
}
ToolContext provides metadata about the current tool call to middleware. It's stored in the context and accessible via ToolContextFromContext.
func ToolContextFromContext ¶ added in v0.11.0
func ToolContextFromContext(ctx context.Context) *ToolContext
ToolContextFromContext retrieves ToolContext from a context. Returns nil if not present.
type ToolSchema ¶
type ToolSchema = core.ToolSchema
ToolSchema describes the parameters a tool accepts. It is an alias of core.ToolSchema; the schema contract is owned by core so providers can consume it without importing this package.
Source Files