tools

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultMaxToolOutputBytes int64 = 1 << 20 // 1 MiB

DefaultMaxToolOutputBytes caps how much a single tool call may return.

Variables

This section is empty.

Functions

This section is empty.

Types

type CalculatorTool 

type CalculatorTool struct{}

CalculatorTool implements basic mathematical calculations

func NewCalculatorTool 

func NewCalculatorTool() *CalculatorTool

NewCalculatorTool creates a new calculator tool

func (*CalculatorTool) Execute 

func (t *CalculatorTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*CalculatorTool) GetConfig 

func (t *CalculatorTool) GetConfig() map[string]interface{}

func (*CalculatorTool) GetDefinition 

func (t *CalculatorTool) GetDefinition() llm.ToolDefinition

func (*CalculatorTool) GetDescription 

func (t *CalculatorTool) GetDescription() string

func (*CalculatorTool) GetName 

func (t *CalculatorTool) GetName() string

func (*CalculatorTool) SetConfig 

func (t *CalculatorTool) SetConfig(config map[string]interface{}) error

func (*CalculatorTool) Validate 

func (t *CalculatorTool) Validate(args string) error

type FileListTool 

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

FileListTool implements directory listing functionality

func NewFileListTool 

func NewFileListTool() *FileListTool

NewFileListTool creates a new file list tool. Listing is confined to the policy's allowed roots.

func (*FileListTool) Execute 

func (t *FileListTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*FileListTool) GetConfig 

func (t *FileListTool) GetConfig() map[string]interface{}

func (*FileListTool) GetDefinition 

func (t *FileListTool) GetDefinition() llm.ToolDefinition

func (*FileListTool) GetDescription 

func (t *FileListTool) GetDescription() string

func (*FileListTool) GetName 

func (t *FileListTool) GetName() string

func (*FileListTool) SetConfig 

func (t *FileListTool) SetConfig(config map[string]interface{}) error

func (*FileListTool) SetSecurityPolicy 

func (t *FileListTool) SetSecurityPolicy(p *SecurityPolicy)

SetSecurityPolicy replaces the tool's security policy.

func (*FileListTool) Validate 

func (t *FileListTool) Validate(args string) error

type FileReadTool 

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

FileReadTool implements file reading functionality

func NewFileReadTool 

func NewFileReadTool() *FileReadTool

NewFileReadTool creates a new file read tool.

Reads are confined to the policy's allowed roots. An extension allowlist on its own is not a boundary: ".json" and ".yaml" files outside the working directory include kubeconfigs, container registry credentials and cloud credential files.

func (*FileReadTool) Execute 

func (t *FileReadTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*FileReadTool) GetConfig 

func (t *FileReadTool) GetConfig() map[string]interface{}

func (*FileReadTool) GetDefinition 

func (t *FileReadTool) GetDefinition() llm.ToolDefinition

func (*FileReadTool) GetDescription 

func (t *FileReadTool) GetDescription() string

func (*FileReadTool) GetName 

func (t *FileReadTool) GetName() string

func (*FileReadTool) SetConfig 

func (t *FileReadTool) SetConfig(config map[string]interface{}) error

func (*FileReadTool) SetSecurityPolicy 

func (t *FileReadTool) SetSecurityPolicy(p *SecurityPolicy)

SetSecurityPolicy replaces the tool's security policy.

func (*FileReadTool) Validate 

func (t *FileReadTool) Validate(args string) error

type FileWriteTool 

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

FileWriteTool implements file writing functionality

func NewFileWriteTool 

func NewFileWriteTool() *FileWriteTool

NewFileWriteTool creates a new file write tool. Writes are confined to the policy's allowed roots.

func (*FileWriteTool) Execute 

func (t *FileWriteTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*FileWriteTool) GetConfig 

func (t *FileWriteTool) GetConfig() map[string]interface{}

func (*FileWriteTool) GetDefinition 

func (t *FileWriteTool) GetDefinition() llm.ToolDefinition

func (*FileWriteTool) GetDescription 

func (t *FileWriteTool) GetDescription() string

func (*FileWriteTool) GetName 

func (t *FileWriteTool) GetName() string

func (*FileWriteTool) SetConfig 

func (t *FileWriteTool) SetConfig(config map[string]interface{}) error

func (*FileWriteTool) SetSecurityPolicy 

func (t *FileWriteTool) SetSecurityPolicy(p *SecurityPolicy)

SetSecurityPolicy replaces the tool's security policy.

func (*FileWriteTool) Validate 

func (t *FileWriteTool) Validate(args string) error

type GenericTool 

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

GenericTool is a generic implementation of the Tool interface

func NewGenericTool 

func NewGenericTool(name, description string, executor ToolExecutor, parameters map[string]interface{}) *GenericTool

NewGenericTool creates a new generic tool

func (*GenericTool) Execute 

func (t *GenericTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*GenericTool) GetConfig 

func (t *GenericTool) GetConfig() map[string]interface{}

func (*GenericTool) GetDefinition 

func (t *GenericTool) GetDefinition() llm.ToolDefinition

func (*GenericTool) GetDescription 

func (t *GenericTool) GetDescription() string

func (*GenericTool) GetName 

func (t *GenericTool) GetName() string

func (*GenericTool) SetConfig 

func (t *GenericTool) SetConfig(config map[string]interface{}) error

func (*GenericTool) Validate 

func (t *GenericTool) Validate(args string) error

type HTTPTool 

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

HTTPTool implements HTTP request functionality

func NewHTTPTool 

func NewHTTPTool() *HTTPTool

NewHTTPTool creates a new HTTP tool.

The request URL comes from a language model, so it is treated as untrusted: requests to loopback, private and link-local addresses are refused by default, which blocks server-side request forgery against internal services and the cloud instance metadata endpoint. The check is applied at dial time and on every redirect hop, so a hostname that resolves to an internal address is caught even if it resolved elsewhere a moment earlier.

func (*HTTPTool) Execute 

func (t *HTTPTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*HTTPTool) GetConfig 

func (t *HTTPTool) GetConfig() map[string]interface{}

func (*HTTPTool) GetDefinition 

func (t *HTTPTool) GetDefinition() llm.ToolDefinition

func (*HTTPTool) GetDescription 

func (t *HTTPTool) GetDescription() string

func (*HTTPTool) GetName 

func (t *HTTPTool) GetName() string

func (*HTTPTool) SetConfig 

func (t *HTTPTool) SetConfig(config map[string]interface{}) error

func (*HTTPTool) SetSecurityPolicy 

func (t *HTTPTool) SetSecurityPolicy(p *SecurityPolicy)

SetSecurityPolicy replaces the tool's security policy and rebuilds its client.

func (*HTTPTool) Validate 

func (t *HTTPTool) Validate(args string) error

type SecurityPolicy 

type SecurityPolicy struct {

	// AllowedRoots are absolute directories the file tools may operate within.
	// Empty means the process working directory and the system temp directory.
	AllowedRoots []string

	// MaxOutputBytes caps command output and HTTP response bodies.
	MaxOutputBytes int64

	// AllowedCommands is the shell command allowlist.
	AllowedCommands []string

	// DeniedArgSubstrings reject shell arguments that can execute other
	// programs even when the base command is allowed.
	DeniedArgSubstrings []string

	// AllowPrivateNetwork permits requests to loopback, link-local and private
	// address ranges. Off by default: those ranges hold cloud metadata services
	// and internal admin endpoints.
	AllowPrivateNetwork bool

	// AllowedHosts, when non-empty, restricts HTTP requests to these hosts.
	AllowedHosts []string

	// MaxRedirects bounds HTTP redirect following.
	MaxRedirects int
	// contains filtered or unexported fields
}

SecurityPolicy bounds what the built-in tools may touch.

Tool arguments are chosen by a language model, which may be steered by untrusted input, so every tool that reaches the filesystem, a shell or the network is treated as attacker-controlled and constrained here.

func DefaultSecurityPolicy 

func DefaultSecurityPolicy() *SecurityPolicy

DefaultSecurityPolicy returns the policy applied to tools built with the New*Tool constructors.

func (*SecurityPolicy) CheckCommand 

func (p *SecurityPolicy) CheckCommand(parts []string) error

CheckCommand validates a shell invocation against the allowlist and rejects arguments that would let an allowed command run something else.

func (*SecurityPolicy) CheckURL 

func (p *SecurityPolicy) CheckURL(raw string) (*url.URL, error)

CheckURL validates a request target before any connection is made.

func (*SecurityPolicy) HTTPClient 

func (p *SecurityPolicy) HTTPClient(timeout time.Duration) *http.Client

HTTPClient builds a client that enforces the policy on every connection and every redirect hop.

func (*SecurityPolicy) LimitedRead 

func (p *SecurityPolicy) LimitedRead(r interface{ Read([]byte) (int, error) }) ([]byte, bool, error)

LimitedRead reads at most the policy's output cap, reporting truncation.

func (*SecurityPolicy) ResolvePath 

func (p *SecurityPolicy) ResolvePath(path string) (string, error)

ResolvePath validates a caller-supplied path and returns its cleaned absolute form. Symlinks are resolved so a link inside an allowed root cannot be used to reach a file outside one; for a path that does not exist yet, the nearest existing parent is checked instead so new files can still be created.

func (*SecurityPolicy) SetAllowedRoots 

func (p *SecurityPolicy) SetAllowedRoots(roots []string)

SetAllowedRoots replaces the directories file tools may operate within.

type ShellTool 

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

ShellTool implements shell command execution

func NewShellTool 

func NewShellTool() *ShellTool

NewShellTool creates a new shell tool.

The previous default allowlist included "find", "cat" and "grep". A command allowlist cannot contain those: "find -exec" runs arbitrary programs, and "cat"/"grep" read any file the process can reach, so the allowlist provided no real boundary. The default set is now restricted, arguments that can execute other programs are rejected, and output is capped.

func (*ShellTool) Execute 

func (t *ShellTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*ShellTool) GetConfig 

func (t *ShellTool) GetConfig() map[string]interface{}

func (*ShellTool) GetDefinition 

func (t *ShellTool) GetDefinition() llm.ToolDefinition

func (*ShellTool) GetDescription 

func (t *ShellTool) GetDescription() string

func (*ShellTool) GetName 

func (t *ShellTool) GetName() string

func (*ShellTool) SetConfig 

func (t *ShellTool) SetConfig(config map[string]interface{}) error

func (*ShellTool) SetSecurityPolicy 

func (t *ShellTool) SetSecurityPolicy(p *SecurityPolicy)

SetSecurityPolicy replaces the tool's security policy.

func (*ShellTool) Validate 

func (t *ShellTool) Validate(args string) error

type TimeTool 

type TimeTool struct{}

TimeTool implements time-related functionality

func NewTimeTool 

func NewTimeTool() *TimeTool

NewTimeTool creates a new time tool

func (*TimeTool) Execute 

func (t *TimeTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*TimeTool) GetConfig 

func (t *TimeTool) GetConfig() map[string]interface{}

func (*TimeTool) GetDefinition 

func (t *TimeTool) GetDefinition() llm.ToolDefinition

func (*TimeTool) GetDescription 

func (t *TimeTool) GetDescription() string

func (*TimeTool) GetName 

func (t *TimeTool) GetName() string

func (*TimeTool) SetConfig 

func (t *TimeTool) SetConfig(config map[string]interface{}) error

func (*TimeTool) Validate 

func (t *TimeTool) Validate(args string) error

type Tool 

type Tool interface {
	// GetName returns the tool name
	GetName() string

	// GetDescription returns the tool description
	GetDescription() string

	// GetDefinition returns the LLM tool definition
	GetDefinition() llm.ToolDefinition

	// Execute executes the tool with the given arguments
	Execute(ctx context.Context, args string) (interface{}, error)

	// Validate validates the tool arguments
	Validate(args string) error

	// GetConfig returns the tool configuration
	GetConfig() map[string]interface{}

	// SetConfig updates the tool configuration
	SetConfig(config map[string]interface{}) error
}

Tool represents a tool that can be executed by agents

type ToolExecutor 

type ToolExecutor func(ctx context.Context, args map[string]interface{}) (interface{}, error)

ToolExecutor is a function that executes a tool

type ToolRegistry 

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

ToolRegistry manages a collection of tools

func NewToolRegistry 

func NewToolRegistry() *ToolRegistry

NewToolRegistry creates a new tool registry

func (*ToolRegistry) GetAllDefinitions 

func (tr *ToolRegistry) GetAllDefinitions() []llm.ToolDefinition

GetAllDefinitions returns all tool definitions for LLM

func (*ToolRegistry) GetDefinitions 

func (tr *ToolRegistry) GetDefinitions(toolNames []string) []llm.ToolDefinition

GetDefinitions returns tool definitions for specific tools

func (*ToolRegistry) GetTool 

func (tr *ToolRegistry) GetTool(name string) (Tool, bool)

GetTool returns a tool by name

func (*ToolRegistry) ListTools 

func (tr *ToolRegistry) ListTools() []string

ListTools returns all registered tool names

func (*ToolRegistry) RegisterTool 

func (tr *ToolRegistry) RegisterTool(tool Tool) error

RegisterTool registers a tool

func (*ToolRegistry) UnregisterTool 

func (tr *ToolRegistry) UnregisterTool(name string) error

UnregisterTool unregisters a tool

type WebSearchTool 

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

WebSearchTool implements web search functionality

func NewWebSearchTool 

func NewWebSearchTool() *WebSearchTool

NewWebSearchTool creates a new web search tool

func (*WebSearchTool) Execute 

func (t *WebSearchTool) Execute(ctx context.Context, args string) (interface{}, error)

func (*WebSearchTool) GetConfig 

func (t *WebSearchTool) GetConfig() map[string]interface{}

func (*WebSearchTool) GetDefinition 

func (t *WebSearchTool) GetDefinition() llm.ToolDefinition

func (*WebSearchTool) GetDescription 

func (t *WebSearchTool) GetDescription() string

func (*WebSearchTool) GetName 

func (t *WebSearchTool) GetName() string

func (*WebSearchTool) SetConfig 

func (t *WebSearchTool) SetConfig(config map[string]interface{}) error

func (*WebSearchTool) Validate 

func (t *WebSearchTool) Validate(args string) error

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.