Orchestrator-Subagent in Go

The Problem

Complex tasks — writing a research report, generating a codebase, planning a project — are too large for a single agent context window and too diverse for one generalist prompt. A monolithic agent either produces shallow results or runs out of tokens trying to do everything at once.

The Solution

The Orchestrator-Subagent pattern decomposes the task into focused subtasks, each handled by a specialized subagent. The orchestrator coordinates: it fans out independent subtasks concurrently using Go’s sync.WaitGroup, collects the results, and sequences dependent steps. Each subagent is a narrow expert — it knows nothing about the other subagents, only its own task.

Structure

Orchestrator-Subagent Pattern

Step 1 of 4

Task Decomposition

The orchestrator receives the raw task and decides which subagents to invoke and in what order. Decomposition logic lives here — subagents are unaware of the broader goal.

flowchart TD
User["User Task"]
Orch["Orchestrator"]
Fan["fanOut() — concurrent"]
Researcher["ResearchAgent"]
Summarizer["SummarizerAgent"]
Context["Aggregate Context"]
Writer["WriterAgent"]
Output["Final Output"]

User --> Orch
Orch --> Fan
Fan -->|"goroutine"| Researcher
Fan -->|"goroutine"| Summarizer
Researcher --> Context
Summarizer --> Context
Context --> Writer
Writer --> Output

Implementation

package main

import "context"

// Agent is a unit of autonomous work that accepts a task and returns a result.
type Agent interface {
	Name() string
	Run(ctx context.Context, task string) (string, error)
}

// SubtaskResult holds the output from one subagent.
type SubtaskResult struct {
	AgentName string
	Output    string
	Err       error
}

package main

import (
	"context"
	"fmt"
	"strings"
	"sync"
)

// Orchestrator coordinates specialized subagents to complete a complex task.
type Orchestrator struct {
	subagents map[string]Agent
}

func NewOrchestrator(agents ...Agent) *Orchestrator {
	m := make(map[string]Agent, len(agents))
	for _, a := range agents {
		m[a.Name()] = a
	}
	return &Orchestrator{subagents: m}
}

// Run decomposes the task, fans out to subagents, and synthesizes the result.
func (o *Orchestrator) Run(ctx context.Context, task string) (string, error) {
	// Phase 1: parallel research and summarization
	parallelAgents := []string{"researcher", "summarizer"}
	results := o.fanOut(ctx, task, parallelAgents)

	for _, r := range results {
		if r.Err != nil {
			return "", fmt.Errorf("subagent %s: %w", r.AgentName, r.Err)
		}
	}

	// Phase 2: sequential writing using aggregated context
	context := buildContext(results)
	writer, ok := o.subagents["writer"]
	if !ok {
		return "", fmt.Errorf("writer subagent not registered")
	}
	return writer.Run(ctx, context)
}

// fanOut dispatches named subagents concurrently and collects their results.
func (o *Orchestrator) fanOut(ctx context.Context, task string, names []string) []SubtaskResult {
	results := make([]SubtaskResult, len(names))
	var wg sync.WaitGroup

	for i, name := range names {
		wg.Add(1)
		go func(idx int, agentName string) {
			defer wg.Done()
			agent, ok := o.subagents[agentName]
			if !ok {
				results[idx] = SubtaskResult{AgentName: agentName, Err: fmt.Errorf("not found")}
				return
			}
			out, err := agent.Run(ctx, task)
			results[idx] = SubtaskResult{AgentName: agentName, Output: out, Err: err}
		}(i, name)
	}

	wg.Wait()
	return results
}

func buildContext(results []SubtaskResult) string {
	var sb strings.Builder
	for _, r := range results {
		fmt.Fprintf(&sb, "[%s]: %s\n", r.AgentName, r.Output)
	}
	return sb.String()
}

// baseAgent is a minimal Agent stub for demonstration.
type baseAgent struct{ name string }

func (b *baseAgent) Name() string { return b.name }
func (b *baseAgent) Run(_ context.Context, task string) (string, error) {
	return fmt.Sprintf("%s processed: %q", b.name, task), nil
}

package main

import (
	"context"
	"fmt"
	"log"
)

func main() {
	orchestrator := NewOrchestrator(
		&baseAgent{name: "researcher"},
		&baseAgent{name: "summarizer"},
		&baseAgent{name: "writer"},
	)

	result, err := orchestrator.Run(context.Background(), "Explain Go generics with examples")
	if err != nil {
		log.Fatalf("orchestrator: %v", err)
	}

	fmt.Println("Final output:")
	fmt.Println(result)
	// Output:
	// Final output:
	// writer processed: "[researcher]: researcher processed: ..."
}

Real-World Analogy

A film production: the director (orchestrator) assigns the cinematographer, sound engineer, and production designer to work in parallel on their specialties. The director then synthesizes their outputs into the final cut. No specialist needs to understand the others’ work — only the director holds the full picture.

Pros and Cons

Pros	Cons
Parallel subagents dramatically reduce wall-clock time	Orchestration logic adds complexity — requires careful error handling
Each subagent has a narrow, focused context — higher quality output	Subagent failures must be handled explicitly; partial results can mislead synthesis
Easy to add new specializations without changing the orchestrator core	Debugging multi-agent failures requires tracing across multiple LLM calls
Maps naturally to Go’s goroutine + WaitGroup concurrency model	Context aggregation must be designed carefully to avoid token bloat

Best Practices

Use errgroup from golang.org/x/sync/errgroup instead of a manual WaitGroup for cleaner error propagation in the fan-out phase.
Give each subagent a timeout via context.WithTimeout — a stalled LLM call should not block the orchestrator indefinitely.
Log the input task and output of every subagent at INFO level; the full trace is essential for debugging multi-agent workflows.
Keep subagent prompts self-contained — pass all necessary context in the task string, not via shared global state.
Design the aggregation step to handle partial results gracefully; prefer degraded output over a hard failure when one subagent errors.

When to Use

Research, writing, or analysis tasks that benefit from specialization and parallelism.
Workflows where the total token count exceeds a single model’s context window.
Systems where different subtasks need different model temperatures, tools, or personas.

When NOT to Use

Simple linear tasks — a single agent loop is easier to reason about.
Tasks where subagent results are tightly interdependent and can’t be parallelized.
Low-latency applications where spinning up multiple LLM calls is too expensive.

Mediator in Go Centralize communication between collaborating objects so they depend on a coordinator instead of referencing each other directly. Composite in Go Treat individual objects and object groups uniformly so recursive tree structures stay simple to traverse and aggregate. Agent Loop (ReAct) in Go Drive an agent by alternating reasoning and acting steps inside a structured loop that terminates when the model signals a final answer. Tool Use in Go Register typed tools by name so an agent can dispatch LLM-selected function calls to the right handler without embedding dispatch logic in the agent itself. Multi-Agent Communication in Go Enable agents to exchange typed messages through a shared message bus so they can collaborate without direct references to each other's implementations.