For AI agents: the complete documentation index is available at https://a3s-lab.github.io/Flow/en/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/Flow/en/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/Flow/en/nodes/step.md.
A3S Flow
  • English
  • v1.1.0

      • 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

      PropertyType and controlDefaultRules
      step_nameStep handlerstrStrInputtask.runRegistered task that this step runs.Required
      inputStep inputdictA3SFlowExpressionInput{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}}Choose the workflow data sent to the task.Optional
      max_attemptsMaximum attemptsintIntInput3Total attempts for this step, including the first execution.Required · Advanced · Range 1 to 100 / 1
      retry_delay_msRetry delay (ms)intIntInput0Wait time before the next attempt. Use 0 to retry immediately.Required · Advanced · Range 0 to 86400000 / 100
      on_exhaustedIf all attempts failstrDropdownInputfail_runEnd the run, or continue from the failure branch.Required · Advanced · Allowed values fail_run, continue_workflow

      Ports

      DirectionPort IDKindValue types
      InputinIncontrolFlowControl
      InputinputInputdataJsonValue
      OutputsuccessSuccesscontrolFlowControl
      OutputresultResultdataJsonValue
      OutputfailedRecoverable failurecontrolFlowControl
      OutputerrorRecoverable errordataString

      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.