subagent

Documentation

Index

• func Run(ctx context.Context, cfg RunnerConfig)
• func Wait(ctx context.Context, mgr *Manager, id string) (string, error)
• type AgentFactory
• type AgentRunner
• type Manager
  • func NewManager(cfg config.SubAgentConfig) *Manager
  • func (m *Manager) AcquireSemaphore(ctx context.Context) error
  • func (m *Manager) Cancel(id string) bool
  • func (m *Manager) Complete(id string, result string, err error)
  • func (m *Manager) Get(id string) (*SubAgent, bool)
  • func (m *Manager) List() []*SubAgent
  • func (m *Manager) Notify(id string)
  • func (m *Manager) ReleaseSemaphore()
  • func (m *Manager) RunningCount() int
  • func (m *Manager) SetCancel(id string, cancel context.CancelFunc)
  • func (m *Manager) SetOnComplete(fn func(*SubAgent))
  • func (m *Manager) SetOnUpdate(fn func(*SubAgent))
  • func (m *Manager) ShowOutput() bool
  • func (m *Manager) Snapshot(id string) (Snapshot, bool)
  • func (m *Manager) Spawn(task, displayTask string, tools []string, ctx context.Context) string
  • func (m *Manager) Timeout() time.Duration
  • func (m *Manager) UpdateActivity(id, phase, toolName, args string)
  • func (m *Manager) UpdateProgress(id, summary string)
• type RunnerConfig
• type Snapshot
  • func WaitForSnapshot(ctx context.Context, mgr *Manager, id string, wait time.Duration) (Snapshot, error)
• type Status
• type SubAgent
  • func (s *SubAgent) IncrementToolCalls()
• type ToolInfo

Functions

func Run

func Run(ctx context.Context, cfg RunnerConfig)

Run starts the sub-agent in a goroutine, running a complete agentic loop. The sub-agent gets its own context manager, tool subset, and provider instance.

func Wait

func Wait(ctx context.Context, mgr *Manager, id string) (string, error)

Wait blocks until the sub-agent with the given ID finishes, returning its result.

Types

type AgentFactory

type AgentFactory func(prov provider.Provider, tools interface{}, systemPrompt string, maxTurns int) AgentRunner

AgentFactory creates an agent with the given provider, tool registry, system prompt, and max turns. The tools parameter is an opaque value passed through from the caller.

type AgentRunner

type AgentRunner interface {
	RunStream(ctx context.Context, prompt string, onEvent func(provider.StreamEvent)) error
}

AgentRunner is the minimal interface needed from an agent.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages spawning, tracking, and collecting results from sub-agents.

func NewManager

func NewManager(cfg config.SubAgentConfig) *Manager

NewManager creates a Manager with the given config.

func (*Manager) AcquireSemaphore

func (m *Manager) AcquireSemaphore(ctx context.Context) error

AcquireSemaphore blocks until a slot is available for a new sub-agent to run.

func (*Manager) Cancel

func (m *Manager) Cancel(id string) bool

Cancel cancels a running sub-agent.

func (*Manager) Complete

func (m *Manager) Complete(id string, result string, err error)

Complete marks a sub-agent as completed or failed.

func (*Manager) Get

func (m *Manager) Get(id string) (*SubAgent, bool)

Get retrieves a sub-agent by ID.

func (*Manager) List

func (m *Manager) List() []*SubAgent

List returns all sub-agents.

func (*Manager) Notify

func (m *Manager) Notify(id string)

func (*Manager) ReleaseSemaphore

func (m *Manager) ReleaseSemaphore()

ReleaseSemaphore releases a slot.

func (*Manager) RunningCount

func (m *Manager) RunningCount() int

RunningCount returns the number of currently running agents.

func (*Manager) SetCancel

func (m *Manager) SetCancel(id string, cancel context.CancelFunc)

SetCancel stores the cancel function for a sub-agent.

func (*Manager) SetOnComplete

func (m *Manager) SetOnComplete(fn func(*SubAgent))

SetOnComplete sets a callback invoked when any sub-agent completes.

func (*Manager) SetOnUpdate

func (m *Manager) SetOnUpdate(fn func(*SubAgent))

SetOnUpdate sets a callback invoked when any sub-agent activity changes.

func (*Manager) ShowOutput

func (m *Manager) ShowOutput() bool

ShowOutput returns whether to show sub-agent output.

func (*Manager) Snapshot

func (m *Manager) Snapshot(id string) (Snapshot, bool)

func (*Manager) Spawn

func (m *Manager) Spawn(task, displayTask string, tools []string, ctx context.Context) string

Spawn creates a new sub-agent with the given task and returns its ID.

func (*Manager) Timeout

func (m *Manager) Timeout() time.Duration

Timeout returns the configured timeout.

func (*Manager) UpdateActivity

func (m *Manager) UpdateActivity(id, phase, toolName, args string)

func (*Manager) UpdateProgress

func (m *Manager) UpdateProgress(id, summary string)

type RunnerConfig

type RunnerConfig struct {
	Provider     provider.Provider
	AllTools     []ToolInfo
	Task         string
	AllowedTools []string
	Manager      *Manager
	SubAgentID   string
	AgentFactory AgentFactory
	BuildToolSet func(allowedTools []string, allTools []ToolInfo) interface{} // returns opaque tool set for agent
}

RunnerConfig holds everything needed to run a sub-agent.

type Snapshot

type Snapshot struct {
	ID              string
	Task            string
	DisplayTask     string
	Tools           []string
	ToolCallCount   int
	Status          Status
	CurrentPhase    string
	CurrentTool     string
	CurrentArgs     string
	ProgressSummary string
	Result          string
	Error           string
	CreatedAt       time.Time
	StartedAt       time.Time
	EndedAt         time.Time
}

func WaitForSnapshot

func WaitForSnapshot(ctx context.Context, mgr *Manager, id string, wait time.Duration) (Snapshot, error)

type Status

type Status string

Status represents the lifecycle state of a sub-agent.

const (
	StatusPending   Status = "pending"
	StatusRunning   Status = "running"
	StatusCompleted Status = "completed"
	StatusFailed    Status = "failed"
	StatusCancelled Status = "cancelled"
)

type SubAgent

type SubAgent struct {
	ID              string
	Task            string
	DisplayTask     string
	Tools           []string
	ToolCallCount   int
	Status          Status
	CurrentPhase    string
	CurrentTool     string
	CurrentArgs     string
	ProgressSummary string
	Result          string
	Error           error
	CreatedAt       time.Time
	StartedAt       time.Time
	EndedAt         time.Time
	// contains filtered or unexported fields
}

SubAgent represents a spawned child agent.

func (*SubAgent) IncrementToolCalls

func (s *SubAgent) IncrementToolCalls()

type ToolInfo

type ToolInfo interface {
	Name() string
}

ToolInfo is the minimal interface needed from a tool for sub-agent registration.