tools

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Mar 11, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package tools provides reusable agent tool implementations.

Includes bash (sandboxed shell execution), read_url (HTML-to-markdown with pluggable ReadURLBackend, tree/section/full modes), search_web (DuckDuckGo Lite), read (file reader with line numbers), read_md (markdown-aware reader with tree/section/full modes), glob (file pattern matching), and grep (content search). Tools are constructed with their respective New* constructors or bundled via NewDefaultToolSet. Filesystem tools (read, read_md, glob, grep) require allowedPaths to be configured.

Plane: shared

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewBashTool

func NewBashTool(sbx *sandbox.Sandbox) fantasy.AgentTool

NewBashTool creates a sandboxed bash tool for use in the agent.

func NewDefaultToolSet

func NewDefaultToolSet(sbx *sandbox.Sandbox, fetchBackend ReadURLBackend, allowedPaths []string, treeThreshold int) []fantasy.AgentTool

NewDefaultToolSet creates the standard tool set: bash, read_url, search_web. Optionally adds read, read_md, glob, grep when allowedPaths is non-empty. Panics if sbx or fetchBackend is nil.

func NewGlobTool

func NewGlobTool(allowedPaths []string) fantasy.AgentTool

NewGlobTool creates a glob tool restricted to the given allowed paths.

func NewGrepTool

func NewGrepTool(allowedPaths []string) fantasy.AgentTool

NewGrepTool creates a content search tool restricted to the given allowed paths.

func NewReadMDTool

func NewReadMDTool(allowedPaths []string, treeThreshold int) fantasy.AgentTool

NewReadMDTool creates a markdown-aware file reader. Small files (≤ treeThreshold chars) return full content by default. Large files return a heading tree. Agent can override with tree/full/section flags.

func NewReadTool

func NewReadTool(allowedPaths []string) fantasy.AgentTool

NewReadTool creates a file-reading tool restricted to the given allowed paths. Access to files outside allowedPaths is denied.

func NewReadURLTool

func NewReadURLTool(backend ReadURLBackend, treeThreshold int) fantasy.AgentTool

NewReadURLTool creates a URL fetch tool using the provided backend. backend controls how HTML is fetched and converted:

  • BrowserGatewayBackend: POST to browser-gateway /api/extract (for server use)
  • DefuddleCLIBackend: shell out to `defuddle parse <url> --markdown` (for local/CLI use)
  • DirectFetchBackend: plain HTTP + html-to-markdown (fallback)

func NewSearchWebTool

func NewSearchWebTool(client *http.Client) fantasy.AgentTool

NewSearchWebTool creates a web search tool using DuckDuckGo Lite.

Types

type BashParams

type BashParams struct {
	Command     string `json:"command"     description:"The bash command to execute"`
	Description string `json:"description" description:"Brief description of what the command does"`
}

BashParams are the input parameters for the bash tool.

type GlobParams

type GlobParams struct {
	Pattern string `json:"pattern" description:"Glob pattern to match files (e.g. '**/*.go', 'src/**/*.ts')"`                                    //nolint:lll
	Path    string `json:"path,omitempty" description:"Directory to search in (must be within allowed paths; empty = search all allowed paths)"` //nolint:lll
}

GlobParams are the input parameters for the glob tool.

type GrepParams

type GrepParams struct {
	Pattern string `json:"pattern" description:"Regex pattern to search for"`
	Path    string `` //nolint:lll
	/* 131-byte string literal not displayed */
	Glob string `json:"glob,omitempty" description:"File glob filter (e.g. '*.go')"`
}

GrepParams are the input parameters for the grep tool.

type ReadMDParams

type ReadMDParams struct {
	FilePath string `json:"file_path" description:"Absolute path to the markdown file to read"`
	Tree     bool   `json:"tree,omitempty" description:"Force tree view (heading structure + char counts)"`
	Section  string `json:"section,omitempty" description:"Section ID to extract (use tree view first to see IDs)"`
	Full     bool   `json:"full,omitempty" description:"Force full content even for large files"`
}

ReadMDParams are the input parameters for the read_md tool.

type ReadParams

type ReadParams struct {
	FilePath string `json:"file_path" description:"Absolute path to the file to read"`
	Offset   int    `json:"offset,omitempty" description:"Line number to start reading from (0-based)"`
	Limit    int    `json:"limit,omitempty" description:"Number of lines to read (default 2000)"`
}

ReadParams are the input parameters for the read tool.

type ReadURLBackend

type ReadURLBackend interface {
	Fetch(ctx context.Context, url string) (content string, err error)
}

ReadURLBackend controls how HTML is fetched and converted to markdown.

func NewBrowserGatewayBackend

func NewBrowserGatewayBackend(gatewayURL string, client *http.Client) ReadURLBackend

NewBrowserGatewayBackend creates a backend that fetches via browser-gateway. Falls back to direct HTTP fetch on any gateway error.

func NewDefuddleCLIBackend

func NewDefuddleCLIBackend() ReadURLBackend

NewDefuddleCLIBackend creates a backend that shells out to the defuddle CLI. Requires defuddle to be installed and on PATH.

func NewDirectFetchBackend

func NewDirectFetchBackend(client *http.Client) ReadURLBackend

NewDirectFetchBackend creates a backend that fetches via plain HTTP. HTML responses are converted to markdown using html-to-markdown.

type ReadURLParams

type ReadURLParams struct {
	URL     string `json:"url" description:"The URL to fetch content from"`
	Tree    bool   `json:"tree,omitempty" description:"Force tree view regardless of content size"`
	Section string `json:"section,omitempty" description:"Section ID to extract (use tree view first to see IDs)"`
	Full    bool   `json:"full,omitempty" description:"Force full content (truncated at 30k chars)"`
}

ReadURLParams are the input parameters for the read_url tool.

type RichToolInfo

type RichToolInfo struct {
	Name        string
	Description string
}

RichToolInfo holds a tool's name and full .md description for system prompt injection. Defined here (not in agentloop) to avoid circular import.

func RichToolDescriptions

func RichToolDescriptions(allTools []fantasy.AgentTool) []RichToolInfo

RichToolDescriptions returns rich descriptions for the given tools. Only includes tools that are in the provided slice (matched by name). Falls back to the tool's schema description if no .md file is found.

type SearchResult

type SearchResult struct {
	Title    string
	Link     string
	Snippet  string
	Position int
}

SearchResult represents a single search result from DuckDuckGo.

type SearchWebParams

type SearchWebParams struct {
	Query      string `json:"query" description:"The search query"`
	MaxResults int    `json:"max_results,omitempty" description:"Maximum number of results (default 10, max 20)"`
}

SearchWebParams are the input parameters for the search_web tool.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL