Quick Start

This guide takes you from a fresh CLI install to a running 3-agent swarm. You need the godotz.ai CLI installed and at least one API key set. See Installation if you haven’t done that yet.

Total time: ~5 minutes.

Step 1 — Initialize a Project

Create a new directory and scaffold the godotz.ai config:

mkdir my-first-swarm
cd my-first-swarm
omp init

omp init creates:

my-first-swarm/
├── config.yml        # runtime settings, model routing, API keys
├── models.yml        # model family definitions
└── swarm.yaml        # example swarm (replace with your own)

Step 2 — Verify Your Config

Open config.yml and confirm your API keys are wired in:

# config.yml
gateway:
  provider: direct          # use 'litellm' if control plane is running
  anthropic_api_key: ${ANTHROPIC_API_KEY}
  zai_api_key: ${ZAI_API_KEY}

defaults:
  orchestrator_model: anthropic/claude-sonnet-4-6
  worker_model: z.ai/glm-5.1
  approval_mode: auto        # auto | manual | hardcore

godotz.ai reads ${ENV_VAR} syntax from the environment at runtime — keys are never stored in the file literally.

Check that the config is valid:

omp config validate
# ✓ config.yml syntax OK
# ✓ models.yml loaded: 4 model families
# ✓ ANTHROPIC_API_KEY: reachable
# ✓ ZAI_API_KEY: reachable

Step 3 — Write a 3-Agent Swarm

Replace the contents of swarm.yaml with this minimal 3-agent example. It performs a research task: one orchestrator breaks down the question, one actor drafts the answer, one critic reviews it.

# swarm.yaml
name: research-qa
description: Answer a technical question with critic review

agents:
  orchestrator:
    model: anthropic/claude-sonnet-4-6
    role: orchestrator
    system: |
      You receive a question. Break it into 2-3 sub-questions and
      assign each to the actor. Synthesize the actor's outputs into
      a final answer. Reject the critic's feedback if it's nitpicky.

  actor:
    model: z.ai/glm-5.1
    role: actor
    depends_on: [orchestrator]
    system: |
      You receive a sub-question from the orchestrator. Research and
      draft a factual, concise answer. Cite sources when possible.

  critic:
    model: z.ai/glm-4.7
    role: critic
    depends_on: [actor]
    system: |
      You receive the actor's draft. Identify factual errors, logical
      gaps, and missing context. Be direct. Do not rewrite; only critique.

flow:
  entry: orchestrator
  max_rounds: 3

input:
  question: "What are the practical trade-offs between Temporal and plain queues for durable workflow orchestration?"

Why different GLM models for actor and critic? Using glm-5.1 and glm-4.7 prevents the echo chamber failure mode — two agents from identical model weights tend to agree even when one is wrong. See Anti-Echo-Chamber Design for details.

Step 4 — Run the Swarm

omp run swarm.yaml

You’ll see live output as agents execute:

[omp] Starting swarm: research-qa
[omp] Spawning orchestrator (claude-sonnet-4-6)...

[orchestrator] Breaking question into sub-questions:
  1. What guarantees does Temporal provide that queues do not?
  2. What is the operational overhead of running Temporal?
  3. When are plain queues sufficient?

[actor] Answering sub-question 1...
[actor] Answering sub-question 2...
[actor] Answering sub-question 3...

[critic] Reviewing actor output...
[critic] Issues found: 2 factual gaps identified.

[orchestrator] Synthesizing final answer (round 2/3)...
[orchestrator] Critique accepted. Revising.

[omp] Swarm complete. 3 agents, 2 rounds, ~$0.004
[omp] Output saved: .omp/runs/research-qa-20260607-143201/

Step 5 — Check Results

View the final output

omp output research-qa

Inspect the run log

omp log research-qa --last

This shows each agent’s full turn: prompt sent, response received, tool calls made.

Check task graph status

If you have the control plane running, use bd (beads CLI) to inspect the DAG:

bd status
# research-qa-20260607-143201
#   orchestrator  ✓ completed  1.2s
#   actor         ✓ completed  4.7s
#   critic        ✓ completed  2.1s
#   orchestrator  ✓ completed  0.9s  (round 2)

What Just Happened

Common First-Run Issues

Error: ANTHROPIC_API_KEY not set
Export the key in your shell: export ANTHROPIC_API_KEY="sk-ant-..."

Model z.ai/glm-5.1 unreachable
Check your ZAI_API_KEY and network access to api.z.ai.

Swarm exceeded max_rounds
The critic and actor disagreed for 3+ rounds without resolution. Either increase max_rounds or tighten the critic’s system prompt.

Slow first run
Model cold-start latency. Subsequent runs against the same models are faster. Enable the Redis cache (omp infra up) to cache identical prompts.

Next Steps

• Configuration — Tune config.yml, switch approval modes, configure model presets
• First Swarm — Learn DAG patterns, parallel agents, and fan-out topologies
• Core Concepts: Architecture — Understand the L0–L6 layer model