subagent

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package subagent exposes built SDK blocks as tools in three groups. Spawn and join: AsTool makes a runner a spawnable subagent tool, and RunAll joins concurrent spawns. Mailbox: NewMailbox, SendTool, and InboxTool pass messages to a subagent. Block wrappers: FlowTool, LedgerTool, MemoryTool, RoomTool, SchedulerTool, HeartbeatTool, DiscoveryTool, ProviderTool, ProviderRegistryTool, TriggerTool, and ChannelTool expose SDK blocks as tools. See docs/packages/subagent.md and docs/history/subagent.md.

Index

Constants

View Source
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.

View Source
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.

View Source
const (
	// OpPut stores Data and returns its content-addressed ref.
	OpPut = "put"
	// OpGet returns the bytes stored under Ref.
	OpGet = "get"
)

Memory operation constants.

View Source
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.

View Source
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.

View Source
const (
	// OpMatch parses Card and reports the capability Need matches.
	OpMatch = "match"
)

Discovery operation constants.

Variables

View Source
var ErrBadCommand = errors.New("subagent: bad command")

ErrBadCommand reports a command a tool could not decode or one naming an unknown operation.

View Source
var ErrInvalidOptions = errors.New("subagent: invalid options")

ErrInvalidOptions reports a construction call whose argument fails validation: a NewMailbox capacity that is not positive. The wrapped message names the field and the rule it broke. Test with errors.Is.

View Source
var ErrMailboxFull = errors.New("subagent: mailbox is full")

ErrMailboxFull reports a Deliver against a full mailbox.

View Source
var ErrMaxDepth = errors.New("subagent: max spawn depth reached")

ErrMaxDepth reports a spawn past the tool's depth bound.

View Source
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

func AsTool(name string, r *run.Runner, opts ToolOptions) tools.Tool

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

func ChannelTool(name string, ask channel.Notifier, recipient string) tools.Tool

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

func DiscoveryTool(name string) tools.Tool

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

func HeartbeatTool(name string, m *flow.Monitor) tools.Tool

HeartbeatTool returns a tool bound to one monitor.

func InboxTool

func InboxTool(name string, box *Mailbox) tools.Tool

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

func LedgerTool(name string, l *ledger.Ledger, actor ledger.Actor, lease time.Duration) tools.Tool

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

func MemoryTool(name string, s *memory.Store) tools.Tool

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 *provider.Registry, order []string,
	retryable provider.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 provider.WrapCompleter to gain per-session totals under this seam.

func ProviderTool

func ProviderTool(name string, c provider.Completer) tools.Tool

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

func RoomTool(name string, r *room.Room, actor string) tools.Tool

RoomTool returns a tool bound to one room and acting actor. The By field overrides the bound actor per call.

func SchedulerTool

func SchedulerTool(name string, s *scheduler.Scheduler, job scheduler.Job) tools.Tool

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.

func SendTool

func SendTool(name string, box *Mailbox, id *envelope.Identity) tools.Tool

SendTool returns a tool that signs one message per call with id and delivers it to the bound mailbox: any caller - agent or human wiring - sends to the recipient through the same surface. The input string is the payload; the result is the message id.

func TriggerTool

func TriggerTool(name string, reg *scheduler.Registry) tools.Tool

TriggerTool returns a tool bound to one trigger registry. The input string names the trigger; the registry's own action runs.

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

type HeartbeatCommand struct {
	Op string `json:"op"`
	ID string `json:"id"`
}

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

func NewMailbox(capacity int) (*Mailbox, error)

NewMailbox builds a mailbox holding at most capacity messages.

func (*Mailbox) Deliver

func (m *Mailbox) Deliver(msg envelope.Message) error

Deliver validates msg, verifies its signature, and appends it. An unsigned or tampered message fails with ErrUnverified. A full mailbox fails with ErrMailboxFull.

func (*Mailbox) Take

func (m *Mailbox) Take() []envelope.Message

Take drains every held message in delivery order.

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 Result

type Result struct {
	Name   string
	Status machine.Status
	Err    error
}

Result reports one RunAll member's outcome.

func RunAll

func RunAll(ctx context.Context, specs []Spec) []Result

RunAll runs every spec concurrently and joins, returning one result per spec in spec order. One member's error never cancels its siblings.

type RoomCommand

type RoomCommand struct {
	Op string `json:"op"`
	ID string `json:"id"`
	By string `json:"by"`
}

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 Spec

type Spec struct {
	Name   string
	Runner *run.Runner
	In     machine.InOut
}

Spec names one runner and its starting record for RunAll.

type ToolOptions

type ToolOptions struct {
	Artifact  string
	Artifacts *run.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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL