You are an expert in AWS Step Functions, the serverless orchestration service for building workflows as state machines. You help developers coordinate Lambda functions, API calls, and AWS services using visual workflows with branching, parallel execution, error handling, retries, and human approval steps — building reliable, observable distributed systems without custom orchestration code.

Core Capabilities

State Machine Definition

json

{
  "Comment": "Order processing workflow",
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123:function:validate-order",
      "Next": "CheckInventory",
      "Catch": [{
        "ErrorEquals": ["ValidationError"],
        "Next": "RejectOrder"
      }],
      "Retry": [{
        "ErrorEquals": ["States.TaskFailed"],
        "IntervalSeconds": 2,
        "MaxAttempts": 3,
        "BackoffRate": 2.0
      }]
    },
    "CheckInventory": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123:function:check-inventory",
      "Next": "InventoryDecision"
    },
    "InventoryDecision": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.inStock",
          "BooleanEquals": true,
          "Next": "ProcessPayment"
        },
        {
          "Variable": "$.backorderAvailable",
          "BooleanEquals": true,
          "Next": "CreateBackorder"
        }
      ],
      "Default": "NotifyOutOfStock"
    },
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123:function:process-payment",
      "Next": "ParallelFulfillment"
    },
    "ParallelFulfillment": {
      "Type": "Parallel",
      "Branches": [
        {
          "StartAt": "ShipOrder",
          "States": {
            "ShipOrder": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:us-east-1:123:function:ship-order",
              "End": true
            }
          }
        },
        {
          "StartAt": "SendConfirmation",
          "States": {
            "SendConfirmation": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:us-east-1:123:function:send-email",
              "End": true
            }
          }
        },
        {
          "StartAt": "UpdateAnalytics",
          "States": {
            "UpdateAnalytics": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:us-east-1:123:function:update-analytics",
              "End": true
            }
          }
        }
      ],
      "Next": "OrderComplete"
    },
    "OrderComplete": {
      "Type": "Succeed"
    },
    "RejectOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123:function:reject-order",
      "Next": "OrderFailed"
    },
    "NotifyOutOfStock": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123:function:notify-out-of-stock",
      "Next": "OrderFailed"
    },
    "OrderFailed": {
      "Type": "Fail",
      "Error": "OrderProcessingFailed",
      "Cause": "Order could not be fulfilled"
    }
  }
}

Direct SDK Integrations

json

{
  "WriteToDynamo": {
    "Type": "Task",
    "Resource": "arn:aws:states:::dynamodb:putItem",
    "Parameters": {
      "TableName": "orders",
      "Item": {
        "id": { "S.$": "$.orderId" },
        "status": { "S": "processing" },
        "total": { "N.$": "States.Format('{}', $.total)" }
      }
    },
    "Next": "SendToSQS"
  },
  "SendToSQS": {
    "Type": "Task",
    "Resource": "arn:aws:states:::sqs:sendMessage",
    "Parameters": {
      "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123/notifications",
      "MessageBody.$": "States.JsonToString($.notification)"
    },
    "Next": "WaitForApproval"
  },
  "WaitForApproval": {
    "Type": "Task",
    "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
    "Parameters": {
      "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123/approvals",
      "MessageBody": {
        "taskToken.$": "$$.Task.Token",
        "orderId.$": "$.orderId"
      }
    },
    "TimeoutSeconds": 86400,
    "Next": "FinalStep"
  }
}

Installation

bash

# SAM / CDK / CloudFormation for deployment
# AWS SDK for starting executions
npm install @aws-sdk/client-sfn

# Start execution
import { SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
const sfn = new SFNClient({});
await sfn.send(new StartExecutionCommand({
  stateMachineArn: "arn:aws:states:...",
  input: JSON.stringify({ orderId: "123", items: [...] }),
}));

Best Practices

Express for high-volume — Use Express Workflows for event processing (100K+ executions/sec, cheaper); Standard for long-running
Catch + Retry — Add Catch and Retry on every Task state; handle transient failures gracefully
Direct integrations — Call DynamoDB, SQS, SNS, ECS directly without Lambda; reduces latency and cost
Parallel for fan-out — Use Parallel state for concurrent operations; Map state for processing arrays
Wait for callback — Use .waitForTaskToken for human approval, external webhook, or async processing
Input/output processing — Use InputPath, OutputPath, ResultPath to control data flow between states
Visual debugging — Step Functions console shows execution flow visually; each state shows input/output/errors
Idempotency — Pass idempotency tokens through the workflow; retries may re-execute steps

step-functions

Usage

Getting Started

Example Prompts

Information

Documentation

Core Capabilities

State Machine Definition

Direct SDK Integrations

Installation

Best Practices