tool

README

axon-tool

Primitives · Part of the lamina workspace

Tool definition and execution primitives for LLM agents. axon-tool provides a provider-agnostic way to declare tools with typed parameter schemas and execute them within a request-scoped context. The core value is the ToolDef / ToolResult contract that any agent framework can build on, plus helpers for parsing tool calls from streaming model output.

Getting started

go get github.com/benaskins/axon-tool@latest

Requires Go 1.26+.

package main

import (
	"context"
	"fmt"

	tool "github.com/benaskins/axon-tool"
)

func main() {
	greet := tool.ToolDef{
		Name:        "greet",
		Description: "Greet someone by name.",
		Parameters: tool.ParameterSchema{
			Type:     "object",
			Required: []string{"name"},
			Properties: map[string]tool.PropertySchema{
				"name": {Type: "string", Description: "The person to greet."},
			},
		},
		Execute: func(ctx *tool.ToolContext, args map[string]any) tool.ToolResult {
			name, _ := args["name"].(string)
			return tool.ToolResult{Content: fmt.Sprintf("Hello, %s!", name)}
		},
	}

	tc := &tool.ToolContext{Ctx: context.Background()}
	result := greet.Execute(tc, map[string]any{"name": "World"})
	fmt.Println(result.Content)
}

See example/main.go for the runnable version.

Key types

• ToolDef: tool definition with name, description, parameter schema, and execute function
• ToolResult: execution result containing text content
• ToolContext: request-scoped context carrying user ID, agent slug, conversation ID
• ParameterSchema / PropertySchema: JSON Schema for tool parameters
• TextGenerator: function type for sending a prompt to an LLM and getting text back
• ToolCall: provider-agnostic representation of a tool invocation parsed from model output
• ToolCallMatcher: axon-tape matcher that detects tool-call JSON (bare or in a fenced code block) in streaming text

License

MIT. See LICENSE.

Documentation

Overview

Package tool provides primitives for defining and executing tools that can be used by LLM-powered agents. It is provider-agnostic, with no dependency on any specific LLM backend.

Class: primitive UseWhen: Always required with axon-loop. The loop drives behaviour through tool calls.

Index

• func NormalizeArguments(args map[string]any, types map[string]string) map[string]any
• type ParameterSchema
• type PropertySchema
• type TextGenerator
• type ToolCall
• type ToolCallAction
  • func (ToolCallAction) IsFilterAction()
• type ToolCallMatcher
  • func NewToolCallMatcher() *ToolCallMatcher
  • func (m *ToolCallMatcher) Extract(buf []byte) tape.FilterAction
  • func (m *ToolCallMatcher) Name() string
  • func (m *ToolCallMatcher) Scan(buf []byte, _ string) tape.MatchResult
• type ToolContext
• type ToolDef
• type ToolResult

Examples

• ToolDef

Functions

func NormalizeArguments

func NormalizeArguments(args map[string]any, types map[string]string) map[string]any

NormalizeArguments coerces tool call argument values to match the JSON Schema types declared in the tool's parameter schema. LLMs sometimes return numbers as strings, bools as strings, etc. Unknown or missing properties are left unchanged.

types maps property names to their JSON Schema type strings (e.g. "number", "boolean", "string", "array", "object").

Types

type ParameterSchema

type ParameterSchema struct {
	Type       string                    `json:"type"`
	Required   []string                  `json:"required,omitempty"`
	Properties map[string]PropertySchema `json:"properties,omitempty"`
}

ParameterSchema describes the parameters a tool accepts.

type PropertySchema

type PropertySchema struct {
	Type        string                    `json:"type"`
	Description string                    `json:"description,omitempty"`
	Enum        []any                     `json:"enum,omitempty"`
	Default     any                       `json:"default,omitempty"`
	Items       *PropertySchema           `json:"items,omitempty"`
	Properties  map[string]PropertySchema `json:"properties,omitempty"`
	Required    []string                  `json:"required,omitempty"`
}

PropertySchema describes a single parameter property using JSON Schema.

type TextGenerator

type TextGenerator func(ctx context.Context, prompt string) (string, error)

TextGenerator is a simple function that sends a prompt to an LLM and returns the response text. Used by components that need LLM capabilities without depending on a full ChatClient.

type ToolCall

type ToolCall struct {
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments"`
}

ToolCall is a provider-agnostic tool call representation.

type ToolCallAction

type ToolCallAction struct{ Calls []ToolCall }

ToolCallAction is returned when a tool call is detected in the stream.

func (ToolCallAction) IsFilterAction

func (ToolCallAction) IsFilterAction()

type ToolCallMatcher

type ToolCallMatcher struct{}

ToolCallMatcher detects tool call JSON emitted as text content.

func NewToolCallMatcher

func NewToolCallMatcher() *ToolCallMatcher

func (*ToolCallMatcher) Extract

func (m *ToolCallMatcher) Extract(buf []byte) tape.FilterAction

func (*ToolCallMatcher) Name

func (m *ToolCallMatcher) Name() string

func (*ToolCallMatcher) Scan

func (m *ToolCallMatcher) Scan(buf []byte, _ string) tape.MatchResult

type ToolContext

type ToolContext struct {
	Ctx            context.Context
	UserID         string
	Username       string
	AgentSlug      string
	ConversationID string
	SystemPrompt   string
}

ToolContext carries request-scoped state into tool execution.

type ToolDef

type ToolDef struct {
	Name        string
	Description string
	Parameters  ParameterSchema
	Execute     func(ctx *ToolContext, args map[string]any) ToolResult
}

ToolDef describes a tool that an agent can invoke.

Example

package main

import (
	"fmt"

	tool "github.com/benaskins/axon-tool"
)

func main() {
	greet := tool.ToolDef{
		Name:        "greet",
		Description: "Greet a user by name",
		Parameters: tool.ParameterSchema{
			Type:     "object",
			Required: []string{"name"},
			Properties: map[string]tool.PropertySchema{
				"name": {
					Type:        "string",
					Description: "The name of the person to greet",
				},
			},
		},
		Execute: func(ctx *tool.ToolContext, args map[string]any) tool.ToolResult {
			name, _ := args["name"].(string)
			return tool.ToolResult{Content: "Hello, " + name + "!"}
		},
	}

	fmt.Println(greet.Name)
	fmt.Println(greet.Description)
}

Output:
greet
Greet a user by name

type ToolResult

type ToolResult struct {
	Content string
}

ToolResult is the output of a tool execution.