AutoGineer
Generated banner for AWS Lambda Durable Functions
Generated logo for AWS Lambda Durable Functions

AWS Lambda Durable Functions

AWS LabsOfficialPublished by AWS Labs

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Low risk
Download ZIP

From the author

Build resilient, long-running, multi-step applications with AWS Lambda durable functions with automatic state persistence, retry logic, and orchestration for long-running executions. Covers the critical replay model, step operations, wait/callback patterns, error handling with saga pattern, testing with LocalDurableTestRunner. Triggers on phrases like: lambda durable functions, workflow orchestration, state machines, retry/checkpoint patterns, long-running stateful Lambda functions, saga pattern, human-in-the-loop callbacks, and reliable serverless applications.
— the description by AWS Labs

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The AWS Lambda Durable Functions skill provides a framework for orchestrating complex, multi-step applications that require long-running execution, automatic state persistence, and robust error handling. It enables developers to implement patterns like sagas, human-in-the-loop callbacks, and retries while ensuring progress is maintained across interruptions. The skill covers the replay model, step operations, and testing strategies for both TypeScript and Python environments, helping developers build reliable serverless architectures that can run for up to a year.

What it does

  • Orchestrates multi-step serverless workflows with automatic state persistence.
  • Implements complex error handling patterns including sagas and circuit breakers.
  • Supports long-running executions with wait/callback patterns and human-in-the-loop integration.
  • Provides a replay-aware environment to ensure determinism in distributed serverless functions.
  • Offers testing utilities via LocalDurableTestRunner for local development and validation.
  • Enables dynamic step naming and advanced concurrency patterns for AI agents and batch processing.

When to use it

  • When building workflows that need to persist state across multiple Lambda invocations.
  • When implementing long-running processes that require wait times or external system callbacks.
  • When you need robust retry logic and error recovery for distributed serverless tasks.
  • When developing complex state machines or saga-based transaction management in AWS.
  • When creating AI agent workflows that require reasoning and multi-step tool execution.

Advantages

  • Maintains reliable progress for workflows that may run for up to one year.
  • Simplifies complex orchestration logic through a structured replay model.
  • Provides built-in support for idempotent operations and retry strategies.
  • Enables local testing of distributed stateful logic before cloud deployment.
  • Reduces boilerplate code for managing state, timeouts, and error recovery.

Usage examples

“How do I implement a retry strategy for a database update in a durable function?”
The agent provides a code example using context.step with retry options, explaining how to classify errors as transient or permanent to ensure only appropriate operations are retried.
“Show me how to wait for an external callback in a Python durable function.”
The agent generates a Python snippet using context.wait_for_callback, including configuration for timeouts and fallback logic to handle cases where the callback is not received.
“I am getting a non-deterministic error in my Lambda function, how do I fix it?”
The agent explains the replay model, identifies non-deterministic code (like Date.now or API calls) outside of steps, and provides a refactored code block moving those calls into context.step.
“How do I test my durable function locally?”
The agent guides the user to use the LocalDurableTestRunner, providing a template for instantiating the runner with their handler and executing test cases to verify replay behavior.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/awslabs/aws-lambda-durable-functions/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip aws-lambda-durable-functions.zip -d .agents/skills

Documentation by AWS Labs

AWS Lambda durable functions

Build resilient multi-step applications and AI workflows that can execute for up to 1 year while maintaining reliable progress despite interruptions.

Onboarding

Step 1: Validate Prerequisites

Before using AWS Lambda durable functions, verify:

  1. AWS CLI is installed (2.33.22 or higher) and configured:

    aws --version
aws sts get-caller-identity

  2. Runtime environment is ready:

    • For TypeScript/JavaScript: Node.js 22+ (node --version)

    • For Python: Python 3.11+ (python --version. Note that currently only Lambda runtime environments 3.13+ come with the Durable Execution SDK pre-installed. 3.11 is the min supported Python version by the Durable SDK itself, however, you could use OCI to bring your own container image with your own Python runtime + Durable SDK.)

  3. Deployment capability exists (one of):

    • AWS SAM CLI (sam --version) 1.153.1 or higher

    • AWS CDK (cdk --version) v2.237.1 or higher

    • Direct Lambda deployment access

Step 2: Select language and IaC framework
Language Selection

Default: TypeScript

Override syntax:

  • "use Python" → Generate Python code

  • "use JavaScript" → Generate JavaScript code

When not specified, ALWAYS use TypeScript

IaC framework selection

Default: CDK

Override syntax:

  • "use CloudFormation" → Generate YAML templates

  • "use SAM" → Generate YAML templates

When not specified, ALWAYS use CDK

Error Scenarios
Unsupported Language

  • List detected language

  • State: "Durable Execution SDK is not yet available for [framework]"

  • Suggest supported languages as alternatives

Unsupported IaC Framework

  • List detected framework

  • State: "[framework] might not support Lambda durable functions yet"

  • Suggest supported frameworks as alternatives

Serverless MCP Server Unavailable

  • Inform user: "AWS Serverless MCP not responding"

  • Ask: "Proceed without MCP support?"

  • DO NOT continue without user confirmation

Step 3: Install SDK

For TypeScript/JavaScript:

npm install @aws/durable-execution-sdk-js
npm install --save-dev @aws/durable-execution-sdk-js-testing

For Python:

pip install aws-durable-execution-sdk-python
pip install aws-durable-execution-sdk-python-testing

When to Load Reference Files

Load the appropriate reference file based on what the user is working on:

  • Getting started, basic setup, example, ESLint, or Jest setup -> see getting-started.md

  • Understanding replay model, determinism, or non-deterministic errors -> see replay-model-rules.md

  • Creating steps, atomic operations, or retry logic -> see step-operations.md

  • Waiting, delays, callbacks, external systems, or polling -> see wait-operations.md

  • Parallel execution, map operations, batch processing, or concurrency -> see concurrent-operations.md

  • Error handling, retry strategies, saga pattern, or compensating transactions -> see error-handling.md

  • Advanced error handling, timeout handling, circuit breakers, or conditional retries -> see advanced-error-handling.md

  • Testing, local testing, cloud testing, test runner, or flaky tests -> see testing-patterns.md

  • Deployment, CloudFormation, CDK, SAM, log groups, deploy, or infrastructure -> see deployment-iac.md

  • Advanced patterns, GenAI agents, completion policies, step semantics, or custom serialization -> see advanced-patterns.md

  • troubleshooting, stuck execution, failed execution, debug execution ID, execution history, execution error, why did my execution fail, execution timed out, callback not received, diagnose execution, or root cause execution -> see troubleshooting-executions.md

Quick Reference

Basic Handler Pattern

TypeScript:

import { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';

export const handler = withDurableExecution(async (event, context: DurableContext) => {
  const result = await context.step('process', async () => processData(event));
  return result;
});

Python:

from aws_durable_execution_sdk_python import durable_execution, DurableContext

@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
    result = context.step(lambda _: process_data(event), name='process')
    return result
Critical Rules

  1. All non-deterministic code MUST be in steps (Date.now, Math.random, API calls)

  2. Cannot nest durable operations - use runInChildContext to group operations

  3. Closure mutations are lost on replay - return values from steps

  4. Side effects outside steps repeat - use context.logger (replay-aware)

Python API Differences

The Python SDK differs from TypeScript in several key areas:

  • Steps: Use @durable_step decorator + context.step(my_step(args)), or inline context.step(lambda _: ..., name='...'). Prefer the decorator for automatic step naming.

  • Wait: context.wait(duration=Duration.from_seconds(n), name='...')

  • Exceptions: ExecutionError (permanent), InvocationError (transient), CallbackError (callback failures)

  • Testing: Use DurableFunctionTestRunner class directly - instantiate with handler, use context manager, call run(input=...)

Invocation Requirements

Durable functions require qualified ARNs (version, alias, or $LATEST):

# Valid
aws lambda invoke --function-name my-function:1 output.json
aws lambda invoke --function-name my-function:prod output.json

# Invalid - will fail
aws lambda invoke --function-name my-function output.json

IAM Permissions

Your Lambda execution role MUST have the AWSLambdaBasicDurableExecutionRolePolicy managed policy attached. This includes:

  • lambda:CheckpointDurableExecution - Persist execution state

  • lambda:GetDurableExecutionState - Retrieve execution state

  • CloudWatch Logs permissions

Additional permissions needed for:

  • Durable invokes: lambda:InvokeFunction on target function ARNs

  • External callbacks: Systems need lambda:SendDurableExecutionCallbackSuccess and lambda:SendDurableExecutionCallbackFailure

Validation Guidelines

When writing or reviewing durable function code, ALWAYS check for these replay model violations:

  1. Non-deterministic code outside steps: Date.now(), Math.random(), UUID generation, API calls, database queries must all be inside steps

  2. Nested durable operations in step functions: Cannot call context.step(), context.wait(), or context.invoke() inside a step function — use context.runInChildContext() instead

  3. Closure mutations that won't persist: Variables mutated inside steps are NOT preserved across replays — return values from steps instead

  4. Side effects outside steps that repeat on replay: Use context.logger for logging (it is replay-aware and deduplicates automatically)

When implementing or modifying tests for durable functions, ALWAYS verify:

  1. All operations have descriptive names

  2. Tests get operations by NAME, never by index

  3. Replay behavior is tested with multiple invocations

  4. Use LocalDurableTestRunner for local testing

MCP Server Configuration

Write access is enabled by default. The plugin ships with --allow-write in .mcp.json, so the MCP server can create projects, generate IaC, and deploy on behalf of the user.

Access to sensitive data (like Lambda and API Gateway logs) is not enabled by default. To grant it, add --allow-sensitive-data-access to .mcp.json.

Resources

Files

references/replay-model-rules.md

Replay Model Rules - CRITICAL

The replay model is the foundation of durable functions. Violations cause subtle, hard-to-debug issues. Read this carefully.

How Replay Works

Durable functions use a "checkpoint and replay" execution model:

  1. Code runs from the beginning on every invocation

  2. Steps that already completed return their checkpointed results WITHOUT re-executing

  3. Code OUTSIDE steps executes again on every replay

  4. New steps execute when reached

Example:

// First execution: Runs lines 1-5
// After wait: Runs lines 1-5 again (line 2 returns cached result)
const data = await context.step('fetch', async () => fetchAPI());  // Line 2: Executes once, cached
await context.wait({ seconds: 60 });                                // Line 3: Waits
const result = await context.step('process', async () => process(data)); // Line 5: Executes after wait

Rule 1: Deterministic Code Outside Steps

ALL code outside steps MUST produce the same result on every replay.

❌ WRONG - Non-Deterministic Outside Steps

TypeScript:

// These values change on each replay!
const id = uuid.v4();                    // Different UUID each time
const timestamp = Date.now();            // Different timestamp each time
const random = Math.random();            // Different random number
const now = new Date();                  // Different date each time

await context.step('save', async () => saveData({ id, timestamp }));

Python:

# These values change on each replay!
id = str(uuid.uuid4())                   # Different UUID each time
timestamp = time.time()                  # Different timestamp each time
random_val = random.random()             # Different random number
now = datetime.now()                     # Different datetime each time

context.step(lambda _: save_data({"id": id}), name='save')
✅ CORRECT - Non-Deterministic Inside Steps

TypeScript:

const id = await context.step('generate-id', async () => uuid.v4());
const timestamp = await context.step('get-time', async () => Date.now());
const random = await context.step('random', async () => Math.random());
const now = await context.step('get-date', async () => new Date());

await context.step('save', async () => saveData({ id, timestamp }));

Python:

id = context.step(lambda _: str(uuid.uuid4()), name='generate-id')
timestamp = context.step(lambda _: time.time(), name='get-time')
random_val = context.step(lambda _: random.random(), name='random')
now = context.step(lambda _: datetime.now(), name='get-date')

context.step(lambda _: save_data({"id": id}), name='save')
Must Be In Steps

  • Date.now(), new Date(), time.time(), datetime.now()

  • Math.random(), random.random()

  • UUID generation (uuid.v4(), uuid.uuid4())

  • API calls, HTTP requests

  • Database queries

  • File system operations

  • Environment variable reads (if they can change)

  • Any external system interaction

Rule 2: No Nested Durable Operations

You CANNOT call durable operations inside a step function.

❌ WRONG - Nested Operations

TypeScript:

await context.step('process', async () => {
  await context.wait({ seconds: 1 });      // ERROR!
  await context.step(async () => ...);     // ERROR!
  await context.invoke('other-fn', ...);   // ERROR!
  return result;
});

Python:

@durable_step
def process(step_ctx: StepContext):
    context.wait(duration=Duration.from_seconds(1))  # ERROR!
    context.step(lambda _: ..., name='nested')       # ERROR!
    return result

context.step(process())
✅ CORRECT - Use Child Context

TypeScript:

await context.runInChildContext('process', async (childCtx) => {
  await childCtx.wait({ seconds: 1 });
  const step1 = await childCtx.step('validate', async () => validate());
  const step2 = await childCtx.step('process', async () => process(step1));
  return step2;
});

Python:

# Note: validate and process are decorated with @durable_step
def process_child(child_ctx: DurableContext):
    child_ctx.wait(duration=Duration.from_seconds(1))
    step1 = child_ctx.step(validate())
    step2 = child_ctx.step(process(step1))
    return step2

context.run_in_child_context(func=process_child, name='process')

Rule 3: Closure Mutations Are Lost

Variables mutated inside steps are NOT preserved across replays.

❌ WRONG - Lost Mutations

TypeScript:

let counter = 0;
await context.step('increment', async () => {
  counter++;  // This mutation is lost!
});
console.log(counter);  // Always 0 on replay!

Python:

counter = 0
@durable_step
def increment(step_ctx: StepContext):
    nonlocal counter
    counter += 1  # This mutation is lost!

context.step(increment())
print(counter)  # Always 0 on replay!
✅ CORRECT - Return Values

TypeScript:

let counter = 0;
counter = await context.step('increment', async () => counter + 1);
console.log(counter);  // Correct value

Python:

counter = 0
counter = context.step(lambda _: counter + 1, name='increment')
print(counter)  # Correct value

Rule 4: Side Effects Outside Steps Repeat

Side effects outside steps happen on EVERY replay.

❌ WRONG - Repeated Side Effects

TypeScript:

console.log('Starting process');     // Logs multiple times!
await sendEmail(user.email);         // Sends multiple emails!
await updateDatabase(data);          // Updates multiple times!

await context.step('process', async () => process());

Python:

print('Starting process')            # Prints multiple times!
send_email(user.email)               # Sends multiple emails!
update_database(data)                # Updates multiple times!

context.step(lambda _: process(), name='process')
✅ CORRECT - Side Effects In Steps

TypeScript:

context.logger.info('Starting process');  // Deduplicated automatically
await context.step('send-email', async () => sendEmail(user.email));
await context.step('update-db', async () => updateDatabase(data));
await context.step('process', async () => process());

Python:

# Note: Functions are decorated with @durable_step
context.logger.info('Starting process')  # Deduplicated automatically
context.step(send_email(user.email))
context.step(update_database(data))
context.step(process())
Exception: context.logger

context.logger is replay-aware and safe to use anywhere. It automatically deduplicates logs across replays.

Common Pitfalls

Pitfall 1: Reading Environment Variables
// ❌ WRONG if env vars can change
const apiKey = process.env.API_KEY;
await context.step('call-api', async () => callAPI(apiKey));

// ✅ CORRECT
const apiKey = await context.step('get-key', async () => process.env.API_KEY);
await context.step('call-api', async () => callAPI(apiKey));
Pitfall 2: Array/Object Mutations
// ❌ WRONG
const items = [];
await context.step('add-item', async () => {
  items.push(newItem);  // Lost on replay
});

// ✅ CORRECT
let items = [];
items = await context.step('add-item', async () => [...items, newItem]);
Pitfall 3: Conditional Logic with Non-Deterministic Values
// ❌ WRONG
if (Math.random() > 0.5) {  // Different on each replay!
  await context.step('path-a', async () => ...);
} else {
  await context.step('path-b', async () => ...);
}

// ✅ CORRECT
const shouldTakePathA = await context.step('decide', async () => Math.random() > 0.5);
if (shouldTakePathA) {
  await context.step('path-a', async () => ...);
} else {
  await context.step('path-b', async () => ...);
}

Debugging Replay Issues

If you see inconsistent behavior:

  1. Check for non-deterministic code outside steps

  2. Verify no nested durable operations

  3. Look for closure mutations

  4. Search for side effects outside steps

  5. Use context.logger to trace execution flow

Testing Replay Behavior

Always test with multiple invocations to simulate replay:

const runner = new LocalDurableTestRunner({ handlerFunction: handler });
const execution = await runner.run({ payload: { test: true } });

// Verify operations executed correctly
const step1 = runner.getOperation('step-name');
expect(step1.getStatus()).toBe(OperationStatus.SUCCEEDED);

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs a command-line tool, Needs Python, Needs Node.js

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
AWS Labs
Publisher
AWS Labs (Official)
Source
awslabs/agent-plugins · plugins/aws-serverless/skills/aws-lambda-durable-functions · commit fbefb37
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • NOTICE (added by AutoGineer from NOTICE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by AWS Labs.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-lambda-durable-functions.zip