Documentation
¶
Overview ¶
Package subagent exposes built SDK blocks as tools: a runner becomes a spawnable subagent tool, RunAll joins concurrent spawns, and FlowTool, LedgerTool, and MemoryTool expose SDK blocks as optional internal tools. See docs/plans/subagent.md.
Index ¶
- Constants
- Variables
- func AsTool(name string, r *agentrun.Runner, opts ToolOptions) tools.Tool
- func ChannelTool(name string, ask channel.Notifier, recipient string) tools.Tool
- func DiscoveryTool(name string) tools.Tool
- func FlowTool(name string, plan *flow.Definition, m *machine.Definition, bus *events.Bus) tools.Tool
- func HeartbeatTool(name string, m *heartbeat.Monitor) tools.Tool
- func InboxTool(name string, box *Mailbox) tools.Tool
- func LedgerTool(name string, l *ledger.Ledger, actor ledger.Actor, lease time.Duration) tools.Tool
- func MemoryTool(name string, s *memory.Store) tools.Tool
- func ProviderRegistryTool(name string, reg *providerregistry.Registry, order []string, ...) tools.Tool
- func ProviderTool(name string, c provider.Completer) tools.Tool
- func RoomTool(name string, r *room.Room, actor string) tools.Tool
- func SchedulerTool(name string, s *scheduler.Scheduler, job scheduler.Job) tools.Tool
- func SendTool(name string, box *Mailbox, id *identity.Identity) tools.Tool
- func TriggerTool(name string, reg *trigger.Registry) tools.Tool
- type DiscoveryCommand
- type HeartbeatCommand
- type LedgerCommand
- type Mailbox
- type MemoryCommand
- type Result
- type RoomCommand
- type SchedulerCommand
- type Spec
- type ToolOptions
Constants ¶
const ( // OpBeat records one beat for ID now. OpBeat = "beat" // OpAlive reports whether ID is inside the timeout. OpAlive = "alive" // OpDead lists every silent id, comma-joined. OpDead = "dead" )
Heartbeat operation constants.
const ( // OpRun records one completed task: admit, claim, complete. OpRun = "run" // OpState reports a key's current status, or absent. OpState = "state" )
Ledger operation constants.
const ( // OpPut stores Data and returns its content-addressed ref. OpPut = "put" // OpGet returns the bytes stored under Ref. OpGet = "get" )
Memory operation constants.
const ( // OpAdmit adds a member, as By or the bound actor. OpAdmit = "admit" // OpRemove removes a member, as By or the bound actor. OpRemove = "remove" // OpPromote promotes a member to admin, as By or the bound actor. OpPromote = "promote" // OpMembers lists every member id, comma-joined. OpMembers = "members" // OpIsMember reports whether ID holds membership. OpIsMember = "ismember" )
Room operation constants.
const ( // OpEvery schedules the bound job on a fixed interval. OpEvery = "every" // OpAt schedules the bound job at fixed times. OpAt = "at" // OpCancel cancels one scheduled job. OpCancel = "cancel" )
Scheduler operation constants.
const (
// OpMatch parses Card and reports the capability Need matches.
OpMatch = "match"
)
Discovery operation constants.
Variables ¶
var ErrBadCommand = errors.New("subagent: bad command")
ErrBadCommand reports a command a tool could not decode or one naming an unknown operation.
var ErrInvalidCapacity = errors.New("subagent: mailbox capacity must be positive")
ErrInvalidCapacity reports a NewMailbox call whose capacity is not positive. Test with errors.Is.
var ErrMailboxFull = errors.New("subagent: mailbox is full")
ErrMailboxFull reports a Deliver against a full mailbox.
var ErrMaxDepth = errors.New("subagent: max spawn depth reached")
ErrMaxDepth reports a spawn past the tool's depth bound.
var ErrUnverified = errors.New("subagent: mailbox rejects an unverified message")
ErrUnverified reports a Deliver whose message fails envelope signature verification. Test with errors.Is.
Functions ¶
func AsTool ¶
AsTool wraps one built runner as a tools.Tool. Each Run drives one full runner execution on a fresh thread; the ctx carries the spawn depth, so a subagent spawning subagents stops at the bound. The input string seeds the run's starting record; the result is the named artifact, or the final status when no artifact is named.
func ChannelTool ¶
ChannelTool returns a tool that routes its input string to one human as a question. An approved answer returns its payload, or approved when the answer carries none. A declined answer fails the call naming the recipient.
func DiscoveryTool ¶
DiscoveryTool returns a stateless tool that parses one capability card per call and matches it against one need. Routing a match to a transport choice stays caller code.
func FlowTool ¶
func FlowTool(name string, plan *flow.Definition, m *machine.Definition, bus *events.Bus) tools.Tool
FlowTool returns a tool that drives plan against m on every call. The input string seeds the starting record; the result is the walk's final status. A non-nil bus observes one StepCompletedEvent per step.
func HeartbeatTool ¶
HeartbeatTool returns a tool bound to one monitor.
func InboxTool ¶
InboxTool returns a tool bound to one mailbox. Each Run drains the mailbox and returns its payloads comma-joined; an empty mailbox returns the literal empty marker.
func LedgerTool ¶
LedgerTool returns a tool bound to one ledger and actor. OpRun wraps the full taskrun ceremony around a no-op work function, landing the key completed; a blocked or replayed key fails the call with the ceremony's own sentinel. OpState reports the key's status, or absent when no record exists.
func MemoryTool ¶
MemoryTool returns a tool bound to one store. Put returns the new ref string; get returns the stored bytes. Both commands travel as a JSON-encoded MemoryCommand in the tool input.
func ProviderRegistryTool ¶
func ProviderRegistryTool( name string, reg *providerregistry.Registry, order []string, retryable providerregistry.Retryable, ) tools.Tool
ProviderRegistryTool returns a tool bound to a named-provider registry. Each run routes one turn through the caller's order and falls through to the next name only when retryable approves the failure; the result is the answering provider's reply content. Wrap the registered completers with usage.WrapCompleter to gain per-session totals under this seam.
func ProviderTool ¶
ProviderTool returns a tool bound to one caller-supplied Completer. The input string is the prompt; the result is the assistant reply's content. No concrete client ships in this SDK; the Completer is always caller code.
func RoomTool ¶
RoomTool returns a tool bound to one room and acting actor. The By field overrides the bound actor per call.
func SchedulerTool ¶
SchedulerTool returns a tool bound to one scheduler and one job. The job closure is caller code; the tool only places it on a schedule or removes it.
Types ¶
type DiscoveryCommand ¶
type DiscoveryCommand struct {
Op string `json:"op"`
Card string `json:"card"`
Need string `json:"need"`
}
DiscoveryCommand is the JSON wire form of one discovery tool call.
type HeartbeatCommand ¶
HeartbeatCommand is the JSON wire form of one heartbeat tool call.
type LedgerCommand ¶
type LedgerCommand struct {
Op string `json:"op"`
Key string `json:"key"`
Seq uint64 `json:"seq"`
Description string `json:"description"`
Needs []ledger.IdempotencyKey `json:"needs"`
}
LedgerCommand is the JSON wire form of one ledger tool call. Op selects the operation; the remaining fields feed it.
type Mailbox ¶
type Mailbox struct {
// contains filtered or unexported fields
}
Mailbox holds signed messages for one recipient. It is safe for concurrent use. Deliver validates, verifies the signature, and appends; Take drains.
func NewMailbox ¶
NewMailbox builds a mailbox holding at most capacity messages.
type MemoryCommand ¶
type MemoryCommand struct {
Op string `json:"op"`
Data string `json:"data"`
Ref string `json:"ref"`
}
MemoryCommand is the JSON wire form of one memory tool call.
type RoomCommand ¶
RoomCommand is the JSON wire form of one room tool call.
type SchedulerCommand ¶
type SchedulerCommand struct {
Op string `json:"op"`
ID string `json:"id"`
EveryMs int64 `json:"every_ms"`
AtMs int64 `json:"at_ms"`
}
SchedulerCommand is the JSON wire form of one scheduler tool call.
type ToolOptions ¶
type ToolOptions struct {
Artifact string
Artifacts *agentrun.Artifacts
Depth int
Bus *events.Bus
// Tracer opens one span per spawn, named subagent.spawn, carrying
// the spawn's thread as an attribute. A runner wired with its own
// Tracer nests that run's spans under the spawn span when both
// use the same Tracer instance.
Tracer *trace.Tracer
}
ToolOptions tunes one subagent tool. Artifact names the artifact the call returns; it needs the runner's own Artifacts bag. Depth bounds recursive spawns; zero means the default three. Bus, when set, receives the spawned run's agent events.