Documentation
¶
Overview ¶
Package tools provides the tool plugin system for Forge agents. Tools are capabilities that an LLM agent can invoke during execution.
Index ¶
- func InputSpecToSchema(spec string) json.RawMessage
- func ToLLMDefinition(t Tool) llm.ToolDefinition
- type Category
- type CommandExecutor
- type CustomTool
- func (t *CustomTool) Category() Category
- func (t *CustomTool) Description() string
- func (t *CustomTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
- func (t *CustomTool) InputSchema() json.RawMessage
- func (t *CustomTool) Name() string
- func (t *CustomTool) ValidateEntrypoint(basedir string) error
- type DiscoveredTool
- type MCPSource
- type NetworkPolicy
- type Registry
- func (r *Registry) Execute(ctx context.Context, name string, arguments json.RawMessage) (string, error)
- func (r *Registry) Filter(allowed []string) *Registry
- func (r *Registry) Get(name string) Tool
- func (r *Registry) List() []string
- func (r *Registry) Register(t Tool) error
- func (r *Registry) Remove(name string)
- func (r *Registry) ToolDefinitions() []llm.ToolDefinition
- type SkillTool
- type Tool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InputSpecToSchema ¶
func InputSpecToSchema(spec string) json.RawMessage
InputSpecToSchema converts a skill InputSpec string (e.g. "input (string), model (string)") into a JSON Schema object. The first parameter is marked as required. Falls back to an open schema if parsing fails.
func ToLLMDefinition ¶
func ToLLMDefinition(t Tool) llm.ToolDefinition
ToLLMDefinition converts a Tool to an llm.ToolDefinition for use with LLM APIs.
Types ¶
type CommandExecutor ¶
type CommandExecutor interface {
Run(ctx context.Context, command string, args []string, stdin []byte) (stdout string, err error)
}
CommandExecutor abstracts command execution for custom tools.
type CustomTool ¶
type CustomTool struct {
// contains filtered or unexported fields
}
CustomTool wraps a discovered script as a Tool implementation. It delegates execution to an injected CommandExecutor rather than calling os/exec directly, keeping this package free of OS dependencies.
func NewCustomTool ¶
func NewCustomTool(dt DiscoveredTool, executor CommandExecutor) *CustomTool
NewCustomTool creates a tool wrapper for a discovered script. If executor is nil, Execute will return an error.
func (*CustomTool) Category ¶
func (t *CustomTool) Category() Category
func (*CustomTool) Description ¶
func (t *CustomTool) Description() string
func (*CustomTool) Execute ¶
func (t *CustomTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
func (*CustomTool) InputSchema ¶
func (t *CustomTool) InputSchema() json.RawMessage
func (*CustomTool) Name ¶
func (t *CustomTool) Name() string
func (*CustomTool) ValidateEntrypoint ¶
func (t *CustomTool) ValidateEntrypoint(basedir string) error
ValidateEntrypoint checks that the entrypoint is safe to execute: - Not empty or absolute - Does not contain path traversal (..) - Resolves (via symlinks) to a path within basedir - Is a regular file
type DiscoveredTool ¶
DiscoveredTool represents a tool found via filesystem discovery.
func DiscoverToolsFS ¶
func DiscoverToolsFS(fsys fs.FS) []DiscoveredTool
DiscoverToolsFS scans the given fs.FS for tool scripts/modules. It looks for:
- tool_*.py, tool_*.ts, tool_*.js files
- */tool.py, */tool.ts, */tool.js subdirectories
type MCPSource ¶
type MCPSource interface {
Tool
MCPSource() // marker — body is empty
}
MCPSource is an optional interface signalling that a tool was discovered from an MCP server. The registry uses this to permit "__" in the tool's name — that separator is reserved for the namespaced form "<server-name>__<tool-name>" so MCP tools cannot collide with builtin or adapter tool names. Tools that do NOT implement MCPSource are rejected at registration time if their name contains "__".
Implementing this is a single no-op method; see forge-core/tools/adapters/mcp_tool.go.
type NetworkPolicy ¶
type NetworkPolicy struct {
AllowedHosts []string `json:"allowed_hosts,omitempty"`
DenyAll bool `json:"deny_all,omitempty"`
}
NetworkPolicy describes network requirements for registered tools.
func GenerateNetworkPolicy ¶
func GenerateNetworkPolicy(reg *Registry) NetworkPolicy
GenerateNetworkPolicy scans registered tools and generates a network policy.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is a thread-safe tool registry. It implements engine.ToolExecutor via Go structural typing -- no direct import of the engine package is needed.
func (*Registry) Execute ¶
func (r *Registry) Execute(ctx context.Context, name string, arguments json.RawMessage) (string, error)
Execute runs the named tool with the given arguments. This method satisfies the engine.ToolExecutor interface.
func (*Registry) Filter ¶
Filter returns a new Registry containing only tools whose names are in the allowed list. This is useful for Command to restrict which tools are available at runtime.
func (*Registry) Register ¶
Register adds a tool to the registry. Returns an error if a tool with the same name is already registered.
Tool names containing "__" are reserved for MCP-discovered tools (the "<server>__<tool>" namespaced form). Non-MCP tools that try to use that separator are rejected — this prevents a builtin from accidentally shadowing an MCP tool's namespace. MCP tools must implement the MCPSource marker interface to opt in.
func (*Registry) ToolDefinitions ¶
func (r *Registry) ToolDefinitions() []llm.ToolDefinition
ToolDefinitions returns LLM tool definitions for all registered tools. This method satisfies the engine.ToolExecutor interface.
type SkillTool ¶
type SkillTool struct {
// contains filtered or unexported fields
}
SkillTool wraps a parsed skill entry as a Tool. It delegates execution to a CommandExecutor, running the skill's script with JSON input as a positional argument.
func NewSkillTool ¶
func NewSkillTool(name, description, inputSpec, scriptPath string, executor CommandExecutor) *SkillTool
NewSkillTool creates a tool wrapper for a skill entry backed by a shell script.
func (*SkillTool) Description ¶
func (*SkillTool) InputSchema ¶
func (t *SkillTool) InputSchema() json.RawMessage
type Tool ¶
type Tool interface {
// Name returns the unique tool name.
Name() string
// Description returns a human-readable description of the tool.
Description() string
// Category returns the tool's category.
Category() Category
// InputSchema returns the JSON Schema for the tool's input parameters.
InputSchema() json.RawMessage
// Execute runs the tool with the given JSON arguments.
Execute(ctx context.Context, args json.RawMessage) (string, error)
}
Tool is the interface that all tools must implement.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adapters provides tools that call out to external systems.
|
Package adapters provides tools that call out to external systems. |
|
Package builtins provides built-in tools available to all agents.
|
Package builtins provides built-in tools available to all agents. |