AWS Lambda Durable Functions
AWS LabsOfficialPublished by AWS Labs
- Skill
- Tool integration
- Cloud and DevOps
- Apache-2.0
- Low risk
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
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/awslabs/aws-lambda-durable-functions/downloadUnzip 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:
AWS CLI is installed (2.33.22 or higher) and configured:
aws --version aws sts get-caller-identityRuntime 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.)
Deployment capability exists (one of):
AWS SAM CLI (
sam --version) 1.153.1 or higherAWS CDK (
cdk --version) v2.237.1 or higherDirect 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-testingFor Python:
pip install aws-durable-execution-sdk-python
pip install aws-durable-execution-sdk-python-testingWhen 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 resultCritical Rules
All non-deterministic code MUST be in steps (Date.now, Math.random, API calls)
Cannot nest durable operations - use
runInChildContextto group operationsClosure mutations are lost on replay - return values from steps
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_stepdecorator +context.step(my_step(args)), or inlinecontext.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
DurableFunctionTestRunnerclass directly - instantiate with handler, use context manager, callrun(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.jsonIAM Permissions
Your Lambda execution role MUST have the AWSLambdaBasicDurableExecutionRolePolicy managed policy attached. This includes:
lambda:CheckpointDurableExecution- Persist execution statelambda:GetDurableExecutionState- Retrieve execution stateCloudWatch Logs permissions
Additional permissions needed for:
Durable invokes:
lambda:InvokeFunctionon target function ARNsExternal callbacks: Systems need
lambda:SendDurableExecutionCallbackSuccessandlambda:SendDurableExecutionCallbackFailure
Validation Guidelines
When writing or reviewing durable function code, ALWAYS check for these replay model violations:
Non-deterministic code outside steps:
Date.now(),Math.random(), UUID generation, API calls, database queries must all be inside stepsNested durable operations in step functions: Cannot call
context.step(),context.wait(), orcontext.invoke()inside a step function — usecontext.runInChildContext()insteadClosure mutations that won't persist: Variables mutated inside steps are NOT preserved across replays — return values from steps instead
Side effects outside steps that repeat on replay: Use
context.loggerfor logging (it is replay-aware and deduplicates automatically)
When implementing or modifying tests for durable functions, ALWAYS verify:
All operations have descriptive names
Tests get operations by NAME, never by index
Replay behavior is tested with multiple invocations
Use
LocalDurableTestRunnerfor 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
- ATTRIBUTION.mdAdded by AutoGineer942 B
- LICENSELicence file added by AutoGineer9.9 KiB
- NOTICELicence file added by AutoGineer89 B
- SKILL.md9.0 KiB
- references/advanced-error-handling.md4.9 KiB
- references/advanced-patterns.md9.8 KiB
- references/concurrent-operations.md8.4 KiB
- references/deployment-iac.md14.3 KiB
- references/error-handling.md10.9 KiB
- references/getting-started.md11.1 KiB
- references/replay-model-rules.md8.3 KiB
- references/step-operations.md7.4 KiB
- references/testing-patterns.md17.4 KiB
- references/troubleshooting-executions.md8.2 KiB
- references/wait-operations.md9.5 KiB
references/error-handling.md
Error Handling and Retry Strategies
Comprehensive error handling patterns for durable functions.
TypeScript:
import { createRetryStrategy, JitterStrategy } from '@aws/durable-execution-sdk-js';
// Exponential backoff with jitter
const result = await context.step(
'api-call',
async () => callAPI(),
{
retryStrategy: createRetryStrategy({
maxAttempts: 5,
initialDelay: { seconds: 1 },
maxDelay: { seconds: 60 },
backoffRate: 2.0,
jitter: JitterStrategy.FULL
})
}
);
// Fixed delay
const result = await context.step(
'simple-retry',
async () => operation(),
{
retryStrategy: createRetryStrategy({
maxAttempts: 3,
delay: { seconds: 5 },
backoffRate: 1
})
}
);Python:
from aws_durable_execution_sdk_python.retries import RetryStrategyConfig, create_retry_strategy, JitterStrategy
retry_config = RetryStrategyConfig(
max_attempts=5,
initial_delay=Duration.from_seconds(1),
max_delay=Duration.from_seconds(60),
backoff_rate=2.0,
jitter_strategy=JitterStrategy.FULL
)
result = context.step(
func=api_call(),
config=StepConfig(retry_strategy=create_retry_strategy(retry_config))
)Custom Retry Logic
TypeScript:
const result = await context.step(
'custom-retry',
async () => riskyOperation(),
{
retryStrategy: (error, attemptCount) => {
// Don't retry client errors
if (error.statusCode >= 400 && error.statusCode < 500) {
return { shouldRetry: false };
}
// Retry server errors with exponential backoff
if (attemptCount < 5) {
return {
shouldRetry: true,
delay: { seconds: Math.pow(2, attemptCount) }
};
}
return { shouldRetry: false };
}
}
);Python:
def custom_retry(error: Exception, attempt: int) -> RetryDecision:
if hasattr(error, 'status_code') and 400 <= error.status_code < 500:
return RetryDecision(should_retry=False)
if attempt < 5:
return RetryDecision(
should_retry=True,
delay=Duration.from_seconds(2 ** attempt)
)
return RetryDecision(should_retry=False)Error Classification
Retryable vs Non-Retryable
TypeScript:
class ValidationError extends Error {
name = 'ValidationError';
}
class NetworkError extends Error {
name = 'NetworkError';
}
const result = await context.step(
'selective-retry',
async () => operation(),
{
retryStrategy: createRetryStrategy({
maxAttempts: 3,
retryableErrorTypes: ['NetworkError', 'TimeoutError'],
// ValidationError won't be retried
})
}
);Python:
retry_config = RetryStrategyConfig(
max_attempts=3,
retryable_error_types=[NetworkError, TimeoutError]
)Saga Pattern
Implement compensating transactions for distributed workflows:
TypeScript:
export const handler = withDurableExecution(async (event, context: DurableContext) => {
const compensations: Array<{
name: string;
fn: () => Promise<void>;
}> = [];
try {
// Step 1: Reserve inventory
const reservation = await context.step('reserve-inventory', async () =>
inventoryService.reserve(event.items)
);
compensations.push({
name: 'cancel-reservation',
fn: () => inventoryService.cancelReservation(reservation.id)
});
// Step 2: Charge payment
const payment = await context.step('charge-payment', async () =>
paymentService.charge(event.paymentMethod, event.amount)
);
compensations.push({
name: 'refund-payment',
fn: () => paymentService.refund(payment.id)
});
// Step 3: Create shipment
const shipment = await context.step('create-shipment', async () =>
shippingService.createShipment(event.address, event.items)
);
compensations.push({
name: 'cancel-shipment',
fn: () => shippingService.cancelShipment(shipment.id)
});
return { success: true, orderId: shipment.orderId };
} catch (error) {
context.logger.error('Order failed, executing compensations', error);
// Execute compensations in reverse order
for (const comp of compensations.reverse()) {
try {
await context.step(comp.name, async () => comp.fn());
} catch (compError) {
context.logger.error(`Compensation ${comp.name} failed`, compError);
// Continue with other compensations
}
}
throw error;
}
});Python:
# Note: All service methods are decorated with @durable_step
@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
compensations = []
try:
# Step 1: Reserve inventory
reservation = context.step(reserve_inventory(event['items']))
compensations.append(('cancel-reservation', cancel_reservation, reservation['id']))
# Step 2: Charge payment
payment = context.step(charge_payment(event['payment_method'], event['amount']))
compensations.append(('refund-payment', refund_payment, payment['id']))
# Step 3: Create shipment
shipment = context.step(create_shipment(event['address'], event['items']))
return {'success': True, 'order_id': shipment['order_id']}
except Exception as error:
context.logger.error('Order failed, executing compensations', error)
for name, comp_step, resource_id in reversed(compensations):
try:
context.step(comp_step(resource_id))
except Exception as comp_error:
context.logger.error(f'Compensation {name} failed', comp_error)
raise errorUnrecoverable Errors
Mark errors as unrecoverable to stop execution immediately:
TypeScript:
import { UnrecoverableInvocationError } from '@aws/durable-execution-sdk-js';
export const handler = withDurableExecution(async (event, context: DurableContext) => {
const user = await context.step('fetch-user', async () => {
const user = await fetchUser(event.userId);
if (!user) {
// Stop execution immediately - no retry
throw new UnrecoverableInvocationError('User not found');
}
return user;
});
// Continue processing...
});Python:
from aws_durable_execution_sdk_python.exceptions import ExecutionError
@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
@durable_step
def fetch_user_step(step_ctx: StepContext):
user = fetch_user(event['user_id'])
if not user:
# Stop execution immediately — permanent failure, no retry
raise ExecutionError('User not found')
return user
user = context.step(fetch_user_step())
# Continue processing...The SDK provides these exception types for different failure scenarios:
| Exception | Retryable | Use case |
|---|---|---|
ExecutionError | No | Permanent business logic failures (returns FAILED status) |
InvocationError | Yes (by Lambda) | Transient infrastructure issues (Lambda retries invocation) |
CallbackError | No | Callback handling failures |
DurableExecutionsError | — | Base class for all SDK exceptions |
Error Determinism
Ensure errors are deterministic across replays:
TypeScript:
class CustomBusinessError extends Error {
constructor(
message: string,
public readonly code: string,
public readonly details: any
) {
super(message);
this.name = 'CustomBusinessError';
}
}
const result = await context.step('validate', async () => {
if (!isValid(data)) {
// ✅ Deterministic error
throw new CustomBusinessError(
'Validation failed',
'INVALID_DATA',
{ field: 'email', reason: 'invalid format' }
);
}
return processData(data);
});Circuit Breaker Pattern
TypeScript:
class CircuitBreaker {
private failures = 0;
private lastFailureTime = 0;
private readonly threshold = 5;
private readonly timeout = 60000; // 1 minute
async execute<T>(fn: () => Promise<T>): Promise<T> {
if (this.isOpen()) {
throw new Error('Circuit breaker is open');
}
try {
const result = await fn();
this.onSuccess();
return result;
} catch (error) {
this.onFailure();
throw error;
}
}
private isOpen(): boolean {
if (this.failures >= this.threshold) {
const elapsed = Date.now() - this.lastFailureTime;
return elapsed < this.timeout;
}
return false;
}
private onSuccess() {
this.failures = 0;
}
private onFailure() {
this.failures++;
this.lastFailureTime = Date.now();
}
}
// Use in handler
const breaker = new CircuitBreaker();
export const handler = withDurableExecution(async (event, context: DurableContext) => {
const result = await context.step('api-call', async () => {
return await breaker.execute(() => callExternalAPI());
});
return result;
});Partial Failure Handling
TypeScript:
export const handler = withDurableExecution(async (event, context: DurableContext) => {
const results = await context.map(
'process-items',
event.items,
async (ctx, item, index) => {
return await ctx.step(async () => processItem(item));
},
{
completionConfig: {
toleratedFailurePercentage: 10 // Allow 10% failures
}
}
);
if (results.hasFailure()) {
// Log failures but continue
context.logger.warn('Some items failed', {
failureCount: results.failureCount,
failures: results.failed.map(f => ({
index: f.index,
error: f.error?.message
}))
});
// Store failed items for later retry
await context.step('store-failures', async () => {
const failedItems = results.failed.map(f => event.items[f.index]);
return await storeFailedItems(failedItems);
});
}
return {
totalProcessed: results.successCount,
failed: results.failureCount
};
});Best Practices
Use appropriate retry strategies - exponential backoff for most cases
Classify errors correctly - distinguish retryable from non-retryable
Implement compensating transactions for distributed workflows
Make errors deterministic - same input produces same error
Use unrecoverable errors to stop execution early when appropriate
Log errors with context using
context.loggerHandle partial failures gracefully in batch operations
Implement circuit breakers for external service calls
Test error scenarios thoroughly with test runners
Monitor error rates and adjust retry strategies accordingly
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