Handler patterns

These patterns combine the handler fields into the shapes that come up most often. Each is a starting point, not a rule.

Guard with escalation

Block a handler and route the failure to a named event instead of rejecting it.

request.received:
  guard:
    id: rate_limit
    check: "entity.request_count < policy.max_requests_per_hour"
    on_fail: escalate:rate_limit.exceeded
  advances_to: processing

on_fail is one of reject (default), discard, kill, or escalate:{event}. See Guards.

Multi-gate pipeline

Track sub-steps with gates, then reset them when re-entering a cycle.

review.completed:
  sets_gate: g_reviewed
  advances_to: approved
  emit: approval.requested

resubmission.requested:
  clear_gates: true     # resets every gate on the entity
  advances_to: draft

See Writing data and advancing state.

Accumulate and compute

Wait for several items, aggregate them, then branch on the result.

score.received:
  accumulate:
    expected_from: entity.dimensions_requested
    completion: all
    dedup_by: payload.dimension
  compute:
    operation: weighted_average
    keys:
      dimension_key: dimension
      score_keys: [score]
    tiers:
      - dimensions: [quality, speed, cost]
        weight: 0.6
      - dimensions: [innovation, scalability]
        weight: 0.4
    store_as: entity.composite_score
  on_complete:
    - condition: "entity.composite_score >= policy.threshold"
      advances_to: approved
      emit: candidate.approved
    - condition: "entity.composite_score < policy.threshold"
      advances_to: rejected
      emit: candidate.rejected

See Accumulation and computation.

Fan out

Dispatch one event per item; each event resolves into its own template-flow instance (with its own agent), and a staged join: owns completion.

batch.requested:
  fan_out:
    items_from: payload.items
    as: entry     # the loop variable used in fields: (`item` is reserved and rejected)
    identity: entry.item_id  # what makes each dispatched item distinct
    emit:
      event: item.assigned
      fields:
        item_id: entry.item_id
  data_accumulation:
    writes:
      - target_field: item_ids
        expression: payload.items.map(i, i.item_id)

Delivery is receiver-owned: the template flow’s input pin decides whether each item gets a new instance or joins an existing one, so you get one instance and one agent per item. Completion is owned by a fan-in barrier, not by counting in the handler — see examples/routing/fan-in/barrier and Parallel work.

Rules-based routing

Dispatch on a payload field. rules is a list; the matched rule owns the emit.

request.received:
  rules:
    - id: billing
      condition: "payload.category == 'billing'"
      advances_to: billing_review
      emit:
        event: billing.requested
    - id: technical
      condition: "payload.category == 'technical'"
      advances_to: tech_review
      emit:
        event: tech.requested

rules and on_complete are mutually exclusive; using both is a load-time error caught by swarm verify. See Branching.

Dynamic flow instances

One instance (and one entity) per order or customer. The usual way needs no creation call at all — the template flow’s input pin mints the instance when the first event for a new identity arrives:

fulfillment/schema.yaml

mode: template
instance: order_id
pins:
  inputs:
    events:
      - name: order_created
        event: order.created
        resolution:
          mode: select-or-create   # first order.created for a new order_id mints the instance
        carries:
          order_id: {from: payload.order_id, type: text}

When you need to create an instance explicitly from a handler (to pass extra config in), use the create_flow_instance action instead — see Composing flows for that form and the return path. Either way, results come back through the child’s output pin and a connect edge; the carried identity does the addressing.

Timers

“An entity sat here too long” is a stage timer — declared on the stage, armed on entry, cancelled when the entity leaves:

schema.yaml

stages:
  awaiting_payment:
    timers:
      - after: "{{payment_deadline_hours}}h"
        advances_to: payment_overdue     # a real lifecycle edge
  paid: {}
  payment_overdue: {}

{{...}} reads a value from the flow’s policy. For time that a stage cannot anchor — event-triggered delays, or boot-anchored recurring work like a nightly report — declare a node timer with start_on: event:<name> or start_on: boot (see nodes.yaml).

Cross-entity queries

Read across entities to build a report.

timer.daily_report:
  query:
    - entities: tickets
      group_by: state
      count: true
      store_as: entity.tickets_by_state
    - entities: tickets
      filter: "priority == 'critical' && state != 'resolved'"
      select: [ticket_id, subject]
      store_as: entity.open_critical
  emit: report.daily_compiled

query accepts either a single query object or a list of them (as here), and each store_as target is an entity field. store_as is always entity-prefixed (entity.<field>).

Payload transform

Build an output payload from entity state, payload, and policy with emit.fields — and when names match, from: entity fills the required same-named fields for you (see Emitting events).

order.finalized:
  emit:
    event: invoice.requested
    fields:
      order_id: entity.order_id
      total: entity.computed_total
      customer: entity.customer_name

See Emitting events.

Keep reviewers independent

When two agents must not share context, give a role two pools (independent groups of sessions for the same agent role) with different subscriptions: route originals to one and appeals to the other. Same prompt, separate sessions, no shared context.

Getting started

Core concepts

Build a flow

Handlers

Patterns

Operating Swarm

Guard with escalation

Multi-gate pipeline

Accumulate and compute

Fan out

Rules-based routing

Dynamic flow instances

Timers

Cross-entity queries

Payload transform

Keep reviewers independent

​Guard with escalation

​Multi-gate pipeline

​Accumulate and compute

​Fan out

​Rules-based routing

​Dynamic flow instances

​Timers

​Cross-entity queries

​Payload transform

​Keep reviewers independent

Guard with escalation

Multi-gate pipeline

Accumulate and compute

Fan out

Rules-based routing

Dynamic flow instances

Timers

Cross-entity queries

Payload transform

Keep reviewers independent