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

AWS Lambda Durable Functions

AWSOfficialPublished by AWS

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

From the author

Builds 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, durable execution, workflow orchestration, state machines, retry/checkpoint patterns, long-running stateful Lambda functions, saga pattern, human-in-the-loop callbacks, reliable serverless applications, context.step, context.wait, context.invoke, context.runInChildContext, withDurableExecution, DurableContext, UnrecoverableInvocationError, durable-execution-sdk, qualified ARN invocation, and durable handler replay.
— the description by AWS

AutoGineer summary

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

This skill provides guidance and patterns for implementing durable, multi-step applications on AWS Lambda. It focuses on the replay model, which allows functions to maintain state across long-running executions—up to one year—by automatically checkpointing progress. The skill covers essential architectural patterns such as the saga pattern for error handling, wait/callback mechanisms for external system integration, and testing strategies using the local test runner. It emphasizes strict adherence to deterministic coding practices required by the replay model to ensure reliable execution.

What it does

  • Enables state persistence for long-running Lambda functions.
  • Provides patterns for implementing the saga pattern and compensating transactions.
  • Supports wait/callback patterns for integrating with external systems.
  • Offers guidance on testing durable functions locally and in the cloud.
  • Defines rules for deterministic code to prevent state corruption during replays.
  • Outlines requirements for qualified ARN invocation and IAM permissions.

When to use it

  • When building workflows that require execution times longer than standard Lambda timeouts.
  • When orchestrating multi-step processes that need to maintain state across interruptions.
  • When implementing reliable, fault-tolerant serverless integrations.
  • When managing complex state machines or human-in-the-loop approval processes.
  • When you need automatic retry logic and checkpointing for critical business processes.

Advantages

  • Resilient execution that survives infrastructure interruptions.
  • Simplified state management without external databases for simple workflows.
  • Native support for complex orchestration patterns like sagas and parallel execution.
  • Built-in replay-aware logging and error handling.
  • Local testing capabilities to validate complex workflow logic.

Usage examples

“How do I implement a multi-step workflow with a wait period in AWS Lambda?”
The agent provides a code example using context.step for logic and context.wait for the delay, ensuring the execution state is persisted correctly.
“Why is my durable function failing during replay?”
The agent helps diagnose non-deterministic code (like Date.now() or Math.random()) placed outside of steps, which causes state corruption.
“How do I handle errors in a long-running durable function?”
The agent explains the saga pattern and how to implement compensating transactions within steps to roll back state if a step fails.
“What are the requirements for invoking a durable Lambda function?”
The agent clarifies that durable functions must be invoked using a qualified ARN (version, alias, or $LATEST) and provides the corresponding AWS CLI command.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/aws/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

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.

Works best with the AWS MCP server but is not required. All AWS interactions in this skill use standard AWS CLI commands that work in any environment with configured AWS credentials.

Critical Rules

Read these before writing any code. Each one is a constraint that will silently break a function if violated.

  1. Durable execution must be enabled at function creation time — it cannot be retrofitted. A new Lambda function must be created with durable execution turned on. Migrate the logic into the new function; do not attempt to install the SDK and wrap the handler of the existing function and expect it to work.

  2. Durable functions must be invoked with a qualified ARN — a specific version, an alias, or the literal $LATEST suffix. An unqualified function name will fail. See the Invocation Requirements section below for examples.

  3. Durable operations cannot be nested. You cannot call context.step(), context.wait(), or context.invoke() from inside another step's callback. Use context.runInChildContext() to group operations instead.

  4. All non-deterministic code must run inside steps. Date.now(), Math.random(), UUID generation, API calls, and database queries outside a step will produce different values on replay and corrupt execution state.

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

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

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
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:live 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

Security Considerations

  • Checkpoint data encryption: Execution state is persisted automatically. Enable KMS encryption on associated CloudWatch Log Groups to protect checkpointed data at rest.

  • Sensitive data in step results: Step return values are checkpointed and persisted. Do not return secrets, raw credentials, or PII from steps — store sensitive data in Secrets Manager or SSM Parameter Store and return references instead.

  • Input validation: Validate and sanitize event payloads at the handler entry point before passing data to steps.

  • Credential management: Retrieve secrets from AWS Secrets Manager or SSM Parameter Store within steps.

  • Callback payload validation: Data received via waitForCallback originates from external systems — validate and sanitize before processing.

  • Logging: Avoid DEBUG log level in non-development environments as it may expose step results and execution state. Enable CloudWatch Logs encryption with KMS.

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

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
Publisher
AWS (Official)
Source
aws/agent-toolkit-for-aws · skills/specialized-skills/serverless-skills/aws-lambda-durable-functions · commit 0a218f8
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 or AWS.

Download ZIP

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