aws-lambda-durable-functions

AWS Lambda 耐久関数

中断が発生しても確実に進捗を維持しながら、最大1年間実行できる、回復性に優れた複数ステップのアプリケーションとAIワークフローを構築します。

オンボーディング

ステップ1：前提条件を確認する

AWS Lambda 耐久関数を使用する前に、次の項目を確認してください。

1. AWS CLI がインストールされ（2.33.22以降）、設定されていること：

   aws --version
   aws sts get-caller-identity
   

2. ランタイム環境の準備ができていること：

   • TypeScript/JavaScriptの場合：Node.js 22以降（node --version）
   • Pythonの場合：Python 3.11以降（python --version。現在、Durable Execution SDKがプリインストールされているのは、Lambdaランタイム環境の3.13以降のみです。Durable SDK自体がサポートするPythonの最小バージョンは3.11ですが、OCIを使用して、独自のPythonランタイムとDurable SDKを含むコンテナイメージを持ち込むことができます。）

3. デプロイ機能があること（次のいずれか）：

   • AWS SAM CLI（sam --version）1.153.1以降
   • AWS CDK（cdk --version）v2.237.1以降
   • Lambdaへの直接デプロイアクセス

ステップ2：言語とIaCフレームワークを選択する

言語の選択

デフォルト：TypeScript

指定方法：

• 「use Python」→ Pythonコードを生成
• 「use JavaScript」→ JavaScriptコードを生成

指定がない場合は、必ずTypeScriptを使用します。

IaCフレームワークの選択

デフォルト：CDK

指定方法：

• 「use CloudFormation」→ YAMLテンプレートを生成
• 「use SAM」→ YAMLテンプレートを生成

指定がない場合は、必ずCDKを使用します。

エラーシナリオ

サポート対象外の言語

• 検出された言語を列挙します
• 「Durable Execution SDKはまだ[framework]では利用できません」と伝えます
• 代替として、サポート対象の言語を提案します

サポート対象外のIaCフレームワーク

• 検出されたフレームワークを列挙します
• 「[framework]は、まだLambda耐久関数をサポートしていない可能性があります」と伝えます
• 代替として、サポート対象のフレームワークを提案します

Serverless MCP サーバーを利用できない場合

• ユーザーに「AWS Serverless MCPが応答していません」と伝えます
• 「MCPのサポートなしで続行しますか？」と尋ねます
• ユーザーの確認なしに続行してはいけません

ステップ3：SDKをインストールする

TypeScript/JavaScriptの場合：

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

Pythonの場合：

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

リファレンスファイルを読み込むタイミング

ユーザーが取り組んでいる内容に応じて、適切なリファレンスファイルを読み込んでください。

• 開始方法、基本設定、例、ESLint、または Jest のセットアップ -> getting-started.md を参照してください
• リプレイモデルの理解、決定性、または 非決定的なエラー -> replay-model-rules.md を参照してください
• ステップの作成、アトミック操作、または 再試行ロジック -> step-operations.md を参照してください
• 待機、遅延、コールバック、外部システム、または ポーリング -> wait-operations.md を参照してください
• 並列実行、map 操作、バッチ処理、または 並行性 -> concurrent-operations.md を参照してください
• エラー処理、再試行戦略、Saga パターン、または 補償トランザクション -> error-handling.md を参照してください
• 高度なエラー処理、タイムアウト処理、サーキットブレーカー、または 条件付き再試行 -> advanced-error-handling.md を参照してください
• テスト、ローカルテスト、クラウドテスト、テストランナー、または 不安定なテスト -> testing-patterns.md を参照してください
• デプロイ、CloudFormation、CDK、SAM、ロググループ、デプロイ、または インフラストラクチャ -> deployment-iac.md を参照してください
• 高度なパターン、GenAI エージェント、完了ポリシー、ステップのセマンティクス、または カスタムシリアライズ -> advanced-patterns.md を参照してください
• トラブルシューティング、実行が停止している、実行が失敗した、実行 ID のデバッグ、実行履歴、実行エラー、実行が失敗した理由、実行がタイムアウトした、コールバックを受信できない、実行の診断、または 実行の根本原因 -> troubleshooting-executions.md を参照してください

クイックリファレンス

基本的なハンドラーパターン

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

重要なルール

1. 非決定的なコードはすべてステップ内に記述する必要があります（Date.now、Math.random、API 呼び出し）
2. 耐久性のある操作をネストすることはできません - 操作をまとめるには runInChildContext を使用してください
3. クロージャの変更はリプレイ時に失われます - ステップから戻り値を返してください
4. ステップ外の副作用は繰り返し実行されます - context.logger を使用してください（リプレイに対応）

Python API の相違点

Python SDK は、いくつかの重要な点で TypeScript と異なります。

• ステップ: @durable_step デコレーターと context.step(my_step(args)) を使用するか、インラインで context.step(lambda _: ..., name='...') を使用します。ステップ名を自動的に付けるには、デコレーターを推奨します。
• 待機: context.wait(duration=Duration.from_seconds(n), name='...')
• 例外: ExecutionError（永続的）、InvocationError（一時的）、CallbackError（コールバックの失敗）
• テスト: DurableFunctionTestRunner クラスを直接使用します。ハンドラーを指定してインスタンスを作成し、コンテキストマネージャーを使用して、run(input=...) を呼び出します。

呼び出し要件

耐久性のある関数には修飾済み ARN（バージョン、エイリアス、または $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 権限

Lambda 実行ロールには、管理ポリシー AWSLambdaBasicDurableExecutionRolePolicy を必ずアタッチしてください。これには以下が含まれます。

• lambda:CheckpointDurableExecution - 実行状態を永続化します
• lambda:GetDurableExecutionState - 実行状態を取得します
• CloudWatch Logs の権限

以下には追加の権限が必要です。

• 耐久性のある呼び出し: 対象関数 ARN に対する lambda:InvokeFunction
• 外部コールバック: システムには lambda:SendDurableExecutionCallbackSuccess と lambda:SendDurableExecutionCallbackFailure が必要です

検証ガイドライン

永続関数のコードを作成またはレビューする際は、再生モデルに関する次の違反がないか必ず確認してください。

1. ステップ外の非決定的なコード：Date.now()、Math.random()、UUID の生成、API 呼び出し、データベースクエリはすべてステップ内で実行する必要があります
2. ステップ関数内のネストされた永続操作：ステップ関数内では context.step()、context.wait()、context.invoke() を呼び出せません。代わりに context.runInChildContext() を使用してください
3. 永続化されないクロージャの変更：ステップ内で変更された変数は再生後に保持されません。代わりに、ステップから戻り値を返してください
4. 再生時に繰り返されるステップ外の副作用：ログ記録には context.logger を使用してください（再生に対応しており、自動的に重複を排除します）

永続関数のテストを実装または変更する際は、次の点を必ず確認してください。

1. すべての操作に説明的な名前が付いている
2. テストではインデックスではなく、名前で操作を取得している
3. 複数回の呼び出しで再生時の動作をテストしている
4. ローカルテストには LocalDurableTestRunner を使用している

MCP サーバーの設定

書き込みアクセスはデフォルトで有効です。 プラグインには .mcp.json に --allow-write が含まれているため、MCP サーバーはユーザーに代わってプロジェクトを作成し、IaC を生成してデプロイできます。

Lambda や API Gateway のログなど、機密データへのアクセスはデフォルトで有効になっていません。許可するには、.mcp.json に --allow-sensitive-data-access を追加してください。

リソース

• AWS Lambda の永続関数のドキュメント
• JavaScript SDK のリポジトリ
• Python SDK のリポジトリ
• IAM ポリシーのリファレンス