tools

type AudioContent ¶

type AudioContent = MediaContent

AudioContent is an alias kept for readability at call sites.

type ChangeNotifier ¶

type ChangeNotifier interface {
	SetToolsChangedHandler(handler func())
}

ChangeNotifier is implemented by toolsets that can notify when their tool list changes (e.g. after an MCP ToolListChanged notification).

type Describer ¶

type Describer interface {
	Describe() string
}

Describer can be implemented by a ToolSet to provide a short, user-visible description that uniquely identifies the toolset instance (e.g. for use in error messages and warnings). The string must never contain secrets.

type Elicitable ¶

type Elicitable interface {
	SetElicitationHandler(handler ElicitationHandler)
}

Elicitable is implemented by toolsets that support MCP elicitation.

type ElicitationAction ¶

type ElicitationAction string

const (
	ElicitationActionAccept  ElicitationAction = "accept"
	ElicitationActionDecline ElicitationAction = "decline"
	ElicitationActionCancel  ElicitationAction = "cancel"
)

type ElicitationHandler ¶

type ElicitationHandler func(ctx context.Context, req *mcp.ElicitParams) (ElicitationResult, error)

ElicitationHandler is a function type that handles elicitation requests from the MCP server This allows the runtime to handle elicitation requests and propagate them to its own client

type ElicitationResult ¶

type ElicitationResult struct {
	Action  ElicitationAction `json:"action"`
	Content map[string]any    `json:"content,omitempty"`
}

type FunctionCall ¶

type FunctionCall struct {
	Name      string `json:"name,omitempty"`
	Arguments string `json:"arguments,omitempty"`
}

type ImageContent ¶

type ImageContent = MediaContent

ImageContent is an alias kept for readability at call sites.

type Instructable ¶

type Instructable interface {
	Instructions() string
}

Instructable is implemented by toolsets that provide custom instructions.

type MediaContent ¶

type MediaContent struct {
	// Data is the base64-encoded payload.
	Data string `json:"data"`
	// MimeType identifies the content type (e.g. "image/png", "audio/wav").
	MimeType string `json:"mimeType"`
}

MediaContent represents base64-encoded binary data (image, audio, etc.) returned by a tool.

type OAuthCapable ¶

type OAuthCapable interface {
	SetOAuthSuccessHandler(handler func())
	SetManagedOAuth(managed bool)
}

OAuthCapable is implemented by toolsets that support OAuth flows.

type Startable ¶

type Startable interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

Startable is implemented by toolsets that require initialization before use. Toolsets that don't implement this interface are assumed to be ready immediately.

type StartableToolSet ¶

type StartableToolSet struct {
	ToolSet
	// contains filtered or unexported fields
}

StartableToolSet wraps a ToolSet with lazy, single-flight start semantics. This is the canonical way to manage toolset lifecycle.

Failure and recovery tracking:

• freshFailure is set to true on the first Start() failure in a streak (i.e. when hasEverFailed transitions false→true). It is consumed by ShouldReportFailure() which returns true exactly once per streak.
• hasEverFailed stays true for the duration of the failure streak.
• pendingRecovery is set to true on the first successful Start() after a failure streak. It is consumed by ConsumeRecovery().
• ConsumeRecovery() also resets hasEverFailed, so the next failure streak generates a fresh warning.

func NewStartable(ts ToolSet) *StartableToolSet

func (s *StartableToolSet) ConsumeRecovery() bool

func (s *StartableToolSet) IsStarted() bool

func (s *StartableToolSet) ShouldReportFailure() bool

func (s *StartableToolSet) Start(ctx context.Context) error

func (s *StartableToolSet) Stop(ctx context.Context) error

func (s *StartableToolSet) Unwrap() ToolSet

type Tool ¶

type Tool struct {
	Name                    string          `json:"name"`
	Category                string          `json:"category"`
	Description             string          `json:"description,omitempty"`
	Parameters              any             `json:"parameters"`
	Annotations             ToolAnnotations `json:"annotations"`
	OutputSchema            any             `json:"outputSchema"`
	Handler                 ToolHandler     `json:"-"`
	AddDescriptionParameter bool            `json:"-"`
	// ModelOverride is the per-toolset model for the LLM turn that processes
	// this tool's results. Set automatically from the toolset "model" field.
	ModelOverride string `json:"-"`
}

func AddDescriptionParameter(toolList []Tool) []Tool

func (t *Tool) DisplayName() string

type ToolAnnotations ¶

type ToolAnnotations mcp.ToolAnnotations

type ToolCall ¶

type ToolCall struct {
	ID       string       `json:"id,omitempty"`
	Type     ToolType     `json:"type"`
	Function FunctionCall `json:"function"`
}

type ToolCallResult ¶

type ToolCallResult struct {
	Output  string `json:"output"`
	IsError bool   `json:"isError,omitempty"`
	Meta    any    `json:"meta,omitempty"`
	// Images contains optional image attachments returned by the tool.
	Images []MediaContent `json:"images,omitempty"`
	// Audios contains optional audio attachments returned by the tool.
	Audios []MediaContent `json:"audios,omitempty"`
	// StructuredContent holds optional structured output returned by an MCP
	// tool whose definition includes an OutputSchema. When non-nil it is the
	// JSON-decoded structured result from the server.
	StructuredContent any `json:"structuredContent,omitempty"`
}

func ResultError(output string) *ToolCallResult

func ResultJSON(v any) *ToolCallResult

func ResultSuccess(output string) *ToolCallResult

type ToolHandler ¶

type ToolHandler func(ctx context.Context, toolCall ToolCall) (*ToolCallResult, error)

func NewHandler[T any](fn func(context.Context, T) (*ToolCallResult, error)) ToolHandler

type ToolSet ¶

type ToolSet interface {
	Tools(ctx context.Context) ([]Tool, error)
}

ToolSet defines the interface for a set of tools.

type ToolType ¶

type ToolType string

type ToolsetMetadata ¶

type ToolsetMetadata interface {
	ToolsetID() string
}

ToolsetMetadata exposes optional details for toolset identification. Implemented by toolsets that can provide additional context for warnings.

type Unwrapper ¶

type Unwrapper interface {
	Unwrap() ToolSet
}

Unwrapper is implemented by toolset wrappers that decorate another ToolSet. This allows As to walk the wrapper chain and find inner capabilities.