tools

Documentation

Overview

Package tools / functioncalls.go handles function calls, or tools, in chat API. Allows external packages to register functions that AI can request to be executed.

Index

• Variables
• type CustomToolFormat
• type FunctionCall
• type MCPApprovalList
  • func (al MCPApprovalList) MarshalJSON() ([]byte, error)
• type Registry
  • func (r *Registry) CountFunctions() int
  • func (r *Registry) CountTools() int
  • func (r *Registry) CreateFunction(fc FunctionCall) error
  • func (r *Registry) DeleteFunction(name string) error
  • func (r *Registry) DeleteTool(name string) error
  • func (r *Registry) GetFunction(name string) (FunctionCall, bool)
  • func (r *Registry) GetTool(name string) (Tool, bool)
  • func (r *Registry) RegisterTool(tool Tool) error
• type Tool
• type ToolChoiceOption
  • func (tco ToolChoiceOption) MarshalJSON() ([]byte, error)
• type UserLocation

Variables

var (
	// ErrDoNotRespond is to be returned by an AI function when it has completed its work
	// and wishes to prevent the AI from any further actions.
	ErrDoNotRespond = errors.New("function call indicated that further communication with AI is not needed")

	// TextDoNotRespond is a string that can be returned by a function to AI to indicate
	// that further communication is not needed for this function.
	TextDoNotRespond = "Function was executed successfully and requested to end this line of interaction. Do not respond further in this regard."
)

var EmptyParamsSchema = []byte(`{"type":"object","properties":{}}`)

EmptyParamsSchema is a minimal schema for function calls with no parameters that API would accept.

Types

type CustomToolFormat

type CustomToolFormat struct {
	Type       string `json:"type"`
	Syntax     string `json:"syntax,omitempty"`
	Definition string `json:"definition,omitempty"`
}

CustomToolFormat represents the `format` object for custom tools. When Type is "grammar", Syntax must be "lark" or "regex" and Definition must be set.

type FunctionCall

type FunctionCall struct {
	Name         string          `json:"name"` // ^[a-zA-Z0-9_-]{1,64}$
	Description  string          `json:"description"`
	ParamsSchema json.RawMessage `json:"parameters"`

	// forces AI to follow JSON schema strictly, false by default
	// additional limitations for schema apply if set to true:
	// https://platform.openai.com/docs/guides/structured-outputs/supported-schemas
	Strict bool `json:"strict,omitempty"`

	// the function to be executed, if nil then the function call will be returned
	// instead of being executed
	F func(params json.RawMessage) (string, error) `json:"-"`

	// the function will be used no more than this number of times at once
	// and then non-function response is forced
	CallLimit int `json:"-"` // default 0, unlimited
}

FunctionCall reperesents a function that AI can request to be executed. All fields except F and CallLimit are required. If F is not provided, calls to this function will be returned instead of being executed. Name must be unique. Description will be used by AI to understand what the function does. ParamsSchema must countain a valid JSON schema object for the params that F will accept. F can return any string but for any complex data an encoded JSON object is preferred. CallLimit is the maximum number of times the function can be used at once before non-function response is forced (0 is unlimited).

type MCPApprovalList

type MCPApprovalList struct {
	Always []string `json:"always,omitempty"`
	Never  []string `json:"never,omitempty"`
}

MCPApprovalList is a list of MCP tool approval rules. It is marshalled as required by the API but filled in a simplified way.

func (MCPApprovalList) MarshalJSON

func (al MCPApprovalList) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. Marshals "always" and "never" lists as objects with "tool_names" field.

type Registry

type Registry struct {
	sync.RWMutex
	FunctionCalls map[string]FunctionCall
	Tools         map[string]Tool
}

Registry holds user-defined tools that AI can request to use.

func (*Registry) CountFunctions

func (r *Registry) CountFunctions() int

CountFunctions returns the number of registered functions.

func (*Registry) CountTools

func (r *Registry) CountTools() int

CountTools returns the number of registered tools.

func (*Registry) CreateFunction

func (r *Registry) CreateFunction(fc FunctionCall) error

CreateFunction creates a function that can be added to AI request to be run as needed. To allow AI to call a function in a particular request, add the function name to the request's "functions" field.

func (*Registry) DeleteFunction

func (r *Registry) DeleteFunction(name string) error

DeleteFunction deletes a function from the registry.

func (*Registry) DeleteTool

func (r *Registry) DeleteTool(name string) error

DeleteTool deletes a tool from the registry.

func (*Registry) GetFunction

func (r *Registry) GetFunction(name string) (FunctionCall, bool)

GetFunction returns a registered function by its name. Returns false if the function is not registered.

func (*Registry) GetTool

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

GetTool returns a registered tool by its name.

func (*Registry) RegisterTool

func (r *Registry) RegisterTool(tool Tool) error

RegisterTool registers a tool that can be used by the model. To allow the model to use a tool in a particular request, add the tool to the request's "tools" field.

type Tool

type Tool struct {
	// Type of tool: "function", "file_search", "web_search" (and preview), "computer_use_preview",
	// "mcp", "local_shell", "code_interpreter", "shell", "apply_patch"
	Type string `json:"type"`

	// Name of the tool
	Name string `json:"name,omitempty"`
	// Description of the tool
	Description string `json:"description,omitempty"`
	// Parameters schema
	Parameters json.RawMessage `json:"parameters,omitempty"`
	// Whether to enforce strict schema validation
	Strict bool `json:"strict,omitempty"`
	// Underlying FunctionCall (not sent to API)
	Function FunctionCall `json:"-"`

	// Custom tool execution handler. If nil, calls will be returned instead of executed.
	Custom func(input string) (string, error) `json:"-"`

	// Optional input format constraints for custom tools. Follows API schema.
	// Use type "text" for unconstrained text, or type "grammar" with Syntax and Definition.
	Format *CustomToolFormat `json:"format,omitempty"`

	// Vector store IDs for file_search type
	VectorStoreIDs []string `json:"vector_store_ids,omitempty"`
	// Max number of results for file_search type
	MaxNumResults int `json:"max_num_results,omitempty"`
	// Filters for selecting files, see documentation:
	// https://platform.openai.com/docs/guides/tools-file-search#metadata-filtering
	// https://platform.openai.com/docs/guides/retrieval#attribute-filtering
	Filters any `json:"filters,omitempty"`

	// Display dimensions for computer_use_preview type
	DisplayWidth  int `json:"display_width,omitempty"`
	DisplayHeight int `json:"display_height,omitempty"`
	// Environment for computer_use_preview type
	Environment string `json:"environment,omitempty"`

	// A label for this MCP server, used to identify it in tool calls.
	ServerLabel string `json:"server_label,omitempty"`
	// The URL for the MCP server.
	ServerURL string `json:"server_url,omitempty"`
	// Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.
	Headers http.Header `json:"headers,omitempty"`
	// List of allowed tool names.
	// TODO: it also can be a filter object but it's functionally same as just []string. Add if it allows something more in future.
	AllowedTools []string `json:"allowed_tools,omitempty"`
	// Specify which of the MCP server's tools require approval. Defaults to always.
	// Either "always", or "never", or MCPApprovalList.
	RequireApproval any `json:"require_approval,omitempty"`

	// High level guidance for the amount of context window space to use for the search.
	// One of low, medium, or high. medium is the default.
	SearchContextSize string `json:"search_context_size,omitempty"`

	// User location object
	UserLocation *UserLocation `json:"user_location,omitempty"`

	// The code interpreter container. Can be a container ID or an object that specifies uploaded
	// file IDs to make available to your code:
	//  {"type": "auto", "file_ids": []string}
	// Note that the field itself is required but the list of IDs is optional:
	//  {"type": "auto"}
	Container any `json:"container,omitempty"`
}

Tool represents a tool that can be used by the model.

type ToolChoiceOption

type ToolChoiceOption string

ToolChoiceOption represents a choice of tool to be forced for use by AI.

func (ToolChoiceOption) MarshalJSON

func (tco ToolChoiceOption) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type UserLocation

type UserLocation struct {
	// Always `approximate`
	Type string `json:"type"`
	// Free text input for the city of the user, e.g. "San Francisco"
	City string `json:"city,omitempty"`
	// The two-letter ISO country code, e.g. "US"
	Country string `json:"country,omitempty"`
	// Free text input for the region of the user, e.g. "California"
	Region string `json:"region,omitempty"`
	// The timezone of the user, e.g. "America/Los_Angeles"
	Timezone string `json:"timezone,omitempty"`
}

UserLocation represents a user's location.