Documentation
¶
Overview ¶
Package tool defines provider-neutral tools implemented by Go functions.
A tool is declared once and installed on an Agent with adaptor.WithTools:
search := tool.Define(
"search_repo",
"Search files in the current repository.",
func(ctx context.Context, in SearchInput) (SearchOutput, error) {
return searchRepo(ctx, in.Query)
},
tool.ReadOnly(),
tool.Idempotent(),
tool.Revision("search_repo/v1"),
)
Input and output JSON Schemas are inferred from the handler's Go types. InputSchemaJSON and OutputSchemaJSON are provider-neutral escape hatches for schemas maintained outside Go. Transport, endpoint authentication, and runtime lifecycle are deliberately not part of this package's vocabulary.
Index ¶
- Variables
- func AsRejection(err error) (code, message string, ok bool)
- func Reject(code, message string) error
- type Annotations
- type Definition
- type Descriptor
- type Handler
- type Option
- func ClosedWorld() Option
- func Destructive() Option
- func Idempotent() Option
- func InputSchemaJSON(schema []byte) Option
- func NonDestructive() Option
- func OpenWorld() Option
- func OutputSchemaJSON(schema []byte) Option
- func ReadOnly() Option
- func Revision(revision string) Option
- func Title(title string) Option
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidDefinition identifies a tool declaration that cannot be // validated for installation on an Agent. ErrInvalidDefinition = errors.New("agentadaptor: invalid tool definition") // ErrInvalidInput identifies arguments that do not satisfy a tool's input // schema or cannot be decoded into its Go input type. ErrInvalidInput = errors.New("agentadaptor: invalid tool input") // ErrInvalidOutput identifies a handler result that does not satisfy its // declared output schema or cannot be encoded as JSON. ErrInvalidOutput = errors.New("agentadaptor: invalid tool output") )
Functions ¶
func AsRejection ¶
AsRejection reports whether err, or an error it wraps, was created by Reject. Only the package-private rejection type is recognized; an ordinary application error cannot opt into model-visible delivery by implementing a public method with the same shape.
func Reject ¶
Reject returns a typed, model-visible tool failure. Code should be a stable machine-readable identifier; message should explain how the caller can correct the request. Both values are trimmed; empty, malformed, or excessive values are replaced with safe defaults. Rejections are never interpreted as transport or infrastructure errors.
Types ¶
type Annotations ¶
Annotations are optional provider-neutral behavioral hints. A nil field is unspecified and must not be projected as an explicit false value. Hints are not access control and do not replace the Agent's approval policy.
type Definition ¶
type Definition interface {
// Descriptor returns the validated, deterministic tool declaration. The
// returned schema bytes are detached from the Definition.
Descriptor() (Descriptor, error)
// Invoke is the provider-neutral runtime bridge. Applications normally do
// not call it directly; Agent-owned tool runtimes use it after routing a
// provider tool call to this Definition.
Invoke(ctx context.Context, input json.RawMessage) (json.RawMessage, error)
// contains filtered or unexported methods
}
Definition is an immutable, heterogeneous tool declaration. Values can only be constructed by Define; the unexported method seals the interface so that invalid third-party implementations cannot enter the runtime.
func Define ¶
func Define[In, Out any](name, description string, handler Handler[In, Out], opts ...Option) Definition
Define declares a provider-neutral tool backed by a typed Go handler. Declaration errors are retained in the Definition and returned by Definition.Descriptor, allowing the common construction expression to stay compact while still failing deterministically before a provider is launched.
type Descriptor ¶
type Descriptor struct {
Name string
Title string
Description string
Revision string
InputSchemaJSON json.RawMessage
OutputSchemaJSON json.RawMessage
Annotations Annotations
}
Descriptor is the deterministic, transport-independent description of one validated tool. Schema slices returned by Definition.Descriptor are detached copies and may be safely modified by the caller.
type Handler ¶
Handler is the ordinary implementation shape for a tool. Implementations may be called concurrently and should honor ctx cancellation.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option changes the semantic declaration produced by Define. The interface is sealed; use the option constructors in this package.
func ClosedWorld ¶
func ClosedWorld() Option
ClosedWorld explicitly declares that the tool only interacts with a closed local domain. This differs from leaving the hint unspecified: MCP consumers otherwise default openWorldHint to true.
func Destructive ¶
func Destructive() Option
Destructive declares that the tool may make destructive changes.
func Idempotent ¶
func Idempotent() Option
Idempotent declares that repeating a call with the same arguments has no additional effect.
func InputSchemaJSON ¶
InputSchemaJSON replaces schema inference for the input type with a standard JSON Schema document. The byte slice is snapshotted immediately.
func NonDestructive ¶
func NonDestructive() Option
NonDestructive explicitly declares that the tool does not perform destructive updates. This differs from leaving the hint unspecified: MCP consumers otherwise default destructiveHint to true.
func OpenWorld ¶
func OpenWorld() Option
OpenWorld declares that the tool may interact with entities outside the Agent's local environment.
func OutputSchemaJSON ¶
OutputSchemaJSON replaces schema inference for the output type with a standard JSON Schema document. The byte slice is snapshotted immediately.
func ReadOnly ¶
func ReadOnly() Option
ReadOnly declares that the tool does not modify its environment.
Source Files