agentworkforce/adding-swarm-patterns

Adding Swarm Patterns

Overview

Add new multi-agent coordination patterns to agent-relay by updating four locations: TypeScript types, JSON schema, YAML template, and markdown docs.

When to Use

• Adding a new swarm pattern (e.g., "competitive", "auction")
• Extending coordination capabilities for multi-agent workflows
• Responding to user requests for new orchestration strategies

Quick Reference

| File | Location | What to Add | |------|----------|-------------| | types.ts | packages/broker-sdk/src/workflows/types.ts | Add to SwarmPattern union type | | schema.json | packages/broker-sdk/src/workflows/schema.json | Add to SwarmPattern.enum array | | template.yaml | packages/broker-sdk/src/workflows/builtin-templates/ | Create {pattern}.yaml | | pattern.md | docs/workflows/patterns/ | Create {pattern}.md | | template.md | docs/workflows/templates/ | Create {pattern}.md | | README.md | docs/workflows/README.md | Add to patterns and templates tables |

Implementation Checklist

1. Update TypeScript Types

// packages/broker-sdk/src/workflows/types.ts
export type SwarmPattern =
  | "fan-out"
  | "pipeline"
  // ... existing patterns ...
  | "your-new-pattern";  // Add here

2. Update JSON Schema

// packages/broker-sdk/src/workflows/schema.json
"SwarmPattern": {
  "type": "string",
  "enum": [
    "fan-out",
    "pipeline",
    // ... existing patterns ...
    "your-new-pattern"
  ]
}

3. Create YAML Template

# packages/broker-sdk/src/workflows/builtin-templates/{pattern}.yaml
version: "1.0"
name: pattern-name
description: "One-line description"
swarm:
  pattern: pattern-name
  maxConcurrency: N
  timeoutMs: N
  channel: swarm-pattern-name
agents:
  - name: lead
    cli: claude
    role: "Role description"
  # ... more agents
workflows:
  - name: workflow-name
    steps:
      - name: step-name
        agent: agent-name
        task: |
          Task description with {{task}} placeholder
        verification:
          type: output_contains
          value: STEP_COMPLETE
coordination:
  barriers:
    - name: barrier-name
      waitFor: [step1, step2]
state:
  backend: memory
  namespace: pattern-name
errorHandling:
  strategy: fail-fast

4. Create Pattern Documentation

# docs/workflows/patterns/{pattern}.md

# Pattern Name

One-sentence description.

## When to Use
- Use case 1
- Use case 2

## Structure
[ASCII diagram showing agent/step flow]

## Configuration
[YAML snippet]

## Best Practices
- Practice 1
- Practice 2

5. Create Template Documentation

# docs/workflows/templates/{pattern}.md

# Pattern Template

**Pattern:** name | **Timeout:** N minutes | **Channel:** swarm-name

## Overview
What this template does.

## Agents
| Agent | CLI | Role |
|-------|-----|------|

## Workflow Steps
1. **step** (agent) — Description

## Usage
[CLI and TypeScript examples]

## Verification Markers
- `MARKER` — Description

6. Update README

Add to both tables in docs/workflows/README.md:

• Patterns table: | [pattern](patterns/pattern.md) | Description | Best For |
• Templates table: | [pattern](templates/pattern.md) | pattern | Description |

Common Mistakes

| Mistake | Fix | |---------|-----| | Forgetting schema.json | Validation will fail if schema doesn't include the pattern | | Inconsistent naming | Use same name in types, schema, template filename, and docs | | Missing verification markers | Each step should have output_contains verification | | Wrong doc links | Use relative paths: patterns/name.md not /docs/workflows/patterns/name.md |

Pattern Design Guidelines

Good patterns have:

• Clear coordination model (who talks to whom)
• Defined failure handling (what happens if one agent fails)
• Appropriate concurrency (parallel vs sequential)
• Barrier synchronization for convergence points

Pattern categories:

• Parallel: fan-out, competitive, scatter-gather
• Sequential: pipeline, handoff, cascade
• Hierarchical: hub-spoke, hierarchical, supervisor
• Consensus: consensus, debate, auction
• Graph: dag, mesh