Agent Patterns That Survive Production

// Plan represents a sequence of steps the agent intends to execute.
// Steps can be updated mid-execution when results diverge.
type Plan struct {
	Goal      string
	Steps     []Step
	Completed []StepResult
}

type Step struct {
	ID          string
	Description string
	ToolName    string
	Input       map[string]any
}

type StepResult struct {
	StepID  string
	Output  any
	Err     error
	Blocked bool
}

// Execute runs through the plan, replanning when a step is blocked
// or produces unexpected results.
func (a *Agent) Execute(ctx context.Context, p *Plan) (*Plan, error) {
	for len(p.Steps) > 0 {
		step := p.Steps[0]
		p.Steps = p.Steps[1:]

		result := a.runStep(ctx, step)
		p.Completed = append(p.Completed, result)

		if result.Blocked || result.Err != nil {
			revised, err := a.replan(ctx, p)
			if err != nil {
				return p, fmt.Errorf("replan failed: %w", err)
			}
			p = revised
		}
	}
	return p, nil
}

// replan asks the model to revise remaining steps given what has
// happened so far. The completed results provide context.
func (a *Agent) replan(ctx context.Context, p *Plan) (*Plan, error) {
	prompt := fmt.Sprintf(
		"Goal: %s\nCompleted: %s\nRevise the remaining steps.",
		p.Goal, formatResults(p.Completed),
	)
	resp, err := a.llm.Complete(ctx, prompt)
	if err != nil {
		return p, err
	}
	p.Steps = parseSteps(resp)
	return p, nil
}

// Orchestrator decomposes a task and dispatches sub-tasks to
// specialist agents. It synthesizes their results.
type Orchestrator struct {
	planner     LLM
	specialists map[string]*Specialist
}

type Specialist struct {
	Name    string
	Agent   *Agent
	Domain  string // e.g. "research", "code-generation", "validation"
}

type SubTask struct {
	ID          string
	Description string
	Specialist  string
	Input       map[string]any
	DependsOn   []string
}

// Run decomposes the task, executes sub-tasks respecting dependencies,
// and synthesizes results.
func (o *Orchestrator) Run(ctx context.Context, task string) (string, error) {
	subtasks, err := o.decompose(ctx, task)
	if err != nil {
		return "", fmt.Errorf("decompose: %w", err)
	}

	results := make(map[string]string)

	for _, batch := range topologicalBatches(subtasks) {
		g, gCtx := errgroup.WithContext(ctx)

		for _, st := range batch {
			st := st
			spec, ok := o.specialists[st.Specialist]
			if !ok {
				return "", fmt.Errorf("unknown specialist: %s", st.Specialist)
			}

			g.Go(func() error {
				// Inject dependency results into the sub-task input.
				for _, dep := range st.DependsOn {
					st.Input[dep] = results[dep]
				}
				res, err := spec.Agent.RunTask(gCtx, st.Description, st.Input)
				if err != nil {
					return fmt.Errorf("specialist %s: %w", spec.Name, err)
				}
				results[st.ID] = res
				return nil
			})
		}

		if err := g.Wait(); err != nil {
			return "", err
		}
	}

	return o.synthesize(ctx, task, results)
}

// Memory manages the agent's working context with size limits
// and periodic compression.
type Memory struct {
	mu       sync.Mutex
	facts    []Fact
	maxFacts int
	llm      LLM
}

type Fact struct {
	Key       string
	Value     string
	Source    string // which step produced this
	Priority  int    // higher = keep longer
	CreatedAt time.Time
}

// Add inserts a fact, compressing if the memory is full.
func (m *Memory) Add(ctx context.Context, f Fact) error {
	m.mu.Lock()
	defer m.mu.Unlock()

	m.facts = append(m.facts, f)

	if len(m.facts) > m.maxFacts {
		return m.compress(ctx)
	}
	return nil
}

// compress asks the model to summarize low-priority facts into
// fewer entries, keeping high-priority facts intact.
func (m *Memory) compress(ctx context.Context) error {
	sort.Slice(m.facts, func(i, j int) bool {
		return m.facts[i].Priority > m.facts[j].Priority
	})

	// Keep top half as-is, compress bottom half.
	keep := m.facts[:m.maxFacts/2]
	toCompress := m.facts[m.maxFacts/2:]

	summary, err := m.llm.Complete(ctx, fmt.Sprintf(
		"Summarize these facts into 2-3 key points:\n%s",
		formatFacts(toCompress),
	))
	if err != nil {
		// On failure, just drop the lowest priority facts.
		m.facts = keep
		return nil
	}

	m.facts = append(keep, Fact{
		Key:       "compressed_context",
		Value:     summary,
		Priority:  1,
		CreatedAt: time.Now(),
	})
	return nil
}

// ForPrompt renders the current memory as a string for inclusion
// in a prompt.
func (m *Memory) ForPrompt() string {
	m.mu.Lock()
	defer m.mu.Unlock()
	return formatFacts(m.facts)
}

// RecoveryStrategy defines how the agent handles a specific failure type.
type RecoveryStrategy struct {
	Name       string
	MaxRetries int
	Backoff    time.Duration
	Handler    func(ctx context.Context, err error) (Action, error)
}

type Action int

const (
	Retry        Action = iota
	Decompose           // break the failed step into smaller steps
	Skip                // mark step as skipped, continue
	Escalate            // pause for human input
	Abort               // stop the agent
)

// Recover selects and applies the appropriate recovery strategy.
func (a *Agent) Recover(ctx context.Context, step Step, err error) (Action, error) {
	strategy := a.selectStrategy(err)

	for attempt := 0; attempt < strategy.MaxRetries; attempt++ {
		action, retryErr := strategy.Handler(ctx, err)
		if retryErr == nil {
			return action, nil
		}
		time.Sleep(strategy.Backoff * time.Duration(attempt+1))
	}

	// All retries exhausted. Escalate.
	return Escalate, fmt.Errorf(
		"recovery exhausted for step %s after %d attempts: %w",
		step.ID, strategy.MaxRetries, err,
	)
}