04 -Concepts

Agents & roles

An agent is a named role: a persona and a prompt that together define how one participant thinks about a problem. You select 2-5 agents into a swarm; each runs in parallel every round and returns the same set of structured notes. The swarm's synthesis is built entirely from those notes - no model decides the final word.

What an agent is

An agent is not a long-running process or a background service. It is a role definition - a YAML or Markdown file that tells the harness who this participant is and what to think about. When a round runs, each selected agent receives the same brief and returns one set of structured notes. Between rounds, those notes inform the next directive. After all rounds, the deterministic synthesis folds every agent's output into one answer.

Because agents are plain files, they are version-controlled, shareable, and overridable at the project or user level without touching bundled defaults. Same-name agents in a closer scope silently override bundled ones - project scope beats user scope beats bundled.

Note

A swarm requires a minimum of 2 agents and a maximum of 5. Single-agent and six-plus-agent runs are rejected at parse time.

Agent definition fields

Each agent file is validated against the AgentDefinitionSchema. These are the fields you can set:

Field	Required	Description
`name`	Yes	Lowercase kebab or snake identifier. Must match `^[a-z0-9][a-z0-9_-]*$`. Examples: `product-manager`, `first-time-user`.
`description`	Yes	A short human-readable summary of the role - shown in registry listings and `agent-swarm doctor` output.
`persona`	Yes	A sentence or two that establishes who this agent is. Sets the point of view the model takes when generating output.
`prompt`	Yes	The main instruction string, or `{ file: "path/to/prompt.md" }` to load from a file relative to the agent definition.
`backend`	No	Run-level backend preference. Accepts `claude` or `codex`. Defaults to `claude`.
`harness`	No	Per-agent harness override. Accepts `claude`, `codex`, `opencode`, or `rovo`. When omitted, the run-level backend or the agent's `backend` field determines dispatch.
`model`	No	Harness-specific model string passed to the harness CLI. When omitted, the harness uses its own default.

A minimal agent definition in YAML looks like this:

name: first-time-user
description: First-time user agent for onboarding clarity, setup friction, and early comprehension.
persona: You are a first-time technical user trying to understand the product quickly without insider context.
prompt: |
  You are the first-time-user agent in a swarm.
  Evaluate the topic from the perspective of someone encountering the product for the first time.
  Focus on setup friction, unclear language, and the moment when value becomes obvious.
  Return only the shared swarm JSON contract.

Agents can also be written as Markdown files with YAML frontmatter - any field above can appear in the frontmatter block, and the Markdown body becomes the prompt.

What each agent returns

Every agent must return a single JSON object that validates against AgentOutputSchema. The schema is the same for every agent in every swarm - it is the contract that makes synthesis deterministic. The fields are:

Field	Type	Description
`stance`	string	A single word or short phrase - the agent's verdict in the preset's decision vocabulary (e.g. `Proceed`, `Fix now`, `Reject`).
`recommendation`	string	One sentence that completes the stance: what the agent thinks should happen and why, in plain language.
`reasoning`	string[]	An ordered list of supporting points. The synthesis uses this list to surface shared reasoning across agents.
`objections`	string[]	The agent's own counter-arguments or doubts - things that argue against its own recommendation.
`risks`	string[]	Risks the agent wants the swarm to track. Risks raised by two or more agents surface as shared risks in the synthesis.
`changesFromPriorRound`	string[]	What shifted since the last round - new evidence, updated stance, revised recommendation. Empty on round 1.
`openQuestions`	string[]	Questions the agent could not resolve. These are collected and deferred in the synthesis so they are not silently dropped.
`confidence`	`low` \| `medium` \| `high`	The agent's own confidence in its recommendation. The synthesis averages confidence across agents and rounds.

Note

Confidence is always one of exactly three levels - low, medium, or high. It is never a fabricated percentage. A response with any other value fails schema validation and triggers one automatic repair attempt.

Bundled rosters

Agent Swarm ships three bundled rosters, each matched to a preset. You can use any bundled agent by name in your own presets, or override any of them with a same-name agent at project or user scope.

Customer panel - react to your product from customer perspectives:

first-time-user - onboarding clarity, setup friction, and early comprehension.
busy-operator - day-to-day operational efficiency and workflow fit.
skeptical-buyer - adoption risk, trust signals, and purchase hesitation.

Engineering review - attack a diff or architecture change from multiple angles:

code-reviewer - correctness, style, and maintainability of the change.
implementation-skeptic - questions the approach before the implementation.
test-risk-reviewer - test coverage gaps and regression surface.
principal-engineer - feasibility, system-level tradeoffs, and long-term cost.

Product decision - frame user value and ground feasibility:

product-manager - user value, scope, delivery sequencing, and decision quality.
product-engineer - engineering effort, technical tradeoffs, and build risk.
product-designer - usability, design coherence, and user experience impact.

For example, the customer-panel preset selects first-time-user, busy-operator, and skeptical-buyer and runs them in parallel every round:

agent-swarm run 2 "Should we ship the freemium tier this quarter?" \
  --preset customer-panel

Where next

Writing an agent - define your own agent from scratch with YAML or Markdown.
CLI reference - every command, flag, preset, and run artifact.
Architecture - how agents flow through the pipeline at runtime.

Note

The agent definition schema is defined in src/schemas/agent-definition.ts and the output schema in src/schemas/agent-output.ts. These are the authoritative sources - this page reflects them exactly.