agenttool

package module
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2026 License: MIT Imports: 14 Imported by: 13

README

agenttool

The tool contract for Go agents over Open Responses: what a tool is, how a typed Go function becomes one, how its JSON Schema is generated and validated, how a batch of calls executes, and MCP adapters in both directions. It is the contract that agentturn runs and that any other loop can run; no loop is imported here.

  • The root module depends on openresponses and the standard library.
  • mcpclient and mcpserver are nested modules on the official MCP Go SDK.

Install

go get github.com/ChristopherDavenport/agenttool

Go 1.25 or later.

A tool

type ReadFileArgs struct {
	Path     string `json:"path" desc:"Absolute path to read"`
	MaxBytes int    `json:"max_bytes,omitempty" desc:"Stop after this many bytes"`
}

var ReadFile = agenttool.New("read_file", "Read a file from disk",
	func(ctx context.Context, a ReadFileArgs) (string, error) {
		b, err := os.ReadFile(a.Path)
		if err != nil {
			return "", err
		}
		return string(b), nil
	})

New reflects the schema from the argument struct at registration time. The generator understands json, desc and enum tags, nested structs, slices, maps, pointers and time.Time, and produces the strict form on request (WithStrict(): every field required, additionalProperties: false, pointers nullable). Arguments are validated against that schema before the function runs, so a missing required property or a value outside an enum reaches the model as an error it can retry on rather than a zero value.

The return type decides what the model sees: a string as text, openresponses.Contents as parts, so image-returning tools need no second constructor, and anything else as JSON. Errors returned from the function become error outputs; a tool never encodes an error as content.

The contract

type Tool interface {
	Name() string
	Description() string
	Parameters() json.RawMessage
	Execute(ctx context.Context, call Call) (Result, error)
}

Call carries the call ID, the raw arguments and an optional progress callback; Result carries the output the model sees, app-only Details, and a Terminate hint. On error the model sees the error and the output is ignored. Details that implement Recordable, one method naming a namespace, can be written to a session by a recorder that does not know their type: RecordOf gives the namespace and the value's JSON. Two optional interfaces refine a tool: Sequential forces a batch containing it to run one call at a time, and Strict marks its schema strict; WithSequential() and WithStrict() set them on a tool from New or NewFunc. NewFunc builds a tool from plain values and a raw function for schemas that come from elsewhere; SchemaFor[T]() gives the schema New would reflect; Set is a list with lookup; Definition produces the openresponses.FunctionTool for a request.

A batch

Executor runs a batch: parallel up to a bound, or sequential when asked. Events are yielded from the caller's goroutine, so a consumer never sees two at once.

jobs := []agenttool.Job{{Tool: ReadFile, Call: agenttool.Call{ID: call.ID, Args: call.Arguments}}}
outputs := make([]agenttool.Result, len(jobs))
for ev := range (agenttool.Executor{MaxParallel: 4}).Execute(ctx, jobs) {
	switch {
	case !ev.Final:
		show(ev.Result) // progress the tool reported through Call.Update
	case ev.Err != nil:
		outputs[ev.Index] = agenttool.ErrorResult(ev.Err)
	default:
		outputs[ev.Index] = ev.Result
	}
}

An Event names its job by Index. It is Final exactly once per job, carrying the Result or the Err, and completions arrive in completion order, not job order. A tool that panics completes with a PanicError whose message is one line; the stack is on the value for errors.As. Results is the shortcut when progress is not needed. A loop that owns its own scheduling needs only the interface.

MCP

The native contract is the centre and MCP is an edge: an MCP tool is a name, a description, an input schema and a call over a transport, which is a subset of Tool. Both adapters use github.com/modelcontextprotocol/go-sdk and map, nothing more.

// Consume: a remote server's tools as Tool values.
s, err := mcpclient.Connect(ctx, &mcp.CommandTransport{Command: cmd}, mcpclient.WithPrefix("fs"))
tools := s.Tools() // fs__read, fs__write, ...

// Serve: Go tools over MCP.
server, err := mcpserver.NewServer("my-tools", "0.1.0", ReadFile)
err = server.Run(ctx, &mcp.StdioTransport{})

mcpclient maps text, image, audio and resource content to output parts, isError to a returned error, progress notifications to the call's progress callback, and refreshes its snapshot on tool-list-changed. The refresh is a round trip: Await blocks until it has landed, and a call that returns after the notification arrived waits for it, so a tool that adds a tool usually returns with the list already current. mcpserver validates arguments against each tool's schema, maps outputs back to MCP content and forwards progress when the request carries a token. make interop checks both against the upstream reference server and the MCP Inspector over stdio.

Development

make check    # gofmt, vet, deps, staticcheck, govulncheck, race tests, every module
make interop  # upstream MCP interoperability; needs npx and the network

See CONTRIBUTING.md.

License

MIT. See LICENSE.

Documentation

Overview

Package agenttool is the tool contract for Go agents over Open Responses: what a tool is, how a typed Go function becomes one, how its JSON Schema is generated and validated, and how a batch of calls executes.

The package imports openresponses and the standard library only, so a tool written with New can be handed to any loop that speaks Open Responses. agentturn is one such loop and depends on this module; the reverse never holds, and a test enforces the boundary. The MCP adapters, mcpclient and mcpserver, are nested modules that map to and from this contract. 

type ReadFileArgs struct {
	Path     string `json:"path" desc:"Absolute path to read"`
	MaxBytes int    `json:"max_bytes,omitempty" desc:"Stop after this many bytes"`
}

var ReadFile = agenttool.New("read_file", "Read a file from disk",
	func(ctx context.Context, a ReadFileArgs) (string, error) { ... })

Errors returned from Execute become error outputs the model sees; a tool never encodes an error as normal content.

Index

Constants

View Source 
const DefaultMaxParallel = 8

DefaultMaxParallel bounds concurrent tool calls in a batch when the caller sets no limit.

Variables

This section is empty.

Functions

func Decode 

func Decode[T any](raw json.RawMessage) (T, error)

Decode unmarshals the raw arguments into T. Empty arguments decode as an empty object. Errors are phrased for the model.

func Definition 

func Definition(t Tool) *openresponses.FunctionTool

Definition builds the function tool that describes t on a request.

func IsSequential 

func IsSequential(t Tool) bool

IsSequential reports whether t asks to run alone.

func IsStrict 

func IsStrict(t Tool) bool

IsStrict reports whether t's schema is strict.

func Progress 

func Progress(ctx context.Context, r Result)

Progress reports progress on the call attached to ctx. It is a no-op when there is no call or the caller did not ask for updates.

func SchemaFor 

func SchemaFor[T any](opts ...Option) (json.RawMessage, error)

SchemaFor returns the JSON Schema for T. See SchemaOf.

func SchemaOf 

func SchemaOf(t reflect.Type, opts ...Option) (json.RawMessage, error)

SchemaOf returns the JSON Schema object New would use for an argument type t: the one t supplies when it implements Schemer, otherwise the reflected schema of Reflect. Of the options only WithStrict applies, and not to a Schemer's own schema.

Exported fields become properties named by their json tag. A "desc" tag becomes the description and an "enum" tag, comma separated, becomes the enum. Embedded structs are flattened under encoding/json's rules: of several fields promoted under one name the shallowest wins, a tagged one wins among equals, and the rest of a tie is dropped as the encoder would drop it. Supported kinds are bool, the integer and float kinds, string, slices and arrays, maps with string keys, nested structs, pointers, time.Time (a date-time string), []byte (a string), json.RawMessage and interfaces (any value) and types implementing encoding.TextMarshaler (a string).

In strict mode every property is required, additionalProperties is false on every object, pointer fields are nullable, and maps are rejected because strict mode cannot express them.

Outside strict mode a field is optional when its tag says omitempty or omitzero or when it is a pointer.

func WithCall 

func WithCall(ctx context.Context, call Call) context.Context

WithCall attaches the call to ctx so the tool function can find it with CallFrom. A New tool does this before calling its function.

Types

type Call 

type Call struct {
	// ID is the call_id of the function_call item.
	ID string
	// Args is the raw JSON arguments object as the model wrote it.
	Args json.RawMessage
	// OnUpdate, when set, receives progress before the final result. It
	// may be called from the tool's goroutine; the caller serialises it.
	OnUpdate func(Result)
}

Call is one invocation of a tool.

func CallFrom 

func CallFrom(ctx context.Context) (Call, bool)

CallFrom returns the call attached to ctx, if any.

func (Call) Update 

func (c Call) Update(r Result)

Update reports progress to the caller when it asked for it.

type Event 

type Event struct {
	Index  int
	Final  bool
	Result Result
	Err    error
}

Event is one step of a batch: a progress update when Final is false, otherwise the completion of the job at Index. Completions arrive in completion order, not job order.

type Executor 

type Executor struct {
	// MaxParallel bounds concurrency; zero means [DefaultMaxParallel].
	MaxParallel int
	// Sequential forces every batch to run one job at a time in order.
	// A batch containing a [Sequential] tool runs that way regardless.
	Sequential bool
}

Executor runs batches of tool calls.

func (Executor) Execute 

func (e Executor) Execute(ctx context.Context, jobs []Job) iter.Seq[Event]

Execute runs jobs and yields their events from the caller's goroutine, so a consumer never sees two events at once. Progress updates from a tool that calls Call.OnUpdate are forwarded as non-final events; the executor installs its own OnUpdate and chains to the one on the job, if any, from the yielding goroutine. A tool that panics completes with an error. Breaking out of the loop cancels the batch and waits for running tools to return.

func (Executor) Results 

func (e Executor) Results(ctx context.Context, jobs []Job) ([]Result, []error)

Results collects the final results of a batch in job order. It is the convenience over Executor.Execute for callers that do not need progress.

type Job 

type Job struct {
	Tool Tool
	Call Call
}

Job is one call of a batch: the tool to run and the call to run it with.

type NoArgs 

type NoArgs struct{}

NoArgs is the argument type of a tool that takes no arguments.

type Option 

type Option func(*options)

Option configures a tool built by New or NewFunc, or a schema from Reflect, SchemaOf and SchemaFor. Each says which options apply to it.

func WithParameters 

func WithParameters(schema json.RawMessage) Option

WithParameters replaces the reflected schema of a New tool with schema. Arguments are then not validated before decoding, because the tool cannot know what the schema promises.

func WithSequential 

func WithSequential() Option

WithSequential marks the tool Sequential.

func WithStrict 

func WithStrict() Option

WithStrict generates the schema under the strict rules and sets the strict flag on the function tool.

func WithoutValidation 

func WithoutValidation() Option

WithoutValidation skips a New tool's argument check against the reflected schema, leaving the decoder as the only guard.

type PanicError added in v0.0.3 

type PanicError struct {
	Tool  string
	Value any
	Stack []byte
}

PanicError is the error a job completes with when its tool panicked. Error reports the tool and the panic value in one line, which is what the model sees; the stack is kept for hosts and subscribers that recover it with errors.As, and never reaches the conversation.

func (*PanicError) Error added in v0.0.3 

func (e *PanicError) Error() string

type ProgressInfo added in v0.0.3 

type ProgressInfo struct {
	Progress float64
	Total    float64
	Message  string
}

ProgressInfo, when set as the Details of a progress update, carries the numbers behind it: how far the tool is, out of how much, and a message. The fields mirror the MCP progress notification so the two adapters forward it in either direction; a tool with no numbers to report leaves Details unset and sends text alone.

type Property 

type Property struct {
	Name   string
	Schema *Schema
}

Property is one named member of an object schema.

type Record added in v0.0.5 

type Record struct {
	NS   string
	Data json.RawMessage
}

Record is the durable form of a Recordable Details value: the namespace and the JSON a recorder writes under it.

func RecordOf added in v0.0.5 

func RecordOf(details any) (*Record, error)

RecordOf returns the record of details when it implements Recordable, and nil when it is nil or any other value, which is not an error: most Details are for subscribers in the same process. An empty namespace or a value that does not marshal is an error.

type Recordable added in v0.0.5 

type Recordable interface {
	RecordNS() string
}

Recordable is implemented by a Details value that is meant to outlive the run. A recorder that does not know the type can still write it, as a namespaced JSON entry beside the call it came from, through RecordOf. RecordNS names the entry's namespace, "owner:kind" by convention, and must not be empty. The data is the value's JSON as json.Marshal produces it, so a type shapes it with MarshalJSON like anywhere else; a MarshalJSON on a pointer receiver applies only when Details holds the pointer. Details for in-process subscribers alone, such as ProgressInfo or a live handle, do not implement it and are not recorded.

type Result 

type Result struct {
	// Output is what the model sees.
	Output openresponses.FunctionCallOutputData
	// Details is app-only data for subscribers and fronts. It is never
	// sent to the model. A value that implements [Recordable] can also
	// be written to a session by a recorder that does not know its
	// type; see [RecordOf].
	Details any
	// Terminate hints that the loop should stop after this batch instead
	// of calling the model again. The loop honours it only when every
	// result in the batch sets it.
	Terminate bool
}

Result is what a tool produced.

func ErrorResult 

func ErrorResult(err error) Result

ErrorResult builds the output the model sees when a tool fails. The text form is "Error: <message>" so the model can tell it apart from a normal result and retry.

func Output 

func Output(v any) (Result, error)

Output converts a Go value into a Result following the rules of New.

func Parts 

func Parts(parts ...openresponses.Content) Result

Parts builds a result whose output is a list of content parts.

func Text 

func Text(s string) Result

Text builds a result whose output is a string.

type Schema 

type Schema struct {
	// Type is a JSON Schema type name, or empty for any value.
	Type string
	// Nullable adds "null" to the type, as strict mode requires for
	// optional fields.
	Nullable    bool
	Description string
	Format      string
	Enum        []any
	Properties  []Property
	Required    []string
	// AdditionalProperties and NoAdditional share the JSON key
	// "additionalProperties". NoAdditional emits false and wins when both
	// are set, as strict mode requires; AdditionalProperties emits a
	// schema for the values of a map. Neither set, the key is omitted and
	// unknown properties are allowed.
	AdditionalProperties *Schema
	NoAdditional         bool
	Items                *Schema
}

Schema is a JSON Schema fragment as the generator builds it. Keys are emitted in a fixed order and properties keep struct field order, so the output is stable across runs and readable in a request.

The type can be built by hand for Schema.Validate. A nil or empty slice is omitted from the JSON, so a hand-built object schema emits "properties" and "required" only when they are set, while the generator sets both to empty slices and always emits them. Type "" accepts any value.

func Reflect 

func Reflect(t reflect.Type, opts ...Option) (*Schema, error)

Reflect returns the schema tree that SchemaOf serialises, for callers that want to validate with it. t must be a struct or a pointer to one; Schemer is not consulted, since a Schemer supplies JSON, not a tree. Of the options only WithStrict applies.

func (Schema) MarshalJSON 

func (s Schema) MarshalJSON() ([]byte, error)

MarshalJSON emits the schema with a fixed key order. The receiver is a value so that a Schema value, on its own or inside another struct, marshals the same way as a pointer; the validate methods take a pointer because a nil Items or AdditionalProperties accepts anything.

func (*Schema) Validate 

func (s *Schema) Validate(v any) error

Validate checks a decoded JSON value (maps, slices, strings, json.Number or float64, bools, nil) against s: its type, enum, required properties, additionalProperties when false, and its items and properties recursively. A schema with no Type accepts anything; one whose Type is not a JSON Schema type name accepts nothing, so a misspelt hand-built schema fails on its first use rather than silently passing everything.

func (*Schema) ValidateJSON 

func (s *Schema) ValidateJSON(raw json.RawMessage) error

ValidateJSON checks raw against s. Empty raw is an empty object.

type Schemer 

type Schemer interface {
	JSONSchema() json.RawMessage
}

Schemer is implemented by argument types that supply their own JSON Schema instead of the reflected one.

type Sequential 

type Sequential interface {
	Sequential() bool
}

Sequential is implemented by tools that must not run alongside other tools in the same batch. When any tool in a batch reports true, the whole batch runs one call at a time in the model's order.

type Set 

type Set []Tool

Set is a list of tools with lookup by name.

func (Set) Definitions 

func (s Set) Definitions() openresponses.Tools

Definitions returns the function tools for a request, in order.

func (Set) Lookup 

func (s Set) Lookup(name string) (Tool, bool)

Lookup returns the tool named name.

func (Set) Validate 

func (s Set) Validate() error

Validate reports an empty or duplicate name.

type Strict 

type Strict interface {
	Strict() bool
}

Strict is implemented by tools whose schema was generated under the strict rules (every field required, additionalProperties false, optional fields nullable). The flag is set on the function tool.

type Tool 

type Tool interface {
	Name() string
	Description() string
	// Parameters is the JSON Schema of the arguments object. nil means
	// the tool takes no arguments.
	Parameters() json.RawMessage
	// Execute runs one call. On error the model sees the error and
	// Result.Output is ignored; Result.Details may still be set for
	// subscribers, as mcpclient does with the raw MCP result.
	Execute(ctx context.Context, call Call) (Result, error)
}

Tool is something the model can call. Name and Parameters become the function tool on the request; Execute runs one call.

func New 

func New[Args, Out any](name, description string, fn func(context.Context, Args) (Out, error), opts ...Option) Tool

New builds a Tool from a typed function. The schema is reflected from Args at registration time (see SchemaOf); a type that cannot be expressed panics here rather than at call time, like a bad regexp in regexp.MustCompile. Call.Args is validated against that schema, so a missing required property, a wrong type or a value outside an enum is returned as an error the model can retry on, then decoded into Args with the standard decoder. Properties the schema does not name are ignored, or rejected under WithStrict, whose schema says so.

Validation covers reflected schemas only. When Args implements Schemer or the schema comes from WithParameters, the tool cannot know what the schema promises, so arguments go straight to the decoder; WithoutValidation asks for the same on a reflected one.

Out maps to the output the model sees: a string passes through as text, openresponses.Contents goes out as parts, a Result or an openresponses.FunctionCallOutputData is used as is, and anything else is marshalled to JSON.

The function can reach its Call through CallFrom on the context, for the call ID or to report progress.

func NewFunc added in v0.0.3 

func NewFunc(name, description string, parameters json.RawMessage, fn func(ctx context.Context, call Call) (Result, error), opts ...Option) Tool

NewFunc builds a Tool from plain values and a function that takes the raw call: the untyped counterpart of New for tools whose schema comes from elsewhere, such as a remote server. parameters is served verbatim and never validated; nil means the tool takes no arguments. WithStrict and WithSequential apply; the options that shape a reflected schema do not. A nil fn panics here, like a bad schema in New.

type ValidationError 

type ValidationError struct {
	// Path locates the offending value: "" for the root, otherwise a
	// dotted property path with [i] for array elements.
	Path string
	Msg  string
}

ValidationError reports arguments that do not satisfy a schema. Its message is phrased for the model, which sees it as the error output and can retry.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Error returns "invalid arguments: <path>: <msg>".

Source Files

View all Source files

Directories

Path Synopsis
mcpclient module
mcpserver module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.