- name
SKILL.md
技能文件保留在发布者的仓库中。
在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -a cursor -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -a claude-code -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -a codex -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add AgentWorkforce/relay --skill choosing-swarm-patterns -a grok -y在 Grok Bot 聊天中发送复制的消息。Bot 会从 GitHub 获取这个 SKILL.md,并添加到你所有 Bot 共享的技能中。
Install this skill: https://github.com/AgentWorkforce/relay/tree/HEAD/.agents/skills/choosing-swarm-patterns来自发布者
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.
import { runWorkflow } from '@agent-relay/sdk/workflows';
const run = await runWorkflow('workflows/feature-dev.yaml', {
vars: { task: 'Add OAuth login' },
});
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)
Heads up:
hierarchicalresolves to the same edge structure ashub-spokeincoordinator.ts:313-319. Multi-level tree topology is not currently implemented — use pattern name for intent, but expect the same runtime graph.
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):
supervisor or hub-spoke when a lead needs to coordinate live squads.review-loop when the main risk is code quality and feedback iteration.reflection when critic feedback should loop directly back to producers.verifier when completion evidence matters more than design debate.competitive only when independent alternative implementations are useful; otherwise split by ownership scope.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.
swarm: { pattern: fan-out }
agents:
- { name: lead, cli: claude, role: lead }
- { name: auth-rev, cli: claude, role: worker, interactive: false }
- { name: db-rev, cli: claude, role: worker, interactive: false }
workflows:
- name: review
steps:
- { name: review-auth, agent: auth-rev, task: 'Review auth.ts' }
- { name: review-db, agent: db-rev, task: 'Review db.ts' }
swarm: { pattern: pipeline }
agents:
- { name: designer, cli: claude }
- { name: implementer, cli: codex, interactive: false }
- { name: tester, cli: codex, interactive: false }
workflows:
- name: build
steps:
- {
name: design,
agent: designer,
task: 'Design the API schema',
verification: { type: output_contains, value: DONE },
}
- {
name: implement,
agent: implementer,
dependsOn: [design],
task: 'Implement: {{steps.design.output}}',
}
- { name: test, agent: tester, dependsOn: [implement], task: 'Write integration tests' }
swarm:
pattern: hub-spoke
channel: swarm-api
agents:
- { name: lead, cli: claude, role: lead }
- { name: db-worker, cli: claude, role: worker }
- { name: api-worker, cli: claude, role: worker }
workflows:
- name: api-build
steps:
- { name: models, agent: db-worker, task: 'Build database models' }
- { name: routes, agent: api-worker, task: 'Build route handlers', dependsOn: [models] }
- { name: review, agent: lead, task: 'Review everything', dependsOn: [routes] }
swarm: { pattern: consensus }
agents:
- { name: perf, cli: claude, role: reviewer }
- { name: dx, cli: claude, role: reviewer }
- { name: sec, cli: claude, role: reviewer }
coordination:
consensusStrategy: majority # declarative marker: majority | unanimous | quorum
votingThreshold: 0.66
workflows:
- name: decide
steps:
- { name: evaluate-perf, agent: perf, task: 'Evaluate perf of Fastify migration' }
- { name: evaluate-dx, agent: dx, task: 'Evaluate DX of Fastify migration' }
- { name: evaluate-sec, agent: sec, task: 'Evaluate security of Fastify migration' }
swarm:
pattern: mesh
channel: swarm-debug
agents:
- { name: logs, cli: claude }
- { name: code, cli: claude }
- { name: repro, cli: claude }
workflows:
- name: debug-auth
steps:
- { name: logs, agent: logs, task: 'Check server logs' }
- { name: code, agent: code, task: 'Review auth code' }
- { name: repro, agent: repro, task: 'Write repro test' }
swarm: { pattern: handoff }
agents:
- { name: triage, cli: claude }
- { name: billing, cli: claude }
- { name: tech, cli: claude }
workflows:
- name: support
steps:
- { name: triage, agent: triage, task: 'Triage: {{request}}' }
- { name: billing, agent: billing, dependsOn: [triage], task: 'Handle billing' }
- { name: tech, agent: tech, dependsOn: [triage], task: 'Handle tech issues' }
swarm: { pattern: cascade }
agents:
- { name: haiku, cli: claude, model: claude-haiku-4-5-20251001 }
- { name: sonnet, cli: claude, model: claude-sonnet-4-6 }
- { name: opus, cli: claude, model: claude-opus-4-7 }
workflows:
- name: answer
steps:
- { name: try-haiku, agent: haiku, task: '{{question}}' }
- name: try-sonnet
agent: sonnet
dependsOn: [try-haiku]
task: "If this is a complete answer, echo it verbatim. Otherwise answer anew:\n{{steps.try-haiku.output}}"
- name: try-opus
agent: opus
dependsOn: [try-sonnet]
task: "Final-tier answer, using prior attempts for context:\n{{steps.try-sonnet.output}}"
swarm:
pattern: dag
maxConcurrency: 3
agents:
- { name: dev, cli: codex, role: worker }
workflows:
- name: fullstack
steps:
- { name: scaffold, agent: dev, task: 'Create project scaffold' }
- { name: frontend, agent: dev, task: 'Build React UI', dependsOn: [scaffold] }
- { name: backend, agent: dev, task: 'Build API', dependsOn: [scaffold] }
- { name: integrate, agent: dev, task: 'Wire together', dependsOn: [frontend, backend] }
swarm: { pattern: debate }
agents:
- { name: pro, cli: claude, role: debater, task: 'Argue FOR monorepo' }
- { name: con, cli: claude, role: debater, task: 'Argue FOR polyrepo' }
- { name: judge, cli: claude, role: judge, task: 'Decide after 3 rounds' }
coordination:
barriers:
- { name: debate-done, waitFor: [pro-round-3, con-round-3] }
swarm: { pattern: hierarchical }
agents:
- { name: lead, cli: claude, role: lead }
- { name: fe-coord, cli: claude, role: coordinator }
- { name: be-coord, cli: claude, role: coordinator }
- { name: fe-dev, cli: codex, role: worker, interactive: false }
- { name: be-dev, cli: codex, role: worker, interactive: false }
workflows:
- name: large-team
steps:
- { name: plan, agent: lead, task: 'Coordinate full-stack app' }
- { name: fe-plan, agent: fe-coord, task: 'Manage frontend', dependsOn: [plan] }
- { name: be-plan, agent: be-coord, task: 'Manage backend', dependsOn: [plan] }
- { name: fe-impl, agent: fe-dev, task: 'Build components', dependsOn: [fe-plan] }
- { name: be-impl, agent: be-dev, task: 'Build API', dependsOn: [be-plan] }
runner.ts:5353-5395, runner.ts:4527-4538):verification:
type: output_contains # or: exit_code | file_exists | custom
value: DONE # or: PLAN_COMPLETE, IMPLEMENTATION_COMPLETE, REVIEW_COMPLETE
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.
interactive: falseagents run as non-interactive subprocesses with no relay connection. They must not call Relay MCP tools.
reflectionThreshold callback. It's configured via the trajectories: block:trajectories:
enabled: true
reflectOnBarriers: true # config flag exists but runner does NOT currently invoke this path
reflectOnConverge: true # fires at parallel convergence points (runner.ts:2762-2779)
autoDecisions: true # record retry/skip/fail decisions
// Resume a failed run:
await runWorkflow('feature-dev.yaml', { resume: '<runId>' });
// Skip ahead, re-using cached outputs from an earlier run:
await runWorkflow('feature-dev.yaml', {
startFrom: 'review',
previousRunId: '<runId>',
});
version: '1.0'
name: feature-dev
description: 'Blueprint-style feature development with quality gates.'
swarm:
pattern: hub-spoke
maxConcurrency: 2
timeoutMs: 3600000
channel: swarm-feature-dev
idleNudge: { nudgeAfterMs: 120000, escalateAfterMs: 120000, maxNudges: 1 }
agents:
- { name: lead, cli: claude, role: lead, permissions: { access: full } }
- { name: planner, cli: codex, role: planner, interactive: false, permissions: { access: readonly } }
- { name: developer, cli: codex, role: worker, interactive: false, permissions: { access: readwrite } }
- { name: reviewer, cli: claude, role: reviewer, permissions: { access: readonly } }
workflows:
- name: feature-delivery
onError: retry
preflight:
- { command: 'git status --porcelain', failIf: non-empty, description: 'Clean worktree' }
steps:
- name: plan
agent: planner
task: 'Plan: {{task}}'
verification: { type: output_contains, value: PLAN_COMPLETE }
- name: implement
agent: developer
dependsOn: [plan]
task: 'Implement: {{steps.plan.output}}'
verification: { type: output_contains, value: IMPLEMENTATION_COMPLETE }
- name: test
type: deterministic
dependsOn: [implement]
command: npm test
- name: review
agent: reviewer
dependsOn: [test]
task: 'Review implementation'
verification: { type: output_contains, value: REVIEW_COMPLETE }
coordination:
barriers:
- { name: delivery-ready, waitFor: [plan, implement, review], timeoutMs: 900000 }
trajectories:
enabled: true
reflectOnBarriers: true
reflectOnConverge: true
errorHandling:
strategy: retry
maxRetries: 2
retryDelayMs: 5000
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, mes
---name: choosing-swarm-patternsdescription: Use when coordinating multiple AI agents with Agent Relay's workflow engine and need to pick the right…---# .agents/skills/choosing-swarm-patterns/SKILL.md概览
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.
常见问题
从发布者处下载 .agents/skills/choosing-swarm-patterns/SKILL.md,或复制路径后打开仓库。PlugMCP 只收录该技能,不托管文件。
发布者将它存放在 https://github.com/AgentWorkforce/relay。
Claude、Cursor、Codex 和 Grok Build 可以读取你从发布者仓库添加的 SKILL.md。在聊天中发送技能的 GitHub 文件夹链接,Grok Bot 就会安装它。