{"id":"c304930c-7811-4e5b-ae57-50e40a3d2336","slug":"aws-lambda-durable-functions","kind":"skill","name":"aws-lambda-durable-functions","summary":"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 critic","owner":"awslabs","repoUrl":"https://github.com/awslabs/agent-plugins/tree/HEAD/plugins/aws-serverless/skills/aws-lambda-durable-functions","license":"Apache-2.0","licenseTier":"permissive","trust":"official","stars":918,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T06:03:42.301Z","logoUrl":"https://avatars.githubusercontent.com/u/3299148?v=4","linkOnly":false,"collection":{"name":"agent-plugins","repo":"awslabs/agent-plugins"},"skillPath":"plugins/aws-serverless/skills/aws-lambda-durable-functions","categories":["cloud-infra","developer-tools"],"tags":["agents","coding-agent-skills","coding-agents","agent-plugins","aws"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T06:03:42.299Z","sample":false,"url":"https://conduits.dev/tools/aws-lambda-durable-functions","language":"Python","transports":[],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"> 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.\n\n# AWS Lambda durable functions\n\nBuild resilient multi-step applications and AI workflows that can execute for up to 1 year while maintaining reliable progress despite interruptions.\n\n## Onboarding\n\n### Step 1: Validate Prerequisites\n\nBefore using AWS Lambda durable functions, verify:\n\n1. **AWS CLI** is installed (2.33.22 or higher) and configured:\n\n   ```bash\n   aws --version\n   aws sts get-caller-identity\n   ```\n\n2. **Runtime environment** is ready:\n   - For TypeScript/JavaScript: Node.js 22+ (`node --version`)\n   - 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.)\n\n3. **Deployment capability** exists (one of):\n   - AWS SAM CLI (`sam --version`) 1.153.1 or higher\n   - AWS CDK (`cdk --version`) v2.237.1 or higher\n   - Direct Lambda deployment access\n\n### Step 2: Select language and IaC framework\n\n### Language Selection\n\nDefault: TypeScript\n\nOverride syntax:\n\n- \"use Python\" → Generate Python code\n- \"use JavaScript\" → Generate JavaScript code\n\nWhen not specified, ALWAYS use TypeScript\n\n### IaC framework selection\n\nDefault: CDK\n\nOverride syntax:\n\n- \"use CloudFormation\" → Generate YAML templates\n- \"use SAM\" → Generate YAML templates\n\nWhen not specified, ALWAYS use CDK\n\n### Error Scenarios\n\n#### Unsupported Language\n\n- List detected language\n- State: \"Durable Execution SDK is not yet available for [framework]\"\n- Suggest supported languages as alternatives\n\n#### Unsupported IaC Framework\n\n- List detected framework\n- State: \"[framework] might not support Lambda durable functions yet\"\n- Suggest supported frameworks as alternatives\n\n### Serverless MCP Server Unavailable\n\n- Inform user: \"AWS Serverless MCP not responding\"\n- Ask: \"Proceed without MCP support?\"\n- DO NOT continue without user confirmation\n\n### Step 3: Install SDK\n\n**For TypeScript/JavaScript:**\n\n```bash\nnpm install @aws/durable-execution-sdk-js\nnpm install --save-dev @aws/durable-execution-sdk-js-testing\n```\n\n**For Python:**\n\n```bash\npip install aws-durable-execution-sdk-python\npip install aws-durable-execution-sdk-python-testing\n```\n\n## When to Load Reference Files\n\nLoad the appropriate reference file based on what the user is working on:\n\n- **Getting started**, **basic setup**, **example**, **ESLint**, or **Jest setup** -> see [getting-started.md](references/getting-started.md)\n- **Understanding replay model**, **determinism**, or **non-deterministic errors** -> see [replay-model-rules.md](references/replay-model-rules.md)\n- **Creating steps**, **atomic operations**, or **retry logic** -> see [step-operations.md](references/step-operations.md)\n- **Waiting**, **delays**, **callbacks**, **external systems**, or **polling** -> see [wait-operations.md](references/wait-operations.md)\n- **Parallel execution**, **map operations**, **batch processing**, or **concurrency** -> see [concurrent-operations.md](references/concurrent-operations.md)\n- **Error handling**, **retry strategies**, **saga pattern**, or **compensating transactions** -> see [error-handling.md](references/error-handling.md)\n- **Advanced error handling**, **timeout handling**, **circuit breakers**, or **conditional retries** -> see [advanced-error-handling.md](references/advanced-error-handling.md)\n- **Testing**, **local testing**, **cloud testing**, **test runner**, or **flaky tests** -> see [testing-patterns.md](references/testing-patterns.md)\n- **Deployment**, **CloudFormation**, **CDK**, **SAM**, **log groups**, **deploy**, or **infrastructure** -> see [deployment-iac.md](references/deployment-iac.md)\n- **Advanced patterns**, **GenAI agents**, **completion policies**, **step semantics**, or **custom serialization** -> see [advanced-patterns.md](references/advanced-patterns.md)\n- **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](references/troubleshooting-executions.md)\n\n## Quick Reference\n\n### Basic Handler Pattern\n\n**TypeScript:**\n\n```typescript\nimport { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';\n\nexport const handler = withDurableExecution(async (event, context: DurableContext) => {\n  const result = await context.step('process', async () => processData(event));\n  return result;\n});\n```\n\n**Python:**\n\n```python\nfrom aws_durable_execution_sdk_python import durable_execution, DurableContext\n\n@durable_execution\ndef handler(event: dict, context: DurableContext) -> dict:\n    result = context.step(lambda _: process_data(event), name='process')\n    return result\n```\n\n### Critical Rules\n\n1. **All non-deterministic code MUST be in steps** (Date.now, Math.random, API calls)\n2. **Cannot nest durable operations** - use `runInChildContext` to group operations\n3. **Closure mutations are lost on replay** - return values from steps\n4. **Side effects outside steps repeat** - use `context.logger` (replay-aware)\n\n### Python API Differences\n\nThe Python SDK differs from TypeScript in several key areas:\n\n- **Steps**: Use `@durable_step` decorator + `context.step(my_step(args))`, or inline `context.step(lambda _: ..., name='...')`. Prefer the decorator for automatic step naming.\n- **Wait**: `context.wait(duration=Duration.from_seconds(n), name='...')`\n- **Exceptions**: `ExecutionError` (permanent), `InvocationError` (transient), `CallbackError` (callback failures)\n- **Testing**: Use `DurableFunctionTestRunner` class directly - instantiate with handler, use context manager, call `run(input=...)`\n\n### Invocation Requirements\n\nDurable functions **require qualified ARNs** (version, alias, or `$LATEST`):\n\n```bash\n# Valid\naws lambda invoke --function-name my-function:1 output.json\naws lambda invoke --function-name my-function:prod output.json\n\n# Invalid - will fail\naws lambda invoke --function-name my-function output.json\n```\n\n## IAM Permissions\n\nYour Lambda execution role MUST have the `AWSLambdaBasicDurableExecutionRolePolicy` managed policy attached. This includes:\n\n- `lambda:CheckpointDurableExecution` - Persist execution state\n- `lambda:GetDurableExecutionState` - Retrieve execution state\n- CloudWatch Logs permissions\n\n**Additional permissions needed for:**\n\n- **Durable invokes**: `lambda:InvokeFunction` on target function ARNs\n- **External callbacks**: Systems need `lambda:SendDurableExecutionCallbackSuccess` and `lambda:SendDurableExecutionCallbackFailure`\n\n## Validation Guidelines\n\nWhen writing or reviewing durable function code, ALWAYS check for these replay model violations:\n\n1. **Non-deterministic code outside steps**: `Date.now()`, `Math.random()`, UUID generation, API calls, database queries must all be inside steps\n2. **Nested durable operations in step functions**: Cannot call `context.step()`, `context.wait()`, or `context.invoke()` inside a step function — use `context.runInChildContext()` instead\n3. **Closure mutations that won't persist**: Variables mutated inside steps are NOT preserved across replays — return values from steps instead\n4. **Side effects outside steps that repeat on replay**: Use `context.logger` for logging (it is replay-aware and deduplicates automatically)\n\nWhen implementing or modifying tests for durable functions, ALWAYS verify:\n\n1. All operations have descriptive names\n2. Tests get operations by NAME, never by index\n3. Replay behavior is tested with multiple invocations\n4. Use `LocalDurableTestRunner` for local testing\n\n### MCP Server Configuration\n\n**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.\n\nAccess 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`.\n\n## Resources\n\n- [AWS Lambda durable functions Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)\n- [JavaScript SDK Repository](https://github.com/aws/aws-durable-execution-sdk-js)\n- [Python SDK Repository](https://github.com/aws/aws-durable-execution-sdk-python)\n- [IAM Policy Reference](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLambdaBasicDurableExecutionRolePolicy.html)"}