tool

Documentation

Overview

Package tool defines provider-neutral tool vocabulary shared by AgentSlot tool contracts and adapters.

Index

• Constants
• Variables
• type Call
• type Definition
  • func (d Definition) Validate() error
• type InputSchema
  • func ParseInputSchema(raw []byte) (InputSchema, error)
  • func (s InputSchema) JSON() json.RawMessage
  • func (s InputSchema) MarshalJSON() ([]byte, error)
  • func (s *InputSchema) UnmarshalJSON(raw []byte) error
  • func (s InputSchema) ValidateArguments(raw []byte) error
• type ParallelSafety
  • func (s ParallelSafety) Valid() bool
• type ResultStatus
• type StructuredError
• type Tool
• type ToolInvocation
• type ToolResult
  • func (r ToolResult) Validate() error
  • func (r ToolResult) ValidateWithin(maxInlineOutputBytes int) error

Constants

const (
	// InputSchemaDialect is the fixed schema vocabulary for model-facing tool
	// arguments. JSON Schema 2020-12 schemas are usable as OpenAPI 3.1 Schema
	// Objects without making every tool an HTTP API.
	InputSchemaDialect = "https://json-schema.org/draft/2020-12/schema"
)

Variables

var (
	// ErrInvalidInputSchema reports a tool input schema outside AgentSlot's
	// self-contained portable envelope.
	ErrInvalidInputSchema = errors.New("invalid tool input schema")
	// ErrInvalidArguments reports call arguments that are not valid JSON or do
	// not conform to their tool's InputSchema.
	ErrInvalidArguments = errors.New("invalid tool arguments")
)

var ToolSlot = agentslot.Many[Tool]("tool")

ToolSlot is the standard model-callable tool ecosystem.

Types

type Call

type Call struct {
	ID        agent.ToolCallID
	Name      string
	Arguments json.RawMessage
}

Call is one model-requested tool invocation. Arguments are JSON instance values that must conform to the Definition's InputSchema; they are not a schema document.

type Definition

type Definition struct {
	Name        string
	Description string
	InputSchema InputSchema
}

Definition is the provider-neutral, model-facing description of one tool.

func (Definition) Validate

func (d Definition) Validate() error

Validate checks whether a definition can be advertised to a model.

type InputSchema

type InputSchema struct {
	// contains filtered or unexported fields
}

InputSchema is a detached, canonical JSON representation of a tool's named arguments. The root is always a closed object schema. Provider adapters may impose smaller keyword or size subsets but may not reinterpret the schema.

func ParseInputSchema

func ParseInputSchema(raw []byte) (InputSchema, error)

ParseInputSchema validates the portable AgentSlot envelope and returns a detached canonical representation. Full instance validation remains the responsibility of the tool invocation boundary.

func (InputSchema) JSON

func (s InputSchema) JSON() json.RawMessage

JSON returns a detached copy of the canonical schema document.

func (InputSchema) MarshalJSON

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

MarshalJSON preserves the canonical schema in durable Context snapshots. Credentials and execution state are not part of InputSchema.

func (*InputSchema) UnmarshalJSON

func (s *InputSchema) UnmarshalJSON(raw []byte) error

UnmarshalJSON recompiles the canonical schema so a restored Definition has exactly the same validation behavior as the in-memory original.

func (InputSchema) ValidateArguments

func (s InputSchema) ValidateArguments(raw []byte) error

ValidateArguments verifies one JSON argument value against the compiled input schema. Provider adapters and invocation runtimes use the same method so schema enforcement cannot drift between model protocols.

type ParallelSafety

type ParallelSafety string

ParallelSafety controls whether the fixed dispatcher may place calls in the same execution batch.

const (
	ParallelSafe ParallelSafety = "parallel_safe"
	Serial       ParallelSafety = "serial"
)

func (ParallelSafety) Valid

func (s ParallelSafety) Valid() bool

Valid reports whether a tool declares one supported scheduling mode.

type ResultStatus

type ResultStatus string

ResultStatus is intentionally small and independent of process exit codes.

const (
	ResultSucceeded ResultStatus = "succeeded"
	ResultFailed    ResultStatus = "failed"
	ResultUnknown   ResultStatus = "outcome_unknown"
)

type StructuredError

type StructuredError struct {
	Code    string
	Message string
}

StructuredError is safe to expose in model context. Internal causes remain in logs and are never copied into this value.

type Tool

type Tool interface {
	Definition() Definition
	ParallelSafety() ParallelSafety
	Invoke(context.Context, ToolInvocation) ToolResult
}

Tool is one independently replaceable model-callable capability.

type ToolInvocation

type ToolInvocation struct {
	Call        Call
	SessionID   agent.SessionID
	AgentID     agent.AgentID
	WorkspaceID agent.WorkspaceID
	// Actor is the trusted caller identity assigned by the fixed Runtime. For
	// model-requested tools it is the current Agent, never a model argument.
	Actor agent.ActorIdentity
	// WorkspaceBoundary is the opaque binding returned by an installed
	// Workspace Manager. It is nil when the optional Manager is absent.
	WorkspaceBoundary workspace.Boundary
	// MaxInlineOutputBytes is the exact byte budget for ToolResult.Output.
	// Tools may use a lower limit or persist full content before returning.
	MaxInlineOutputBytes int
	RunID                agent.RunID
	StepID               agent.StepID
}

ToolInvocation contains stable execution identity and already schema-validated arguments. AgentID and WorkspaceID are trusted values derived from the authoritative Session; model-supplied arguments cannot replace them. The invocation does not expose Runtime, SessionStore, or Gateway internals.

type ToolResult

type ToolResult struct {
	CallID agent.ToolCallID
	Status ResultStatus
	Output json.RawMessage
	Error  *StructuredError
	// Artifacts are stable references to immutable content already committed
	// through an ArtifactStore before this result is returned.
	Artifacts []artifact.Metadata
}

ToolResult is the structured durable outcome passed back to the model.

func (ToolResult) Validate

func (r ToolResult) Validate() error

Validate ensures a result has exactly one terminal status and a matching structured error when it failed.

func (ToolResult) ValidateWithin

func (r ToolResult) ValidateWithin(maxInlineOutputBytes int) error

ValidateWithin validates the durable result and enforces the exact inline byte budget supplied with the invocation. It never truncates or rewrites the result.