Documentation
¶
Overview ¶
Package toolpack turns an IR into a hot-loadable Rysh tool pack: a declarative manifest of tool definitions plus the live ToolExecutors that back them. It is the highest-leverage Forge target — the same manifest is exposed to agents either one-tool-per-operation (small specs) or via three dynamic meta-tools (large specs), per the context-budget policy (see exposure.go).
Index ¶
- Constants
- func RegisterGRPCStreams(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.HTTPExecutor, ...) []string
- func RegisterGraphQL(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.GraphQLExecutor, ...) []string
- func SanitizeName(name string) string
- type ExposureMode
- type Policy
- type ToolDef
- type ToolPack
Constants ¶
const DefaultDynamicThreshold = 50
DefaultDynamicThreshold mirrors Stainless's auto-switch (~50 methods).
const DefaultMaxTools = 200
DefaultMaxTools caps static registration to protect the context budget.
Variables ¶
This section is empty.
Functions ¶
func RegisterGRPCStreams ¶
func RegisterGRPCStreams(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.HTTPExecutor, sm *runtime.StreamManager, pol Policy) []string
RegisterGRPCStreams installs the stream_start / stream_session pair for an API with server-streaming methods (api.Streams). No-op (nil) when the API has none. Returns the registered tool names.
func RegisterGraphQL ¶
func RegisterGraphQL(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.GraphQLExecutor, sm *runtime.StreamManager, pol Policy) []string
RegisterGraphQL exposes a GraphQL API to agents through constant-footprint tools — <prefix>graphql_schema (discover query/mutation/subscription fields from the IR) and <prefix>graphql_query (execute a GraphQL document); when the schema has subscription fields AND sm is non-nil, it also registers <prefix>graphql_subscribe + <prefix>stream_session (streaming sessions over graphql-ws, design 015 §2.1). This mirrors the dynamic REST exposure: the agent discovers, then invokes, without flooding the context. Returns the registered tool names.
func SanitizeName ¶
SanitizeName coerces a name into Anthropic's tool name charset (^[a-zA-Z0-9_-]{1,64}$), folding invalid runes to '_' and truncating to 64.
Types ¶
type ExposureMode ¶
type ExposureMode string
ExposureMode controls how many tools a tool-pack advertises to the model — the central lever against "tool explosion" (a 400-operation API would both blow the context budget and degrade selection accuracy if registered 1:1).
const ( ModeAuto ExposureMode = "" // dynamic above DynamicThreshold, else static ModeStatic ExposureMode = "static" // one tool per (filtered) operation ModeDynamic ExposureMode = "dynamic" // three constant meta-tools regardless of size )
type Policy ¶
type Policy struct {
Mode ExposureMode `json:"mode,omitempty"`
DynamicThreshold int `json:"dynamic_threshold,omitempty"`
Tags []string `json:"tags,omitempty"` // include only ops carrying one of these tags
ReadOnly bool `json:"read_only,omitempty"` // include only GET/HEAD
MaxTools int `json:"max_tools,omitempty"`
ForceApproval bool `json:"force_approval,omitempty"` // gate ALL calls (else mutating-only)
Prefix string `json:"prefix,omitempty"`
}
Policy is the per-integration exposure configuration.
type ToolDef ¶
type ToolDef struct {
Name string `json:"name"` // sanitized, prefixed tool name
OperationID string `json:"operation_id"` // IR operation id (used by invoke_endpoint)
Method string `json:"method"`
Path string `json:"path"`
Summary string `json:"summary,omitempty"`
Tags []string `json:"tags,omitempty"`
Mutating bool `json:"mutating"`
InputSchema json.RawMessage `json:"input_schema"`
}
ToolDef is one operation rendered as an agent-callable tool.
type ToolPack ¶
type ToolPack struct {
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description,omitempty"`
BaseURL string `json:"base_url,omitempty"`
Auth []ir.AuthScheme `json:"auth,omitempty"`
Tools []ToolDef `json:"tools"`
}
ToolPack is the generated, serializable manifest for an API.
func Build ¶
Build produces a ToolPack from the IR. prefix is prepended to every tool name (e.g. "stripe_") for namespacing; pass "" for none.
func (*ToolPack) Register ¶
func (tp *ToolPack) Register(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.HTTPExecutor, pol Policy) ([]string, ExposureMode)
Register installs the tool-pack's executors into reg according to the policy. It returns the registered tool names and the effective exposure mode. exec is the shared HTTP runtime (already carrying credentials + redaction).
Source Files