Actions

An action runs a platform-provided operation as a near-final step of the handler (after the writes and the emit). There are exactly four action types, and you cannot define your own — calling your tools is a different step, activity:, covered at the end of this page. Actions are platform operations; activities are your integrations. action comes in two forms, and which one an action uses depends on its parameters:

Name plus sibling fields, when the parameters are simple. create_flow_instance and record_evidence write action: <name> and put their parameters next to it on the handler.
An object { id, <block> }, when the action carries a structured config block. mailbox_write nests its config under action.mailbox, and artifact_repo_commit under action.artifact_repo.

Every example below passes swarm verify.

create_flow_instance

Spin up a new instance of a template flow, passing data in through config_from:

order.paid:
  action: create_flow_instance
  template: fulfillment              # a flow declared mode: template
  instance_id_from: payload.order_id # the new instance's id
  config_from:
    order_id: payload.order_id       # values the child reads as config
    address: payload.ship_to
  advances_to: fulfilling

This is the spawn half of cross-flow composition, so its “whole flow” is two flows. The complete worked example, including how the child returns a result, is in Composing flows.

record_evidence

Append the triggering event’s payload to an entity accumulator, building an audit trail. It is append-only and never replaces; evidence_target names the accumulator:

evidence.submitted:
  select_entity:
    by:
      incident_id: payload.incident_id
  action: record_evidence
  evidence_target: evidence.items

Not the same as data_accumulation. data_accumulation sets named entity fields and overwrites them (last write wins): use it for the entity’s current state, such as category or a running total. record_evidence appends the whole event payload as a new entry to a list and never overwrites: use it for an append-only history of what happened. They are complementary, fields versus a log.

A complete minimal flow

An incident log: open an incident, append evidence to it, then close it.

package.yaml

name: incident-log
version: 1.0.0
description: Append evidence to an incident, then close it.
platform_version: ">=0.7.0 <0.8.0"
flows: []

schema.yaml

stages:
  open:
    initial: true
  closed:
    terminal: true
pins:
  inputs:
    events: [incident.opened, evidence.submitted, incident.closed]

entities.yaml

incident:
  incident_id: text
  title: text

events.yaml

incident.opened:
  swarm: { source: external }
  incident_id: text
  title: text
evidence.submitted:
  swarm: { source: external }
  incident_id: text
  finding: text
  severity: text
incident.closed:
  swarm: { source: external }
  incident_id: text

nodes.yaml

incident-recorder:
  event_handlers:
    incident.opened:                 # 1. create the incident
      create_entity: true
      data_accumulation:
        writes: [incident_id, title]
        source_event: incident.opened
    evidence.submitted:              # 2. append each finding to the accumulator
      select_entity:
        by:
          incident_id: payload.incident_id
      action: record_evidence
      evidence_target: evidence.items
    incident.closed:                 # 3. close it
      select_entity:
        by:
          incident_id: payload.incident_id
      advances_to: closed

What happens: incident.opened mints the incident and records its id and title. Each evidence.submitted selects that incident by incident_id and appends its payload to the evidence.items accumulator (the accumulator is created on first use; you do not declare it as a field). incident.closed moves the incident to its terminal state. The accumulated evidence is the durable audit trail.

Binding values in action blocks

The next two actions, mailbox_write and artifact_repo_commit, take field values that can be either a constant or a reference, and you say which with an explicit key:

{ ref: payload.x } reads a path (payload.*, entity.*, event.*).
{ literal: "review_request" } is a constant.
{ cel: "entity.a + entity.b" } is a computed expression (expression: is an accepted alias).

Give exactly one. The trap worth internalizing: a bare scalar in these blocks is a literal, not a reference. content: entity.body commits a file whose contents are the text entity.body; you almost always mean content: { ref: entity.body }. This is the opposite of emit.fields, where a bare scalar is evaluated as an expression. When in doubt inside an action block, be explicit. (Handler fields collects how every block treats a bare scalar in one table.)

mailbox_write

Put a decision in front of a human. The runtime materializes a durable mailbox row and the flow waits for the decision to come back as an event. The config nests under action.mailbox; item_type and summary are required, severity defaults to normal:

refund.requested:
  action:
    id: mailbox_write
    mailbox:
      item_type: refund_approval
      severity: urgent               # normal | urgent | critical
      summary: "Refund needs manager approval"
      payload:
        amount: { ref: entity.amount }   # a reference; a bare scalar here is a literal
  advances_to: awaiting_approval

A complete minimal flow

A refund desk: route a large refund to a human, then resume on their decision.

package.yaml

name: refund-approval
version: 1.0.0
description: Route large refunds to a human, resume on their decision.
platform_version: ">=0.7.0 <0.8.0"
flows: []

schema.yaml

stages:
  requested:
    initial: true
  awaiting_approval: {}
  approved:
    terminal: true
  rejected:
    terminal: true
pins:
  inputs:
    events: [refund.requested, refund.approved, refund.rejected]

entities.yaml

refund:
  refund_id: text
  amount: numeric

events.yaml

refund.requested:
  swarm: { source: external }
  refund_id: text
  amount: numeric
refund.approved:
  swarm: { source: external }
  refund_id: text
refund.rejected:
  swarm: { source: external }
  refund_id: text

nodes.yaml

refund-desk:
  event_handlers:
    refund.requested:                # 1. open a mailbox item, then wait
      create_entity: true
      data_accumulation:
        writes: [refund_id, amount]
        source_event: refund.requested
      action:
        id: mailbox_write
        mailbox:
          item_type: refund_approval
          severity: urgent
          summary: "Refund needs manager approval"
          payload:
            amount: { ref: entity.amount }
      advances_to: awaiting_approval
    refund.approved:                 # 2a. human approved
      select_entity:
        by:
          refund_id: payload.refund_id
      advances_to: approved
    refund.rejected:                 # 2b. human rejected
      select_entity:
        by:
          refund_id: payload.refund_id
      advances_to: rejected

What happens: refund.requested creates the refund, writes a pending row to the mailbox, and parks the entity in awaiting_approval. The flow does nothing else until an operator decides (see Mailbox). The decision arrives as refund.approved or refund.rejected, which selects the refund by id and advances it to a terminal state. The mailbox row is idempotent per triggering event, so a replayed delivery does not duplicate it.

artifact_repo_commit

Commit service-owned files to a local git repository and expose them at a swarm-artifact:// URL. This is the most involved action: paths must be allowlisted and relative, each file needs a content_type, and an output block must bind the runtime’s result fields to entity fields. The config nests under action.artifact_repo:

report.ready:
  action:
    id: artifact_repo_commit
    artifact_repo:
      provider: local_git            # the only provider
      repo_id: reports
      request_id: { ref: payload.report_id }  # same id + same content = safe retry (a reference, not a literal)
      allowed_paths: ["reports/summary.md"]
      files:
        - path: "reports/summary.md"
          content: { ref: entity.body }       # the file's contents come from the entity field
          content_type: markdown     # yaml | json | markdown | text
      output:                        # output name -> entity field to write it to
        repo_url: repo_url
        current_ref: current_ref
        file_manifest: file_manifest
        status: commit_status
        failure: failure_reason
        last_request_id: last_request_id
        last_source_event_id: last_source_event_id
  advances_to: published

A complete minimal flow

A report publisher: commit a generated report to a git-backed repo.

package.yaml

name: report-publisher
version: 1.0.0
description: Commit a generated report to a git-backed artifact repo.
platform_version: ">=0.7.0 <0.8.0"
flows: []

schema.yaml

stages:
  ready:
    initial: true
  published:
    terminal: true
pins:
  inputs:
    events: [report.ready]

entities.yaml

report:
  report_id: text
  body: text
  # the action writes these; every field needs an initial value so `swarm verify` can prove it is always defined
  repo_url: { type: text, initial: "" }
  current_ref: { type: text, initial: "" }
  file_manifest: { type: text, initial: "" }
  commit_status: { type: text, initial: "" }
  failure_reason: { type: text, initial: "" }
  last_request_id: { type: text, initial: "" }
  last_source_event_id: { type: text, initial: "" }

events.yaml

report.ready:
  swarm: { source: external }
  report_id: text
  body: text

nodes.yaml

report-publisher:
  event_handlers:
    report.ready:
      create_entity: true
      data_accumulation:
        writes: [report_id, body]
        source_event: report.ready
      action:
        id: artifact_repo_commit
        artifact_repo:
          provider: local_git
          repo_id: reports
          request_id: { ref: payload.report_id }
          allowed_paths: ["reports/summary.md"]
          files:
            - path: "reports/summary.md"
              content: { ref: entity.body }
              content_type: markdown
          output:
            repo_url: repo_url
            current_ref: current_ref
            file_manifest: file_manifest
            status: commit_status
            failure: failure_reason
            last_request_id: last_request_id
            last_source_event_id: last_source_event_id
      advances_to: published

What happens: report.ready creates the report entity and records its body, then commits reports/summary.md to the reports repo. The output block writes the commit’s result (the repo URL, the new ref, a file manifest, status) back onto the entity, so later handlers can read where the artifact landed. request_id makes the commit idempotent: the same id with the same content is a safe repeat, while the same id with different content is rejected rather than silently overwriting. For the full field list (provenance, limits, success/failure events) see Handler fields.

Durable activities

Where action runs the four platform operations, activity: durably calls one of your own declared tools (from tools.yaml) — with the persistence, retry, and approval semantics an external side effect deserves:

nodes.yaml

invoice.approved:
  advances_to: sending
  activity:
    tool: stripe.create_invoice        # a declared tool id
    input:                             # same expression grammar as emit.fields
      customer: entity.customer_id
      amount: entity.total

The durability contract:

The request is persisted in the handler’s transaction (platform.activity_requested); the actual tool call executes only after the transaction commits and the entity lock is released.
A crash between the two replays the persisted request — the call is never lost and never runs inside your state transaction.
The outcome comes back as generated typed result events (success and failure families derived from the tool declaration), which your handlers subscribe to like any event — no hidden runtime state.
Writes that cannot safely be retried — charging a card, sending an email — can require human approval. Add approval: {decision: <stable-decision-id>} and the platform records a pending decision card (proposed_effect) instead of the request — no attempt, no credential lookup, no provider call exists until a human approves. Approval releases the exact recorded request through the same durable path.
In mock mode, activities fail closed — a test run cannot leak a real external call (see Testing).

Getting started

Core concepts

Build a flow

Handlers

Patterns

Operating Swarm

create_flow_instance

record_evidence

Binding values in action blocks

mailbox_write

artifact_repo_commit

Durable activities

​create_flow_instance

​record_evidence

​Binding values in action blocks

​mailbox_write

​artifact_repo_commit

​Durable activities

create_flow_instance

record_evidence

Binding values in action blocks

mailbox_write

artifact_repo_commit

Durable activities