Your First Swarm

A swarm is a YAML file that declares a set of agents, their roles, their models, and the dependency graph that determines execution order. godotz.ai reads the file, builds a DAG (directed acyclic graph), and executes agents in topological order — parallelizing where the graph allows.

This guide walks through authoring a realistic swarm.yaml and explains every field.

The swarm.yaml Skeleton

name: my-swarm          # unique identifier for runs and logs
description: |          # human-readable summary (shown in `omp list`)
  One sentence describing what this swarm does.

agents:                  # map of agent definitions
  agent-name:
    model: ...
    role: ...
    depends_on: [...]    # list of agent names this one waits for
    system: |
      System prompt text.
    tools: [...]         # optional: MCP tools this agent can call

flow:
  entry: agent-name      # first agent to run (no depends_on)
  max_rounds: 3          # circuit breaker: stop after N orchestrator rounds
  on_failure: abort      # abort | continue | retry

input:                   # key-value pairs passed to the entry agent
  key: value

Agent Roles

godotz.ai recognizes five built-in roles. Roles affect how the runtime schedules agents and enforces the echo-chamber guard.

The echo-chamber guard (enabled by default in models.yml) prevents assigning critic and actor to models from the same family. A GLM critic checking GLM actor output is allowed; a GLM critic checking a GLM actor from the exact same model is blocked.

DAG Patterns

Sequential (A → B → C)

The simplest topology: each agent waits for the previous one to complete.

agents:
  planner:
    model: anthropic/claude-sonnet-4-6
    role: orchestrator
    system: "Break the task into steps."

  executor:
    model: z.ai/glm-5.1
    role: actor
    depends_on: [planner]
    system: "Execute the steps from the planner."

  reviewer:
    model: z.ai/glm-4.7
    role: critic
    depends_on: [executor]
    system: "Review the executor's output."

Execution order: planner → executor → reviewer.

Parallel Fan-Out (A → B + C → D)

Two agents run concurrently after the first, then converge into a final agent:

agents:
  coordinator:
    model: anthropic/claude-sonnet-4-6
    role: orchestrator
    system: "Assign research and code tasks."

  researcher:
    model: z.ai/glm-5.1
    role: actor
    depends_on: [coordinator]
    system: "Research the background for the task."

  coder:
    model: z.ai/glm-5.1
    role: actor
    depends_on: [coordinator]
    system: "Write the implementation for the task."

  integrator:
    model: z.ai/glm-4.7
    role: critic
    depends_on: [researcher, coder]
    system: "Combine research and code into a cohesive output."

researcher and coder run in parallel — godotz.ai respects the concurrency.max_parallel_agents setting in config.yml. integrator waits for both to complete before starting.

Actor-Critic-Arbiter (full quality loop)

The highest-quality pattern. Use when output quality matters more than cost.

agents:
  orchestrator:
    model: anthropic/claude-sonnet-4-6
    role: orchestrator
    system: |
      Decompose the task. After each round, decide whether the
      actor's revised output satisfies the critic's objections.
      Conclude when quality is sufficient or max_rounds is reached.

  actor:
    model: z.ai/glm-5.1
    role: actor
    depends_on: [orchestrator]
    system: "Draft a response to the assigned sub-task."

  critic:
    model: z.ai/glm-4.7
    role: critic
    depends_on: [actor]
    system: |
      Identify factual errors and logical gaps. Be specific.
      Do not rewrite; point to the problem and explain it.

  arbiter:
    model: anthropic/claude-opus-4-6
    role: arbiter
    depends_on: [critic]
    system: |
      The actor and critic have exchanged views. Make a final
      determination: accept the actor's output, accept the
      critic's objection, or request one more revision.

flow:
  entry: orchestrator
  max_rounds: 4

A Complete Working Example

This swarm analyzes a piece of code, generates a refactoring plan, and critiques the plan before the orchestrator synthesizes a final recommendation.

# code-review-swarm.yaml
name: code-review
description: |
  Analyze a code snippet, produce a refactoring plan, and critique
  the plan for correctness and completeness.

agents:
  orchestrator:
    model: anthropic/claude-sonnet-4-6
    role: orchestrator
    system: |
      You receive a code snippet. Ask the analyzer to identify
      problems, then ask the planner to write a refactoring plan.
      After the critic reviews the plan, synthesize a final
      recommendation with specific line-level changes.

  analyzer:
    model: z.ai/glm-5.1
    role: actor
    depends_on: [orchestrator]
    system: |
      Analyze the provided code. Identify: performance issues,
      security risks, style violations, and missing error handling.
      Output a structured list; no prose summaries.

  planner:
    model: z.ai/glm-5.1
    role: actor
    depends_on: [analyzer]
    system: |
      Using the analyzer's findings, write a prioritized
      refactoring plan. Each item: problem, proposed fix, risk.

  critic:
    model: z.ai/glm-4.7
    role: critic
    depends_on: [planner]
    system: |
      Review the refactoring plan. Flag: items that are
      incorrect, overly risky, or not actionable as written.
      Do not rewrite the plan; identify problems only.

flow:
  entry: orchestrator
  max_rounds: 3
  on_failure: abort

input:
  code: |
    async function fetchUser(id) {
      const res = await fetch('/api/users/' + id)
      return res.json()
    }

Run it:

omp run code-review-swarm.yaml

Reading Output

Run directory

Every run writes artifacts to .omp/runs/<name>-<timestamp>/:

.omp/runs/code-review-20260607-150342/
├── summary.md          # final synthesized output from the orchestrator
├── transcript.jsonl    # full agent turn log (one JSON object per line)
├── dag.json            # the resolved DAG with timing and token counts
└── cost.json           # per-agent and per-model cost breakdown

View the summary

omp output code-review --last
# Prints summary.md to stdout

Inspect the transcript

Each line in transcript.jsonl is one agent turn:

{
  "turn": 1,
  "agent": "analyzer",
  "model": "z.ai/glm-5.1",
  "input_tokens": 412,
  "output_tokens": 287,
  "duration_ms": 1843,
  "output": "Issues found:\n1. No error handling on fetch..."
}

Beads task graph

If you have the control plane running, bd gives a live view during execution and a historical view after:

# Live view (updates every second)
bd watch code-review

# Historical view
bd status code-review --last
# code-review-20260607-150342
#   orchestrator  ✓  1.1s  312 tok
#   analyzer      ✓  1.9s  699 tok
#   planner       ✓  2.4s  854 tok
#   critic        ✓  1.6s  501 tok
#   orchestrator  ✓  0.9s  423 tok  (round 2)
# Total: 8.9s, ~$0.003

# Retry a failed agent without rerunning the whole swarm
bd retry code-review-20260607-150342 planner

Cost breakdown

omp cost code-review --last
# agent         model              input    output   cost
# orchestrator  claude-sonnet-4-6  735 tok  423 tok  $0.0008
# analyzer      glm-5.1            699 tok  287 tok  $0.0001
# planner       glm-5.1            854 tok  612 tok  $0.0002
# critic        glm-4.7            501 tok  318 tok  $0.0002
# TOTAL                                              $0.0013

Common Patterns Reference

Next Steps

• Configuration — Tune concurrency, budgets, and approval mode for your swarms
• Core Concepts: Agent Roles — Deep dive on role semantics and the echo-chamber guard
• Core Concepts: beads DAG — Understand how godotz.ai tracks and retries tasks
• Guides: Parallelizing Work — Fan-out patterns for high-throughput workloads