subagent

package
v1.3.72 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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 AgentEvent added in v1.1.45 

type AgentEvent struct {
	Type            AgentEventType
	Text            string // AgentEventText / AgentEventError
	ToolName        string // AgentEventToolCall / AgentEventToolResult
	ToolID          string // AgentEventToolCall / AgentEventToolResult — unique ID for precise matching
	ToolArgs        string // AgentEventToolCall / AgentEventToolResult
	ToolDisplayName string // AgentEventToolCall / AgentEventToolResult
	ToolDetail      string // AgentEventToolCall / AgentEventToolResult
	Result          string // AgentEventToolResult
	IsError         bool   // AgentEventToolResult / AgentEventError
}

AgentEvent is a single recorded event from a sub-agent's execution.

type AgentEventType added in v1.1.45 

type AgentEventType int

AgentEventType identifies the kind of event recorded during sub-agent execution. 

const (
	AgentEventText       AgentEventType = iota // LLM text output
	AgentEventToolCall                         // tool invocation started
	AgentEventToolResult                       // tool execution result
	AgentEventError                            // error encountered
	AgentEventReasoning                        // LLM thinking/reasoning content
)

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 AgentMessage added in v1.1.45 

type AgentMessage struct {
	From    string
	Message string
	Summary string
}

AgentMessage represents a message sent to a sub-agent.

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
}

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) Broadcast added in v1.1.45 

func (m *Manager) Broadcast(msg AgentMessage) []string

Broadcast sends a message to all running sub-agents.

func (*Manager) Cancel 

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

Cancel cancels a running sub-agent.

func (*Manager) CancelAll added in v1.2.3 

func (m *Manager) CancelAll() int

CancelAll cancels all pending or running sub-agents. Returns the number cancelled.

func (*Manager) Complete 

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

Complete marks a sub-agent as completed or failed.

func (*Manager) FlushStreamBatch added in v1.3.62 

func (m *Manager) FlushStreamBatch()

FlushStreamBatch exports flushStreamBatch for use in tests that need synchronous delivery of buffered stream events.

func (*Manager) Get 

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

Get retrieves a sub-agent by ID.

func (*Manager) GetTaskOutput added in v1.1.45 

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

GetOutput returns the result of a completed (or in-progress) sub-agent. Returns (result, true) if the agent exists, ("", false) otherwise.

func (*Manager) List 

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

List returns all sub-agents.

func (*Manager) Notify 

func (m *Manager) Notify(id string)

func (*Manager) NotifyReasoning added in v1.3.31 

func (m *Manager) NotifyReasoning(agentID, text string)

NotifyReasoning buffers a reasoning chunk for batched delivery.

func (*Manager) NotifyStreamText added in v1.3.7 

func (m *Manager) NotifyStreamText(agentID, text string)

NotifyStreamText buffers a text chunk for batched delivery to the onStreamText callback. Chunks are accumulated per-agent and flushed at streamBatchInterval to avoid flooding the TUI event loop.

func (*Manager) NotifyToolCall added in v1.3.7 

func (m *Manager) NotifyToolCall(agentID, toolID, toolName, displayName, args, detail string)

func (*Manager) NotifyToolResult added in v1.3.7 

func (m *Manager) NotifyToolResult(agentID, toolID, toolName, displayName, detail, result string, isError bool)

func (*Manager) ReleaseSemaphore 

func (m *Manager) ReleaseSemaphore()

ReleaseSemaphore releases a slot.

func (*Manager) RootContext added in v1.1.45 

func (m *Manager) RootContext() context.Context

RootContext returns the manager's lifecycle context. spawn_agent uses this (instead of the per-tool-call ctx) so that sub-agents are not cancelled the moment the parent agent's current turn ends.

func (*Manager) RunningCount 

func (m *Manager) RunningCount() int

RunningCount returns the number of currently running agents.

func (*Manager) SendToAgent added in v1.1.45 

func (m *Manager) SendToAgent(id string, msg AgentMessage) error

SendToAgent sends a message to a specific sub-agent's mailbox.

func (*Manager) SetCancel 

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

SetCancel stores the cancel function for a sub-agent. Returns false if the sub-agent is already terminal and must not be started.

func (*Manager) SetOnComplete 

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

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

func (*Manager) SetOnReasoning added in v1.3.31 

func (m *Manager) SetOnReasoning(fn func(agentID, text string))

func (*Manager) SetOnStreamText added in v1.3.7 

func (m *Manager) SetOnStreamText(fn func(agentID, text string))

SetOnStreamText sets a callback invoked on each text chunk from any sub-agent. Unlike OnUpdate, this is NOT throttled.

func (*Manager) SetOnToolCall added in v1.3.7 

func (m *Manager) SetOnToolCall(fn func(agentID, toolID, toolName, displayName, args, detail string))

func (*Manager) SetOnToolResult added in v1.3.7 

func (m *Manager) SetOnToolResult(fn func(agentID, toolID, toolName, displayName, detail, result string, isError bool))

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) Shutdown added in v1.1.45 

func (m *Manager) Shutdown()

Shutdown cancels every running sub-agent. Call once during app shutdown.

func (*Manager) Snapshot added in v1.0.23 

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

func (*Manager) SnapshotByID added in v1.3.61 

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

SnapshotByID returns a stable copy of a sub-agent snapshot.

func (*Manager) Spawn 

func (m *Manager) Spawn(name, 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) StartStreamBatcher added in v1.3.62 

func (m *Manager) StartStreamBatcher()

StartStreamBatcher starts the background goroutine that periodically flushes accumulated stream text/reasoning to the registered callbacks. Must be called after SetOnStreamText/SetOnReasoning.

func (*Manager) Statuses added in v1.3.11 

func (m *Manager) Statuses() []StatusInfo

Statuses returns lightweight status info for all sub-agents. Unlike List() + Snapshot(), this does NOT copy events and is safe to call at high frequency (e.g. strip display refresh).

func (*Manager) Timeout 

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

Timeout returns the configured timeout.

func (*Manager) UpdateActivity added in v1.0.23 

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
	Model        string                                                       // optional model override (e.g., "sonnet", "opus", "haiku")
	AgentType    string                                                       // optional agent type hint (e.g., "Explore", "Plan")
	WorkingDir   string                                                       // working directory for the sub-agent
	OnStreamText func(agentID, text string)                                   // called on each text chunk for tunnel relay
	OnUsage      func(provider.TokenUsage)                                    // optional exact-usage callback for session accounting
}

RunnerConfig holds everything needed to run a sub-agent.

type Snapshot added in v1.0.23 

type Snapshot struct {
	ID              string
	Name            string // short, meaningful label
	Task            string
	DisplayTask     string
	Tools           []string
	ToolCallCount   int
	Status          Status
	CurrentPhase    string
	CurrentTool     string
	CurrentArgs     string
	ProgressSummary string
	Result          string
	Error           string
	EventsDropped   int
	CreatedAt       time.Time
	StartedAt       time.Time
	EndedAt         time.Time
	Events          []AgentEvent
}

func WaitForSnapshot added in v1.0.23 

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 StatusInfo added in v1.3.11 

type StatusInfo struct {
	ID           string
	Name         string
	Status       Status
	CurrentPhase string
	EndedAt      time.Time
}

StatusInfo is a lightweight copy of a sub-agent's identity and status. Unlike Snapshot, it does NOT copy events, making it safe for high-frequency calls (e.g. strip display refresh) without O(maxAgentEvents) copy overhead.

type SubAgent 

type SubAgent struct {
	ID              string
	Name            string // short, meaningful label (required)
	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
	Mailbox         chan AgentMessage
	// contains filtered or unexported fields
}

SubAgent represents a spawned child agent.

func (*SubAgent) AppendEvent added in v1.2.3 

func (s *SubAgent) AppendEvent(ev AgentEvent)

AppendEvent adds an event to the sub-agent's history (thread-safe). Used for testing and for external event injection.

func (*SubAgent) Events added in v1.1.45 

func (s *SubAgent) Events() []AgentEvent

Events returns a copy of the recorded events.

func (*SubAgent) EventsSince added in v1.3.11 

func (s *SubAgent) EventsSince(fromIdx int) ([]AgentEvent, int)

EventsSince returns only events with index >= fromIdx. This avoids copying the full event history when only incremental events are needed (e.g. GUI agent panel updates). Returns the total event count so callers can track the next fromIdx.

func (*SubAgent) IncrementToolCalls 

func (s *SubAgent) IncrementToolCalls()

func (*SubAgent) RecordEvent added in v1.1.45 

func (s *SubAgent) RecordEvent(ev AgentEvent)

RecordEvent appends an event to the sub-agent's event log. This is the exported version for external callers (e.g., tests).

type ToolInfo 

type ToolInfo interface {
	Name() string
}

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.