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.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
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.
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.
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)
#
Pattern
Topology (actual edges)
Best For
1
fan-out
Hub broadcasts to N workers; workers reply to hub only
Independent subtasks (reviews, research, tests)
2
pipeline
Linear chain (agent_i → agent_{i+1})
Ordered stages (design → implement → test)
3
hub-spoke
Hub ↔ spokes (bidirectional); no spoke-to-spoke
Dynamic coordination, lead reviews/adjusts
4
consensus
Full mesh; decision via coordination.consensusStrategy
Architecture decisions, approval gates
5
mesh
Full mesh (every agent ↔ every other)
Brainstorming, collaborative debugging
6
handoff
Chain; passes control forward
Triage, specialist routing
7
cascade
Chain of dependsOn steps; all run on success, downstream skipped on upstream failure (no built-in "fall through")
Cost optimization: cheap first, each step's prompt passes through or redoes
8
dag
Edges from step dependsOn
Mixed dependencies, parallel where possible
9
debate
Full mesh (same topology as mesh; roles drive behavior)
Rigorous adversarial examination
10
hierarchical
Hub + subordinates (single-level in current impl)
Large teams; semantic distinction from hub-spoke
Heads up:hierarchical resolves to the same edge structure as hub-spoke in coordinator.ts:313-319. Multi-level tree topology is not currently implemented — use pattern name for intent, but expect the same runtime graph.
Additional Patterns (role-driven)
These 14 additional patterns exist in SwarmPattern (types.ts:114-139). The coordinator has role-based auto-selection heuristics (coordinator.ts:51-165), but they only fire when swarm.pattern is omitted — YAML validation requires it (runner.ts:2105-2117), so auto-selection is effectively a programmatic-API feature. In YAML, set swarm.pattern explicitly.
Topology is still resolved per-pattern once selected; the "Triggering roles" column reflects what the coordinator looks for to shape edges (per coordinator.ts:250-450):
Pattern
Roles the topology keys off
Topology
map-reduce
mapper + reducer
coordinator → mappers → reducers → coordinator
scatter-gather
—
hub → workers → hub
supervisor
supervisor
supervisor ↔ workers
reflection
critic or reviewer (auto-select uses critic only)
producers → critic → producers (loop)
red-team
attacker/red-team + defender/blue-team
adversarial mesh with optional judges
verifier
verifier
producers → verifiers → back to producers
auction
auctioneer
auctioneer → bidders → auctioneer
escalation
tier-*
tiered chain, escalate up / report down
saga
saga-orchestrator, compensate-handler
orchestrator ↔ participants
circuit-breaker
primary + fallback/backup
try primary, fallback on failure
blackboard
blackboard / shared-workspace
shared state hub
swarm
hive-mind / swarm-agent
stigmergy-style
competitive
— (declared explicitly)
independent parallel implementations + judge
review-loop
implement* + 2+ reviewer*
implementer ↔ reviewers
Structured Squad Review Loop
Split the work into bounded implementation squads. Each squad owns a non-overlapping file or subsystem scope.
Give each squad an implementer plus a shadow/review partner. The shadow follows the implementer in real time, checks alignment with the spec, and posts concise feedback before the work drifts.
Require the implementer to self-reflect before external review: compare the final diff against the spec, AGENTS.md / CLAUDE.md, recent local conventions, tests, and declared non-goals.
Run an independent self-review/fresh-eyes agent that reads the actual files and recent repo context, not just the chat transcript.
Send that review back to the implementer for one repair round.
After squads converge, run a final two-agent review team, usually one Claude reviewer and one Codex reviewer, independently. They compare notes, merge findings, and produce one final verdict.
Spawn fresh fix agents for final-review findings. Those fix agents self-reflect, then the final reviewers re-check the post-fix state until the spec is fully satisfied or a blocker is documented.
Use supervisor or hub-spoke when a lead needs to coordinate live squads.
Use review-loop when the main risk is code quality and feedback iteration.
Use reflection when critic feedback should loop directly back to producers.
Use verifier when completion evidence matters more than design debate.
Use competitive only when independent alternative implementations are useful; otherwise split by ownership scope.
Pattern Details
The per-pattern YAML snippets below show only the pattern-relevant fields. A runnable YAML file also needs the required top-level version and name; see the Complete YAML Example.
The old category-expanded names are wrong. Current Agent Relay MCP tools are
flat names. In a client that decorates MCP tools, the prefix comes from the
configured server key. With the relay broker's agent-relay server key, Claude
Code users commonly see mcp__agent-relay__send_dm; Codex and opencode users
see the bare canonical name send_dm.
Purpose
Canonical tool
Claude Code form with agent-relay key
Send DM to another agent
send_dm
mcp__agent-relay__send_dm
Check inbox
check_inbox
mcp__agent-relay__check_inbox
List agents
list_agents
mcp__agent-relay__list_agents
Post to a channel
post_message
mcp__agent-relay__post_message
Reply in a thread
reply_to_thread
mcp__agent-relay__reply_to_thread
Spawn sub-agent
add_agent
mcp__agent-relay__add_agent
Remove sub-agent
remove_agent
mcp__agent-relay__remove_agent
interactive: false agents run as non-interactive subprocesses with no relay connection. They must not call Relay MCP tools.
Reflection (Trajectories)
Reflection is not a reflectionThreshold callback. It's configured via the trajectories: block:
trajectories:enabled:truereflectOnBarriers:true# config flag exists but runner does NOT currently invoke this pathreflectOnConverge:true# fires at parallel convergence points (runner.ts:2762-2779)autoDecisions:true# record retry/skip/fail decisions
Common Mistakes
Mistake
Why It Fails
Fix
Using mesh/debate for everything
Full-mesh blows up message volume past ~5 agents
Use hub-spoke or dag for most tasks
Pipeline for independent work
Sequential bottleneck
Use fan-out or dag
Hub-spoke for 2 agents
Hub is unnecessary overhead
Use pipeline or fan-out
Expecting consensusStrategy to tally votes
Runner has no vote-tally logic; field only affects coordinator auto-selection
Aggregate votes in a judge/lead step that reads {{steps.*.output}}
Handoff with "routing = skip other branches"
Skipping only fires on upstream failure, not routing decisions
Emit a routing token in triage output; downstream prompts self-no-op if token doesn't match
Cascade expecting skip-on-success
Runner has no cascade skip logic; failed upstream skips downstream
Chain downstream prompts to pass-through or redo based on {{steps.previous.output}}
Relying on reflectOnBarriers
Config flag exists but runner never calls it
Use reflectOnConverge for convergence reflection; use reflection pattern for critic loops
interactive: false agent calling MCP
Non-interactive subprocess has no relay
Use interactive: true (default) or emit output on stdout
Relying on multi-level hierarchical
Topology is single-level hub in current impl
Use pattern for naming; model levels via dependsOn graph
Writing mcp__relaycast__send(...)
Wrong tool name
Use post_message / mcp__agent-relay__post_message or send_dm / mcp__agent-relay__send_dm
Resume & Re-run
// Resume a failed run:awaitrunWorkflow('feature-dev.yaml', { resume: '<runId>' });
// Skip ahead, re-using cached outputs from an earlier run:awaitrunWorkflow('feature-dev.yaml', {
startFrom: 'review',
previousRunId: '<runId>',
});
