Swarm

The Swarm primitive defines how multiple agents collaborate. It specifies topology, coordination mechanisms, aggregation strategies, failure handling, and resource boundaries.

URI pattern: claw://local/swarm/{name}

Schema

claw: "0.3.0"
kind: Swarm
metadata:
  name: "analysis-team"
  version: "1.0.0"
spec:
  topology: "leader-worker"       # "leader-worker" | "peer-to-peer" | "pipeline"
                                  # | "broadcast" | "hierarchical"

  agents:
    - identity_ref: "lead-analyst"
      role: "leader"
      provider_ref: "high-quality-llm"
      count: 1
    - identity_ref: "data-collector"
      role: "worker"
      provider_ref: "fast-llm"
      count: 3
    - identity_ref: "fact-checker"
      role: "worker"
      provider_ref: "high-quality-llm"
      count: 1

  coordination:
    message_passing: "queue"      # "queue" | "shared-memory" | "event-bus" | "direct"
    backend: "sqlite-wal"         # "sqlite-wal" | "redis" | "nats" | "in-process"
    concurrency:
      max_parallel: 4
      sequential_within_agent: true

  aggregation:
    strategy: "leader-decides"    # "leader-decides" | "majority-vote" | "merge"
                                  # | "chain" | "best-of-n"
    cost_aware: true
    timeout_ms: 600000

  failure:
    retry_per_agent: 2
    dead_letter:
      enabled: true
      max_retries: 5
    circuit_breaker:
      failure_threshold: 3
      reset_timeout_ms: 60000

  resource_limits:
    max_total_tokens: 1000000
    max_total_cost_usd: 5.00
    max_duration_ms: 1800000

Key Fields

Field	Required	Description
`topology`	Yes	Coordination topology for agent interaction.
`agents`	Yes	List of participating agents with roles and provider assignments.
`coordination`	Yes	How agents exchange messages (backend, concurrency).
`aggregation`	Yes	How results from multiple agents are combined.
`failure`	No	Failure handling: retries, dead letter queue, circuit breaker.
`resource_limits`	No	Resource boundaries for the entire swarm operation.

Topologies

CKP defines five coordination topologies:

Topology	Pattern	Use Case
`leader-worker`	One leader distributes tasks to workers and aggregates results.	Analysis teams, task distribution
`peer-to-peer`	All agents communicate directly with each other.	Collaborative problem-solving
`pipeline`	Agents process data sequentially, each passing output to the next.	Data processing chains, staged analysis
`broadcast`	One source sends the same message to all agents.	Parallel evaluation, voting
`hierarchical`	Tree structure with sub-leaders managing sub-groups.	Large organizations, nested delegation

Leader-Worker:              Pipeline:                Peer-to-Peer:
  +------+                  +---+  +---+  +---+      +---+
  |Leader|                  | A +-->B +-->C |      | A <--> B |
  +--+---+                  +---+  +---+  +---+      |   ^     |
  +--+--+                                             |   |     |
  v  v  v                                             +--->  C  |
+-++-++-+                                                +-----+
|W||W||W|
+-++-++-+

Aggregation Strategies

Strategy	Description
`leader-decides`	The leader agent synthesizes all worker results into a final answer.
`majority-vote`	Results are compared; the majority answer wins.
`merge`	All results are combined into a single composite output.
`chain`	Each agent’s output becomes the next agent’s input.
`best-of-n`	Multiple agents solve the same problem; the best result is selected.

Validation Rules

The topology, agents, coordination, and aggregation fields are REQUIRED.
Each agent entry MUST include identity_ref and role.
The coordination.message_passing and coordination.backend fields are REQUIRED.
Resource limits, when specified, MUST be enforced by the runtime.

Design Rationale

The Swarm primitive supports five topologies with coordination controls for parallelism, task sequencing, dead letter queues, and circuit breakers. This formalizes the multi-agent patterns emerging across the Claw ecosystem into a single, interoperable declaration that works across heterogeneous runtime implementations.