Run step `flow.step`

A step delegates one external operation to a handler registered by the host. Common handlers call a model, MCP tool, HTTP service, database operation, or business API. Flow records the schedule request, attempts, and committed result. The host owns credentials, permission checks, network access, and actual side effects. step_name must match a stable entry in the host registry, and deployment should prove that the handler is available before runs use it.

Input and retries

The input expression builds task parameters from start data or committed upstream results. The resulting input remains stable across retries, so the expression must not pull a fresh time, random number, or mutable process value. If the task needs such a value, create it inside the host handler and return it as a committed result. For large files or model responses, pass an object reference instead of placing an entire payload in event history.

max_attempts includes the first execution. retry_delay_ms is the wait before another attempt. With on_exhausted set to fail_run, exhausted attempts end the run. With continue_workflow, the node exposes failed control and error data so the graph can compensate, degrade, or request human action. An external idempotency key should include run, node, and attempt identity.

Ports and operational checks

success and result become available only after the result commits. A process can exit after an external operation succeeds but before that commit, so the same attempt may be delivered again. Test this path against the real handler. Connect failed and error only when the continuation policy enables them. Before production, review timeouts, error redaction, handler build routing, compensation, retry bounds, and behavior for permanent failures.

Use it for one host-registered task such as a tool call, HTTP request, database write, or business service. The task owns one input, result, and retry policy.

Runtime behavior

The graph node ID becomes the durable step identity. The success port opens after a result is committed; exhausted retries either fail the run or expose the failure port.

Node contract

Type: flow.step
Role: Durable runtime command
Runtime binding: schedule_step
Durable identity: Graph node ID

Configuration properties

Property	Type and control	Default	Rules
`step_name`Step handler	`str`StrInput	`task.run`	Registered task that this step runs.Required
`input`Step input	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}}`	Choose the workflow data sent to the task.Optional
`max_attempts`Maximum attempts	`int`IntInput	`3`	Total attempts for this step, including the first execution.Required · Advanced · Range 1 to 100 / 1
`retry_delay_ms`Retry delay (ms)	`int`IntInput	`0`	Wait time before the next attempt. Use 0 to retry immediately.Required · Advanced · Range 0 to 86400000 / 100
`on_exhausted`If all attempts fail	`str`DropdownInput	`fail_run`	End the run, or continue from the failure branch.Required · Advanced · Allowed values fail_run, continue_workflow

Ports

Direction	Port ID	Kind	Value types
Input	`in`In	control	`FlowControl`
Input	`input`Input	data	`JsonValue`
Output	`success`Success	control	`FlowControl`
Output	`result`Result	data	`JsonValue`
Output	`failed`Recoverable failure	control	`FlowControl`
Output	`error`Recoverable error	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-step",
  "data": {
    "step_name": "task.run",
    "input": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "field",
        "path": "input"
      }
    },
    "max_attempts": 3,
    "retry_delay_ms": 0,
    "on_exhausted": "fail_run",
    "type": "flow.step"
  }
}

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.step --pretty
a3s-flow new flow.step --id example-flow-step --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.step" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

The host task must tolerate at-least-once delivery.
Derive external idempotency from run, node, and attempt identity.
Connect the failed port only when exhaustion continues through the graph.

#Run step flow.step

#Input and retries

#Ports and operational checks