subagent

package
v1.3.6 Latest Latest
Warning

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

 Go to latest Published: May 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
	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
}

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) 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 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) 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) 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)

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) 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) 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) 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
}

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 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) 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.