Run step batch `flow.batch`

A batch declares several host tasks that may advance independently and reports results in declaration order. It works well for a bounded, known set such as checking several records or calling a fixed group of tools. If the collection is large or must resume page by page, split it with a stable cursor or use an iteration container so each member has a clearer scope.

Member settings

Each entry in steps has step_key, step_name, input_mapping, max_attempts, retry_delay_ms, and on_exhausted. The key must be unique inside the node and combines with the graph node ID to form durable task identity. Members may finish in any order, but keys and declaration order must not be rebuilt from completion order. When a graph already has runs, preserve every member key and its semantic position.

Each input_mapping creates separate parameters and retry settings apply per member. If at least one member chooses continue_workflow, the node exposes recoverable_failure and errors so downstream logic can inspect failed members. The default fail_run closes the run when that member exhausts attempts. Host handlers still need at-least-once safety, with idempotency derived from run, node, member, and attempt identity.

Results and capacity

After every member resolves, control continues through done and results follows declaration order. Recoverable errors preserve that order as well, so array position must not be interpreted as completion time. Test empty lists, duplicate keys, partial failure, complete failure, process recovery, and large results. Store references for large outputs. Bound the batch against host concurrency, queue capacity, and tenant limits so one node cannot submit more work than downstream systems can absorb.

Use it to declare host tasks that can advance independently. Members are stored in a fixed order and keep separate names, inputs, and retry policies.

Runtime behavior

The node ID and member key form each durable step identity. The engine records the whole batch before advancing unfinished work and reports results in declaration order.

Node contract

Type: flow.batch
Role: Durable runtime command
Runtime binding: schedule_steps
Durable identity: Graph node ID plus member key

Configuration properties

Property	Type and control	Default	Rules
`steps`Steps to run	`table`A3SFlowBatchInput	`[{"step_key":"member-1","step_name":"task.run","input_mapping":{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}},"max_attempts":3,"retry_delay_ms":0,"on_exhausted":"fail_run"}]`	Steps run in list order. Each member needs a stable, unique ID.Required

Steps to run

Property	Type and control	Default	Rules
`step_key`Step key	`string`	`Not set`	Unique member key; the host combines it with the immutable batch graph node ID.Required
`step_name`Handler	`string`	`Not set`	Registered host step handler.Required
`input_mapping`Input mapping	`object`	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}}`	Versioned deterministic expression resolved before scheduling.Required
`max_attempts`Attempts	`int`	`3`	Total attempts including the first execution.Required
`retry_delay_ms`Delay (ms)	`int`	`0`	Durable delay between attempts.Required
`on_exhausted`After retries	`string`	`fail_run`	Fail the run or continue workflow replay.Required

steps member properties

Property	Type and control	Rules
`step_key`	`string`	Stable unique member identity within the batchRequired
`step_name`	`string`	Task name registered by the hostRequired
`input_mapping`	`FlowExpression`	Builds input for this memberRequired
`max_attempts`	`integer`	Total attempts including the first executionRequired
`retry_delay_ms`	`integer`	Milliseconds before the next attemptRequired
`on_exhausted`	`fail_run \| continue_workflow`	Behavior after retries are exhaustedRequired

Ports

Direction	Port ID	Kind	Value types
Input	`in`In	control	`FlowControl`
Input	`input`Input	data	`JsonValue`
Output	`done`Done	control	`FlowControl`
Output	`results`Results	data	`JsonValue[]`
Output	`recoverable_failure`Recoverable failure	control	`FlowControl`
Output	`errors`Recoverable errors	data	`String[]`

Node JSON example

The CLI creates the same structure from manifest defaults. Canvas position, title, and selection are presentation data.

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-batch",
  "data": {
    "steps": [
      {
        "step_key": "member-1",
        "step_name": "task.run",
        "input_mapping": {
          "apiVersion": "a3s.dev/flow-expression/v1",
          "expression": {
            "op": "field",
            "path": "input"
          }
        },
        "max_attempts": 3,
        "retry_delay_ms": 0,
        "on_exhausted": "fail_run"
      }
    ],
    "type": "flow.batch"
  }
}

CLI usage

Inspect the installed manifest first, then create the node and validate the complete workflow. Every command emits JSON.

Terminal

a3s-flow node flow.batch --pretty
a3s-flow new flow.batch --id example-flow-batch --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill usage

The package includes the a3s-flow Skill. It queries the CLI catalog before creating, validating, compiling, and digesting a workflow.

Prompt

Use $a3s-flow to add the "flow.batch" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

Member keys must be non-empty and unique.
Never renumber members by completion order.
Window large batches with a stable cursor from workflow input.

#Run step batch flow.batch

#Member settings

#Results and capacity