Help us shape the future of Go! Take the 2026 Go Developer Survey

tools

package
v1.33.5 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package tools is the public SDK facade over Harbor's internal/tools package — the transport-agnostic tool catalog, the descriptor/policy vocabulary, and the planner-facing catalog view (RFC §3.6, §6.10). Alias-based re-exports only: no behavior lives here. The policy execution shell, invoke hooks, error classification, search-cache seam, and event payload structs are deliberately private.

Index

Constants

View Source 
const (
	// ErrClassTransient — retryable infrastructure failures.
	ErrClassTransient = internal.ErrClassTransient
	// ErrClassTimeout — the per-attempt deadline elapsed.
	ErrClassTimeout = internal.ErrClassTimeout
	// ErrClass5xx — server-side 5xx failures.
	ErrClass5xx = internal.ErrClass5xx
	// ErrClassPermanent — non-retryable failures.
	ErrClassPermanent = internal.ErrClassPermanent
)

ErrorClass values.

View Source 
const (
	// LoadingAlways — the tool is always visible to the planner.
	LoadingAlways = internal.LoadingAlways
	// LoadingDeferred — the tool is discovered via tool_search.
	LoadingDeferred = internal.LoadingDeferred
)

LoadingMode values.

View Source 
const (
	// SideEffectPure — no side effects.
	SideEffectPure = internal.SideEffectPure
	// SideEffectRead — reads external state.
	SideEffectRead = internal.SideEffectRead
	// SideEffectWrite — writes external state.
	SideEffectWrite = internal.SideEffectWrite
	// SideEffectExternal — calls an external system.
	SideEffectExternal = internal.SideEffectExternal
	// SideEffectStateful — mutates durable state.
	SideEffectStateful = internal.SideEffectStateful
)

SideEffect values.

View Source 
const (
	// TransportInProcess — an in-process Go function tool.
	TransportInProcess = internal.TransportInProcess
	// TransportHTTP — an HTTP endpoint tool.
	TransportHTTP = internal.TransportHTTP
	// TransportMCP — a southbound MCP server tool.
	TransportMCP = internal.TransportMCP
	// TransportA2A — a southbound A2A remote-agent tool.
	TransportA2A = internal.TransportA2A
	// TransportFlow — a typed DAG registered as one Tool.
	TransportFlow = internal.TransportFlow
)

TransportKind values.

View Source 
const (
	// ValidateNone — no schema validation.
	ValidateNone = internal.ValidateNone
	// ValidateBoth — validate args and results.
	ValidateBoth = internal.ValidateBoth
	// ValidateIn — validate args only.
	ValidateIn = internal.ValidateIn
	// ValidateOut — validate results only.
	ValidateOut = internal.ValidateOut
)

ValidateMode values.

View Source 
const (
	// EventTypeToolInvoked — a tool invocation started.
	EventTypeToolInvoked = internal.EventTypeToolInvoked
	// EventTypeToolCompleted — a tool invocation succeeded.
	EventTypeToolCompleted = internal.EventTypeToolCompleted
	// EventTypeToolFailed — a tool invocation failed.
	EventTypeToolFailed = internal.EventTypeToolFailed
	// EventTypeToolInvalidArgs — args failed schema validation.
	EventTypeToolInvalidArgs = internal.EventTypeToolInvalidArgs
	// EventTypeToolPolicyExhausted — the policy retry budget ran out.
	EventTypeToolPolicyExhausted = internal.EventTypeToolPolicyExhausted
)

Tool lifecycle event types (published on the events bus).

Variables

View Source 
var (
	// ErrToolNotFound — the named tool is not in the catalog.
	ErrToolNotFound = internal.ErrToolNotFound
	// ErrToolInvalidArgs — arguments failed the tool's schema.
	ErrToolInvalidArgs = internal.ErrToolInvalidArgs
	// ErrToolPolicyExhausted — policy retries are exhausted.
	ErrToolPolicyExhausted = internal.ErrToolPolicyExhausted
	// ErrToolDuplicateName — a tool with this name is already registered.
	ErrToolDuplicateName = internal.ErrToolDuplicateName
	// ErrArtifactRefUnresolved — an [ArtifactRef] was read before the
	// runtime resolved it (the argument omitted the reference, or the
	// value was built outside a dispatch).
	ErrArtifactRefUnresolved = artifactref.ErrUnresolved
)

Re-exported sentinel errors callers compare via errors.Is.

View Source 
var (
	// WithAuthScopes sets the OAuth scopes the tool requires.
	WithAuthScopes = internal.WithAuthScopes
	// WithCostHint sets the human-readable cost hint.
	WithCostHint = internal.WithCostHint
	// WithDescription sets the planner-visible description.
	WithDescription = internal.WithDescription
	// WithExamples attaches worked invocation examples.
	WithExamples = internal.WithExamples
	// WithLatencyHint sets the expected latency hint.
	WithLatencyHint = internal.WithLatencyHint
	// WithLoading sets the catalog LoadingMode.
	WithLoading = internal.WithLoading
	// WithPolicy sets the per-tool execution policy.
	WithPolicy = internal.WithPolicy
	// WithSafetyNotes sets the planner-visible safety notes.
	WithSafetyNotes = internal.WithSafetyNotes
	// WithSideEffect declares the tool's side-effect class.
	WithSideEffect = internal.WithSideEffect
	// WithSource records the tool's provenance.
	WithSource = internal.WithSource
	// WithTags attaches discovery tags.
	WithTags = internal.WithTags
)

Descriptor options (see internal/tools DescriptorOption docs).

View Source 
var Catalog = internal.Catalog

Catalog extracts the catalog from ctx, reporting presence.

View Source 
var DefaultPolicy = internal.DefaultPolicy

DefaultPolicy returns the default per-tool execution policy.

View Source 
var MustCatalog = internal.MustCatalog

MustCatalog extracts the catalog from ctx, panicking when absent.

View Source 
var NewArtifactRef = artifactref.NewRef

NewArtifactRef builds an ArtifactRef carrying an artifact id and no resolved value — for callers assembling arguments in Go (tests, typed embedders) rather than decoding them from a model's JSON. It resolves at dispatch exactly as a decoded one does.

View Source 
var NewCatalog = internal.NewCatalog

NewCatalog constructs an empty tool catalog.

View Source 
var NewPlannerView = internal.NewPlannerView

NewPlannerView builds the identity-filtered planner-facing view of a catalog.

View Source 
var VisibleNames = internal.VisibleNames

VisibleNames lists the tool names visible under a filter.

View Source 
var WithCatalog = internal.WithCatalog

WithCatalog returns a child context carrying the catalog.

Functions

This section is empty.

Types

type ArtifactRef added in v1.23.0 

type ArtifactRef = artifactref.Ref

ArtifactRef is an artifact-reference tool PARAMETER: declare a field of this type in a tool's typed input struct and the derived JSON Schema renders it to the model as a plain artifact-id string. The model supplies the id; the runtime resolves it at dispatch and the tool reads the stored bytes through [ArtifactRef.Bytes]. Bytes flow store → tool — the model authors an id and never sees content.

The resolved value is dispatch-local. Every serialisation door on the type projects the id instead of the content, so an ArtifactRef that reaches an event payload, a formatted string or a log emits the id.

[ArtifactRef.Bytes] fails with ErrArtifactRefUnresolved when the reference was never resolved, rather than returning an empty slice a tool would mistake for an empty artifact.

The RESOLUTION side is deliberately not re-exported: seating a resolver and binding a value are the runtime's acts at the dispatch boundary, and a tool that could do either would be reaching past the identity scope its run was given.

type CatalogFilter 

type CatalogFilter = internal.CatalogFilter

CatalogFilter scopes catalog reads by the identity triple.

type CatalogOption 

type CatalogOption = internal.CatalogOption

CatalogOption customises NewCatalog.

type DescriptorOption 

type DescriptorOption = internal.DescriptorOption

DescriptorOption customises a descriptor at registration time.

type ErrorClass 

type ErrorClass = internal.ErrorClass

ErrorClass classifies a tool failure for the policy shell (retry-vs-stop decisions). Re-exported here because harbortest.SimulateFailure takes one, so external test authors must be able to name the class values.

type LoadingMode 

type LoadingMode = internal.LoadingMode

LoadingMode is the catalog loading strategy for a tool.

type PlannerView 

type PlannerView = internal.PlannerView

PlannerView is the identity-filtered, planner-facing catalog view.

type SideEffect 

type SideEffect = internal.SideEffect

SideEffect declares a tool's side-effect class.

type Tool 

type Tool = internal.Tool

Tool is one registered tool (descriptor + invoker), any transport.

type ToolCatalog 

type ToolCatalog = internal.ToolCatalog

ToolCatalog is the catalog interface tools register on and the runtime dispatches against.

type ToolDescriptor 

type ToolDescriptor = internal.ToolDescriptor

ToolDescriptor is a tool's catalog-visible metadata.

type ToolExample 

type ToolExample = internal.ToolExample

ToolExample is one worked invocation example on a descriptor.

type ToolPolicy 

type ToolPolicy = internal.ToolPolicy

ToolPolicy is the per-tool timeout/retry/validation policy.

type ToolProvider 

type ToolProvider = internal.ToolProvider

ToolProvider is the per-transport invocation seam.

type ToolResult 

type ToolResult = internal.ToolResult

ToolResult is the canonical invocation result envelope.

type ToolSourceID 

type ToolSourceID = internal.ToolSourceID

ToolSourceID names where a tool came from (config, MCP server, ...).

type TransportKind 

type TransportKind = internal.TransportKind

TransportKind names a tool's transport.

type ValidateMode 

type ValidateMode = internal.ValidateMode

ValidateMode selects schema validation of args and/or results.

Source Files

View all Source files

Directories

Path Synopsis
Package auth is the public SDK facade over Harbor's internal/tools/auth package — the tool-side OAuth completion leg: a plain http.Handler that exchanges the provider redirect and resumes the parked pause (RFC §3.6, §6.3).
 Package auth is the public SDK facade over Harbor's internal/tools/auth package — the tool-side OAuth completion leg: a plain http.Handler that exchanges the provider redirect and resumes the parked pause (RFC §3.6, §6.3).
Package builtin is the public SDK facade over Harbor's internal/tools/builtin package — the runtime's built-in tool set (clock, text, artifact_fetch, tool/skill discovery, declarative actions) registered by name onto a catalog (RFC §3.6, §6.10).
 Package builtin is the public SDK facade over Harbor's internal/tools/builtin package — the runtime's built-in tool set (clock, text, artifact_fetch, tool/skill discovery, declarative actions) registered by name onto a catalog (RFC §3.6, §6.10).
Package inproc is the public SDK facade over Harbor's internal/tools/drivers/inproc package — the in-process tool driver that registers plain Go functions as Tools with reflection-derived schemas (RFC §3.6, §6.10).
 Package inproc is the public SDK facade over Harbor's internal/tools/drivers/inproc package — the in-process tool driver that registers plain Go functions as Tools with reflection-derived schemas (RFC §3.6, §6.10).

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.