Documentation
¶
Overview ¶
Package subagent runs jess subagents with bounded concurrency. A Pool executes named Spec definitions as tasks, merging their events (tagged by AgentPath) onto one stream. It builds each subagent through internal/core, so subagents are real *agentcore.Agent runs that inherit the parent's audit and gate.
Index ¶
- Variables
- type Event
- type Option
- type Pool
- func (p *Pool) Cancel()
- func (p *Pool) Close()
- func (p *Pool) Events() <-chan Event
- func (p *Pool) Register(s Spec)
- func (p *Pool) Submit(ctx context.Context, name, input string, parentPath ...string) (*Task, error)
- func (p *Pool) SubmitTo(ctx context.Context, sink *Stream, name, input string, parentPath ...string) (*Task, error)
- func (p *Pool) Wait() error
- type Result
- type Spec
- type Stream
- type Task
- type Tool
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnknownAgent = errors.New("subagent: unknown agent") ErrPoolClosed = errors.New("subagent: pool is closed") ErrMaxDepth = errors.New("subagent: max depth exceeded") )
Errors returned by Submit.
Functions ¶
This section is empty.
Types ¶
type Event ¶
Event is an agentcore lifecycle event tagged with the AgentPath of the subagent that emitted it. The Pool merges events from many concurrent subagent runs onto one stream; AgentPath is how a consumer tells them apart (e.g. {"research/0001"}, or {"root/0001", "web/0002"} for a nested run).
agentcore.Event has no notion of a subagent path, so jess carries it alongside rather than inside the agentcore type.
type Option ¶
type Option func(*poolConfig)
Option configures a Pool.
func WithDefaults ¶
WithDefaults sets the parent defaults each Spec inherits when its corresponding field is unset: the model, tool gate, audit sink, and agentID. jess.New uses this so subagents share the parent agent's safety controls.
func WithMaxConcurrent ¶
WithMaxConcurrent caps how many subagent runs execute at once (default 8).
func WithMaxDepth ¶
WithMaxDepth caps subagent nesting depth (default 8).
func WithMaxQueued ¶
WithMaxQueued caps how many tasks may wait in the queue; Submit blocks when full (default 1024).
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool runs subagent tasks with bounded concurrency and merges their events.
Callers must call Close (graceful) or Cancel (abort) when done with the Pool; otherwise its worker goroutines run forever waiting for tasks.
func (*Pool) Cancel ¶
func (p *Pool) Cancel()
Cancel aborts all in-flight and queued tasks by cancelling the pool context, then behaves like Close. In-flight runs are interrupted (ctx -> abort).
func (*Pool) Close ¶
func (p *Pool) Close()
Close stops accepting new tasks. In-flight and queued tasks still run; the merged event stream closes once they finish. Idempotent. Safe to call concurrently with Submit (a racing Submit returns ErrPoolClosed rather than panicking).
func (*Pool) Events ¶
Events returns the merged, AgentPath-tagged event stream of all subagent runs. It closes after Close and all tasks finish. Consume it, or call Wait (which drains it); do not do both concurrently.
func (*Pool) Submit ¶
Submit queues a run whose events go to the pool's merged stream (Events()). It blocks if the queue is full and returns when a slot is available or ctx is cancelled. parentPath is the caller's AgentPath (nil at top level).
func (*Pool) SubmitTo ¶
func (p *Pool) SubmitTo(ctx context.Context, sink *Stream, name, input string, parentPath ...string) (*Task, error)
SubmitTo queues a run whose events are forwarded to sink (AgentPath-tagged) instead of the pool's merged stream. Used to bubble a subagent's events into a parent run's stream. The sink is caller-owned; the pool never closes it.
The sink must be actively consumed. If the sink's buffer fills with no reader, the forwarding worker blocks on Send, which stalls the task until the sink drains.
type Result ¶
type Result struct {
AgentPath []string
Output string // the subagent's final assistant text
Summary *ac.RunSummary
}
Result is the outcome of a finished subagent Task.
type Spec ¶
type Spec struct {
Name string
Model ac.ChatModel
Tools []ac.Tool
Skills *skill.Set
SystemPrompt string
AgentID string
MaxTurns int
// Gate and Audit are inherited from the Pool's base config when left nil, so
// subagents share the parent's safety controls by default.
Gate ac.ToolGate
Audit ledger.Sink
}
Spec defines a named subagent: its model and capabilities. The Pool runs a Spec as a task, each task on its own isolated run.
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream multiplexes Events from many producers (the Pool's per-job mergers) onto a single consumer that ranges over Events() (fan-in). Backpressure is by blocking send against the buffered channel: a slow consumer slows producers, bounding memory.
Send after Close is a no-op (never a panic), so a producer that outlives the run is harmless. Close is idempotent and unblocks any producer currently blocked on a full buffer, so a graceful Close never hangs behind a slow or absent consumer.
func (*Stream) Close ¶
func (s *Stream) Close()
Close closes the stream. Idempotent. Subsequent Send calls are no-ops and the Events channel is closed so consumers ranging over it terminate.
type Task ¶
type Task struct {
// contains filtered or unexported fields
}
Task is the handle for one submitted subagent run.
type Tool ¶
type Tool struct {
// contains filtered or unexported fields
}
Tool is the agentcore.Tool the model calls to delegate to a subagent. It runs the named subagent on the Pool and returns the subagent's final text output. The subagent's events are merged onto the Pool's stream (AgentPath-tagged) for any observer of the Pool.
func NewTool ¶
NewTool builds the subagent tool backed by pool. Register the available subagent Specs on the pool before use.
func (*Tool) Execute ¶
func (t *Tool) Execute(ctx context.Context, raw json.RawMessage) (json.RawMessage, error)
Execute runs the subagent and returns its output as JSON. The subagent's events flow onto the Pool's merged stream, tagged by AgentPath.
Source Files