# Choosing Swarm Patterns

Use when coordinating multiple AI agents with Agent Relay's workflow engine and need to...

- Repository: https://github.com/AgentWorkforce/relay (1088 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -g -a claude-code -y`
Codex: `npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -g -a codex -y`
Cursor: `npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -g -a cursor -y`
Gemini CLI: `npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -g -a gemini-cli -y`

## Description

Use when coordinating multiple AI agents with Agent Relay's workflow engine and need to pick the right orchestration pattern - covers the 10 core patterns (fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, hierarchical) plus 14 specialized ones, with decision framework and accurate SDK/YAML examples.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

### Overview

### Overview

The Agent Relay SDK (`@agent-relay/sdk`) supports 24 swarm patterns via a single `swarm.pattern` field. Patterns are configured declaratively in YAML, there are no standalone `fanOut(...)` / `hubAndSpoke(...)` helpers. Pick the simplest pattern that solves the problem; add complexity only when the system proves it's insufficient.

### Run a pattern

#### TypeScript SDK runner

```ts
import { runWorkflow } from '@agent-relay/sdk/workflows';
const run = await runWorkflow('workflows/feature-dev.yaml', {
  vars: { task: 'Add OAuth login' },
});
```

### Quick Decision Framework

```text
Is the task independent per agent?
  YES → fan-out (parallel workers, hub collects)
Does each step need the previous step's output?
  YES → Is it strictly linear?
    YES → pipeline
    NO  → dag (parallel where possible, `dependsOn` edges)
Does a coordinator need to stay alive and adapt?
  YES → hub-spoke (single-level hub + workers)
        hierarchical (structurally identical in current impl; use for naming/intent)
Is the task about making a decision?
  YES → Do agents need to argue opposing sides?
    YES → debate (adversarial, full mesh)
    NO  → consensus (cooperative, full mesh + coordination.consensusStrategy)
Does the right specialist emerge during processing?
  YES → handoff (sequential chain, one active at a time)
Do all agents need to freely collaborate?
  YES → mesh (full peer-to-peer edges)
Is cost the primary concern?
  YES → cascade (chain of increasingly capable agents; each step's prompt
        decides whether to pass through or redo the prior output)
```

### Pattern Reference (Core 10)

The rest: https://github.com/AgentWorkforce/relay/blob/HEAD/.agents/skills/choosing-swarm-patterns/SKILL.md