tools

Documentation

Index

• func ListBuiltins() []string
• func RegisterBuiltin(name string, factory ToolFactory)
• type ErrToolNotBuiltin
  • func (e ErrToolNotBuiltin) Error() string
• type Parameter
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Execute(ctx context.Context, name string, input json.RawMessage) (json.RawMessage, error)
  • func (r *Registry) Get(name string) (Tool, bool)
  • func (r *Registry) Has(name string) bool
  • func (r *Registry) List() []string
  • func (r *Registry) Register(t Tool)
  • func (r *Registry) Schemas() map[string]Schema
• type Schema
  • func SchemaForBuiltin(name string) (Schema, bool)
• type Tool
  • func Resolve(name string, cfg ToolConfig) (Tool, error)
• type ToolCall
• type ToolConfig
• type ToolFactory

Functions

func ListBuiltins

func ListBuiltins() []string

ListBuiltins returns the names of all registered built-in tools. Used by the CLI's `routex tools list` command.

func RegisterBuiltin

func RegisterBuiltin(name string, factory ToolFactory)

RegisterBuiltin registers a factory function for a built-in tool name. Called once per tool — typically in an init() function or at package level.

This is how the CLI and auto-discovery work: when agents.yaml lists "web_search", the runtime calls builtinRegistry["web_search"](cfg) to get a ready Tool.

Usage (inside tools/web_search.go):

func init() {
    RegisterBuiltin("web_search", func(cfg ToolConfig) (Tool, error) {
        return WebSearch(), nil
    })
}

Types

type ErrToolNotBuiltin

type ErrToolNotBuiltin struct {
	Name string
}

ErrToolNotBuiltin is returned by Resolve when the tool name is not found in the built-in registry. The runtime catches this and checks the manual registry next — so custom tools registered via rt.RegisterTool() still work.

func (ErrToolNotBuiltin) Error

func (e ErrToolNotBuiltin) Error() string

type Parameter

type Parameter struct {
	// Type is the JSON type: "string", "number", "boolean", "array", "object"
	Type string

	// Description tells the LLM what this field is for.
	// Be specific — the LLM fills this in based on your description.
	Description string

	// Required marks whether the LLM must include this field.
	// Missing required fields cause the tool call to be rejected.
	Required bool
}

Parameter describes a single input field in a tool's Schema.

type Registry

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

Registry holds all tools that have been registered with the runtime. Agents look up tools here by name when the LLM requests a tool call. You never interact with Registry directly — use rt.RegisterTool() instead.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty tool registry.

func (*Registry) Execute

func (r *Registry) Execute(ctx context.Context, name string, input json.RawMessage) (json.RawMessage, error)

Execute runs a tool by name with the given input. Called by the agent's goroutine when the LLM requests a tool call. Returns a clear error if the tool is not registered — agents log this and report it back to the LLM so it can try something else.

func (*Registry) Get

func (r *Registry) Get(name string) (Tool, bool)

Get retrieves a tool by name. Returns the tool and true if found, nil and false if not. Agents call this when the LLM returns a tool_use block.

func (*Registry) Has

func (r *Registry) Has(name string) bool

Has reports whether a tool with the given name is registered.

func (*Registry) List

func (r *Registry) List() []string

List returns the names of all registered tools. The runtime passes these to the LLM at the start of each agent run so the model knows what it has available.

func (*Registry) Register

func (r *Registry) Register(t Tool)

Register adds a tool to the registry. If a tool with the same name already exists, it is replaced. This is called by rt.RegisterTool() — you rarely call it directly.

func (*Registry) Schemas

func (r *Registry) Schemas() map[string]Schema

Schemas returns the Schema for every registered tool. The runtime serialises these into the format each LLM provider expects.

type Schema

type Schema struct {
	// Description is a plain-English explanation of what the tool does.
	// Write this as if explaining to a smart colleague, not a machine.
	// The LLM uses this to decide WHEN to call your tool.
	// Bad:  "searches"
	// Good: "Search the web and return the top results for a given query"
	Description string

	// Parameters describes the JSON object the LLM must send to Execute().
	// Each key is a parameter name, each value describes that parameter.
	// The LLM will construct the input JSON to match this shape.
	Parameters map[string]Parameter
}

Schema describes a tool to the LLM. The runtime serialises this into the function-calling format that Anthropic, OpenAI, and Ollama all understand.

You fill this out once per tool. The LLM reads it at runtime to understand what inputs your tool accepts.

func SchemaForBuiltin

func SchemaForBuiltin(name string) (Schema, bool)

SchemaForBuiltin returns the schema for a built-in tool by name without constructing the full tool. Used by the CLI tools list command. Returns false if the tool is not registered or has no schema available.

type Tool

type Tool interface {
	// Name returns the unique identifier for this tool.
	// This is what the LLM uses to call it, and what you write
	// in agents.yaml under tools: ["web_search"].
	// Keep it lowercase with underscores. No spaces.
	// Example: "web_search", "write_file", "db_query"
	Name() string

	// Schema describes the tool to the LLM so it knows:
	//   - what the tool does
	//   - what inputs it expects
	//   - what it returns
	// The LLM reads this and decides when and how to call the tool.
	// Think of it as the tool's instruction manual for the AI.
	Schema() Schema

	// Execute is called when the LLM decides to use this tool.
	// input is the raw JSON the LLM produced — your tool parses it.
	// The return value is raw JSON sent back to the LLM as the tool result.
	// ctx carries the deadline and cancellation from the runtime.
	// If Execute returns an error, the agent logs it and may retry.
	Execute(ctx context.Context, input json.RawMessage) (json.RawMessage, error)
}

Tool is the contract every tool in Routex must satisfy.

To create a custom tool:

1. Create a struct
2. Add Name(), Schema(), and Execute() methods
3. Call rt.RegisterTool(&YourTool{})

func Resolve

func Resolve(name string, cfg ToolConfig) (Tool, error)

Resolve tries to instantiate a built-in tool by name. Returns the Tool if found and successfully created. Returns ErrToolNotBuiltin if the name is not a built-in — the caller should then look for a manually registered tool.

type ToolCall

type ToolCall struct {
	// ToolName matches the name returned by Tool.Name().
	ToolName string

	// Input is the raw JSON the LLM passed to Tool.Execute().
	Input string

	// Output is the raw JSON Tool.Execute() returned.
	// Empty if the tool call failed.
	Output string

	// Duration is how long Tool.Execute() took to complete.
	Duration time.Duration

	// Error is non-nil if Tool.Execute() returned an error.
	Error error
}

ToolCall is a record of a single tool execution by an agent. Stored in AgentResult.ToolCalls so you can see exactly what the agent did, what input it sent, what came back, and how long it took.

type ToolConfig

type ToolConfig struct {
	// Name is the tool's registered name — e.g. "web_search"
	Name string

	// APIKey is an optional API key for tools that need one.
	// Read from the env var specified in agents.yaml, or directly set.
	// Example: api_key: "env:BRAVE_API_KEY"
	APIKey string

	// BaseDir is used by file tools to restrict where they can write.
	// Example: base_dir: "./outputs"
	BaseDir string

	// MaxResults controls how many results search tools return.
	MaxResults int

	// Extra holds any additional tool-specific settings from the YAML
	// that do not fit the standard fields above.
	Extra map[string]string
}

ToolConfig holds configuration passed to a tool factory when the runtime auto-instantiates a built-in tool. Values come from the tools: section of agents.yaml.

type ToolFactory

type ToolFactory func(cfg ToolConfig) (Tool, error)

ToolFactory is a function that creates a Tool instance. Built-in tools register a factory under their name. The factory receives a Config so tools can read API keys and settings without hardcoding them.