Index of every page on this site: llms.txt
All skills
aws avatar

/aws-lambda-durable-functions

@12d7f78
Run it yourself

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, durable-execution-sdk, qualified ARN invocation, and durable handler replay.

Use this Skill: https://skilld.dev/gh/aws/agent-toolkit-for-aws/aws-lambda-durable-functions

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈200 tokens for metadata: the name and description. ≈2k when used: this file.

Description uses 10.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈800 characters, or 10.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

AWS Lambda durable functions

Durable functions are Lambda functions that checkpoint progress and can run multi-step workflows for up to one year, suspending without compute charges during waits and callbacks.

Use the developer guides for APIs

Do not write SDK method signatures, configuration objects, or IaC properties from memory. Read the relevant page first. The SDK guide covers TypeScript, Python, Java, Go, Rust, and C#, and the API names differ between languages.

AWS Durable Execution SDK Developer Guide:

Topic Link
Key concepts and quickstart https://docs.aws.amazon.com/durable-execution/getting-started/key-concepts/
Steps (retries, step semantics) https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/step/
Waits https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/wait/
Wait for condition (polling) https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/wait-for-condition/
Callbacks and wait for callback https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/callback/
Invoke (function chaining) https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/invoke/
Parallel https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/parallel/
Map (concurrency, completion policies) https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/map/
Child contexts https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/child-context/
Errors https://docs.aws.amazon.com/durable-execution/sdk-reference/error-handling/errors/
Retries https://docs.aws.amazon.com/durable-execution/sdk-reference/error-handling/retries/
Serialization https://docs.aws.amazon.com/durable-execution/sdk-reference/state/serialization/
Logging https://docs.aws.amazon.com/durable-execution/sdk-reference/observability/logging/
Python language guide https://docs.aws.amazon.com/durable-execution/sdk-reference/languages/python/
TypeScript language guide https://docs.aws.amazon.com/durable-execution/sdk-reference/languages/typescript/
Testing (local and cloud runners) https://docs.aws.amazon.com/durable-execution/testing/
Writing tests https://docs.aws.amazon.com/durable-execution/testing/authoring/
Test assertions https://docs.aws.amazon.com/durable-execution/testing/assertions/
Best practices (determinism, idempotency, state) https://docs.aws.amazon.com/durable-execution/patterns/best-practices/

Lambda durable functions guide, for the Lambda service side:

Topic Link
Deploying with CloudFormation, AWS CDK, AWS SAM, Terraform https://docs.aws.amazon.com/lambda/latest/dg/durable-getting-started-iac.html
Invoking (sync, async, execution names) https://docs.aws.amazon.com/lambda/latest/dg/durable-invoking.html
Security and permissions https://docs.aws.amazon.com/lambda/latest/dg/durable-security.html
Monitoring and execution history https://docs.aws.amazon.com/lambda/latest/dg/durable-monitoring.html
Best practices https://docs.aws.amazon.com/lambda/latest/dg/durable-best-practices.html
Supported runtimes https://docs.aws.amazon.com/lambda/latest/dg/durable-supported-runtimes.html

Works best with the AWS MCP Server for reading these pages, but it is not required.

Critical rules: Lambda

  1. Durable execution is enabled only when a function is created. It cannot be added to an existing function. Create a new function with durable execution (DurableConfig in IaC) and move the logic into it.
  2. The handler must be wrapped with the SDK (withDurableExecution in TypeScript, @durable_execution in Python). A plain handler deployed to a durable function fails every execution, so when moving existing code, wrap it rather than copying it unchanged.
  3. Invoke with a qualified ARN: a version, an alias, or $LATEST (for example my-function:live). An unqualified function name fails.
  4. The execution role needs lambda:CheckpointDurableExecution, lambda:GetDurableExecutionState, and CloudWatch Logs permissions. The managed policy AWSLambdaBasicDurableExecutionRolePolicy grants these on all resources and is fine for getting started; for production, use a policy scoped to the function's ARN. Durable invokes also need lambda:InvokeFunction on the target. External systems that complete callbacks need lambda:SendDurableExecutionCallbackSuccess and lambda:SendDurableExecutionCallbackFailure, plus lambda:SendDurableExecutionCallbackHeartbeat if they send heartbeats.
  5. To invoke a durable function synchronously, through an event source mapping, or through a function URL, set the durable execution timeout (DurableConfig ExecutionTimeout, separate from the function Timeout) to 1,800 seconds (30 minutes) or less.

Critical rules: the replay model

Durable functions use checkpoint and replay. After a wait, failure, or resume, the handler re-runs from the beginning. Completed operations return their checkpointed results without re-executing, and code outside operations runs again on every replay.

  1. Code outside steps must be deterministic. Put timestamps, random values, UUIDs, API calls, and database queries in a step.
  2. Never call durable operations inside a step. Use a child context to group operations.
  3. Closure mutations inside steps are lost on replay. Return values from steps instead.
  4. Side effects outside steps repeat on every replay. Put them in steps. The context logger is replay-aware and safe anywhere.
  5. Don't sleep in the handler. Use a durable wait or callback, which suspends the execution without compute charges.
  6. For human approval or an external job that can report back, use wait for callback (waitForCallback / wait_for_callback). Use wait for condition only when the external system can only be polled.
  7. For sagas, run compensations as named steps, in reverse order, from the catch block around the forward steps.
  8. Steps default to at-least-once (AtLeastOncePerRetry), so a crash before the checkpoint re-runs the step. For non-idempotent calls, say so and use AtMostOncePerRetry with retries disabled or an idempotency key.
  9. Express map and parallel failure tolerance in the form the user gives it. A percentage becomes a tolerated failure percentage in the completion config, not a computed count.

When the user asks for code, a test, or a template, show it inline in your answer, even if you also write it to a file. When writing or reviewing durable function code, check it against these rules. When writing tests, name every operation and look operations up by name, not by index.

Troubleshooting executions

Diagnosis is read-only. Read the execution and its history (aws lambda get-durable-execution, aws lambda get-durable-execution-history) and report what you find. Never stop an execution or change its state unless the user explicitly asks.

Security

  • Step results and callback payloads are checkpointed. Do not return secrets, credentials, or PII from steps. Store them in Secrets Manager or SSM Parameter Store, retrieve them inside steps, and return references.
  • Validate event payloads at the handler entry point, and validate callback payloads, which come from external systems.
  • Encrypt the function's CloudWatch Logs log group with KMS, and avoid DEBUG logging outside development because it can expose step results.

When the guides and the SDK disagree

Trust the installed SDK source and tell the user about the discrepancy.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warningtoday3 checks · Risk SAFE
  • Gen Agent Trust Hub1d

    This skill provides development guidelines and architectural rules for building AWS Lambda durable functions. It emphasizes security best practices and relies on official documentation from trusted sources. No security issues were detected.

  • Sockettoday

    No alerts

  • Snyk1d

    Risk: MEDIUM · 1 issue

Signed by skilld at 12d7f78. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
version
3

README badge

README badge for aws/agent-toolkit-for-aws/aws-lambda-durable-functions