Agent Swarmdocs
GitHub

08 -Build your own

Composing a swarm

A preset is six fields in a YAML file: a name, two to five agents, and optional wiring for resolution, goal, and decision vocabulary. That vocabulary becomes the verdict word in every synthesis the swarm produces.

This page: preset fields → decision vocabulary → full example → where next

The preset file

Drop a .yml file into .agent-swarm/presets/ in your project - or ~/.agent-swarm/presets/ for user-wide presets. The filename does not matter; the name field inside is what you pass to --preset. Project presets override user presets, which override bundled ones. 

# .agent-swarm/presets/my-preset.yml
name: my-preset
description: Optional human-readable description of what this swarm does.
agents:
  - my-agent-one
  - my-agent-two
resolve: orchestrator
goal: Reach a decision-ready recommendation.
decision: Approve / Revise / Reject
Note

The preset schema is strict - no extra keys are allowed. The only valid fields are those documented below.

FieldRequiredDescription
name Yes Lowercase kebab or snake case. Must match /^[a-z0-9][a-z0-9_-]*$/ - start with a letter or digit, then any mix of lowercase letters, digits, hyphens, and underscores. This is the value you pass to --preset.
description No A short human-readable summary. Shown in agent-swarm doctor and in the registry listing.
agents Yes An array of 2-5 agent names. Each name must resolve to an agent definition in the registry (project, user, or bundled). The agents run in parallel every round.
resolve No How the swarm resolves between rounds. One of off, orchestrator, or agents. Defaults to off when omitted. Use orchestrator for most presets - it calls a bundled orchestrator agent to build the next-round directive from the prior round's output.
goal No A sentence that anchors what the swarm is trying to achieve. Included in each agent's brief as context. Useful when your question alone doesn't carry enough framing - for example, "Reach a ship/no-ship recommendation before Friday's planning meeting."
decision No The verdict vocabulary for the synthesis. A slash-separated list of words, e.g. Approve / Revise / Reject. The synthesis picks one of these words as the recommendation. See below for how this works.

Decision vocabulary and the synthesis verdict

The decision field is the most distinctive part of a preset. It defines the exact words the synthesis can use as its recommendation - nothing more, nothing less. When you write: 

decision: Proceed / Defer / Reject

…the synthesis will pick exactly one of Proceed, Defer, or Reject as its verdict word. That word comes from the agents' own stance fields in their structured output - the synthesis tallies the stances, applies a confidence-weighted majority, and surfaces the winning token as the recommendation.

Confidence is always reported as a level - low, medium, or high - not a number. The verdict word and the confidence level are independent: a Proceed at low confidence means the panel leaned one way but wasn't sure.

Synthesismy-preset · round 2 · 2 agents

Approve - both reviewers agreed the plan is sound given the scope constraint.

consensus2 of 2 agree
confidencemedium
Still openDoes the rollback path need a separate sign-off, or is the current approval sufficient?

The synthesis is computed deterministically - no model decides the final word. The same agent notes always produce the same verdict. If decision is omitted, agents can return any stance string they like, and the synthesis picks the most common one.

Tip

Use the bundled presets as vocabulary models. product-decision uses Proceed / Defer / Reject for a three-way call; adversarial-code-review uses Ready / Revise / Reject for a code-change gate; customer-panel uses Fix now / Defer / Reject for urgency framing. Pick words that mean something in your workflow.

A full example end to end

Say you want a two-agent "launch gate" swarm - a growth analyst who looks at market timing and a security reviewer who checks for risk exposure - and you want a three-word call at the end. Here's what that looks like from file to run to synthesis.

1. Define your agents

Each agent name in agents must resolve to an agent definition. Create a .md file with YAML frontmatter for each one in .agent-swarm/agents/. See Writing an agent for the full field reference; the minimal shape is a name and a prompt. 

# .agent-swarm/agents/growth-analyst.md
---
name: growth-analyst
description: Evaluates market timing, competitive position, and launch window risk.
harness: claude
---

You are a growth analyst reviewing a proposed product launch or feature release.
Assess market timing, competitive context, and whether the launch window is
favorable. Return a structured recommendation with your stance, confidence, and
the key risks you see.
# .agent-swarm/agents/security-reviewer.md
---
name: security-reviewer
description: Identifies security exposure, compliance gaps, and launch blockers.
harness: claude
---

You are a security reviewer evaluating a proposed launch for risk exposure.
Identify authentication gaps, data handling concerns, and compliance requirements
that could block or delay the release. Return a structured recommendation with
your stance, confidence, and the specific blockers you see.

2. Write the preset

# .agent-swarm/presets/launch-gate.yml
name: launch-gate
description: >
  Two-agent launch gate - a growth analyst checks market timing,
  a security reviewer checks risk exposure.
agents:
  - growth-analyst
  - security-reviewer
resolve: orchestrator
goal: Determine whether the launch is ready to proceed, needs remediation, or should be held.
decision: Ship / Fix first / Hold

3. Run the swarm

Pass the number of rounds as the first positional argument (1-3), then your question, then --preset: 

agent-swarm run 2 "Is the payments feature ready to launch next Tuesday?" \
  --preset launch-gate

Both agents run in parallel. With two rounds and resolve: orchestrator, the orchestrator builds a second-round brief from the first-round output, then both agents run again with that context before the final synthesis.

Note

Run agent-swarm doctor first to confirm both agents are visible in the registry and your harness is authenticated. Doctor reports any missing agent definitions as a FAIL before the run starts.

4. Read the synthesis

The run directory lands under .agent-swarm/runs/<timestamp>-launch-gate/. The synthesis.md inside uses the preset's own decision vocabulary:

Synthesislaunch-gate · round 2 · 2 agents

Fix first - payments flow is market-ready but the token refresh path has an unauthenticated edge case that must be resolved before launch.

consensus2 of 2 agree
confidencehigh
Still openCan the token refresh fix be shipped as a hotfix in the same release window, or does it require a separate track?

The verdict word - Fix first - is one of the three words you declared in decision: Ship / Fix first / Hold. The synthesis never invents a word outside that vocabulary.

Overriding preset fields at run time

Every preset field except name and agents can be overridden at run time with CLI flags. Flags always win over preset values: 

agent-swarm run 1 "Is the payments feature ready?" \
  --preset launch-gate \
  --goal "Decide before Thursday's go/no-go meeting" \
  --decision "Go / No-go"

Here --decision replaces the preset's three-word vocabulary with a binary call just for this run. The preset file is unchanged.

Note

You cannot override agents or name from the CLI. To run a different roster, use a different preset or create a new one.

Where next