AWS Emulatorのfidelityスコアと注意点、エージェント用スキルを確認してみた
こんにちは。サービス開発部の武田です。
2026年11月11日に、AWS公式のローカルエミュレータ「AWS Emulator」がリリースされました。AWS CLIやAWS SDKの接続先をローカルのエンドポイントに変えるだけで、AWSアカウントなしにリソースの作成や操作を試せます。
起動の手順と、S3やDynamoDBなどの基本操作は、次の記事にまとまっています。
今回は手元のmacOSで動かして、AWS公式ならではの利点と現時点の注意点を確かめてみました。一緒に公開されたエージェント用のスキルも試しています。
検証環境
- macOS（Apple silicon）、Rancher Desktop（Docker Engine 29.5.3）
- AWS CLI 2.36.30
- Claude Code（
aws-emulatorスキル v1） - AWS Emulator 1.0.322
- 検証日は2026年11月12日
Rancher Desktopでは--userを付けて起動する
ユーザーガイドのdocker runをRancher Desktopでそのまま実行すると、次のエラーで終了しました。
emulator serve failed: server I/O error: Operation not permitted (os error 1)
コンテナ内のユーザー（UID 1000）に、マウントしたディレクトリへの書き込み権限がないためです。ユーザーガイドではLinux向けとされている--userを足すと起動します。
mkdir -p ~/.aws/emulator
PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
--user "$(id -u):$(id -g)" \
-e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
aws-emulator -p $PORT
Docker Desktopでは試していません。
公式が提供することの利点
サードパーティ製のエミュレータと比べると、AWS自身が作っていることがそのまま利点になっています。
fidelityテストとスコアが公開されている
AWSとどこまで同じ動きをするかは、fidelityテストで測られています。AWSは、本物のAWSで検証したテストをaws-emulator-evaluation-suiteで公開しています。まだ通っていないテストも含まれます。リリースごとの結果はscores.json.gzとしてGitHubのリリースに添付されます。1.0.322の結果をサービス別に集計しました。
| サービス | パスした数 / テスト数 |
|---|---|
| Amazon S3 | 763 / 924 |
| Amazon DynamoDB | 661 / 808 |
| Amazon SQS | 286 / 304 |
| AWS IAM | 359 / 463 |
| AWS CloudFormation | 354 / 451 |
| AWS Lambda | 293 / 616 |
集計したのはkindがbehavioralのテストで、テストIDの先頭のサービス名ごとに数えました。スキップされたテストと、複数のサービスにまたがるテストは除いています。使いたいAPIがどこまで再現されているかを、動かす前に調べられますね。
fidelityテストは、不正な呼び出しに対するエラーコードとメッセージまで照合しています。ユーザーガイドが例に挙げている短すぎるテーブル名を試すと、次のValidationExceptionが返りました。本物のAWSでも同じメッセージが返ります。
An error occurred (ValidationException) when calling the CreateTable operation: 1 validation error detected: Value 'ab' at 'tableName' failed to satisfy constraint: Member must have length greater than or equal to 3
未実装のAPIは501で失敗する
未実装のオペレーションは、ステータスコード501のNotImplementedを返します。対応していないAPIを呼んでいることが、テストの失敗ですぐにわかります。
$ aws athena list-work-groups
An error occurred (NotImplemented) when calling the ListWorkGroups operation: operation ListWorkGroups is scaffolded but not implemented in this emulator
本物のAWSと取り違えにくい認証
エミュレータは起動のたびにアクセスキーを生成し、SigV4署名を検証します。アクセスキーIDはEMULATORで始まり、それ以外のキーで署名したリクエストは拒否されます。
An error occurred (AccessDenied) when calling the ListBuckets operation: Sign the request with the emulator credentials
ポートを変えて2つ起動すると、キーと状態は別々になりました。9297のキーで9300を呼ぶと、同じエラーで拒否されます。並列のCIジョブやエージェントごとに1つずつ割り当てられます。
新しいAPIへの追随
各サービスはAWS SDKと同じAPIモデルから生成されているので、AWSにサービスやAPIが追加されるとエミュレータにも現れます。挙動はリリースを重ねて実装されていきます。
AWS News Blogによると、その実装と保守はエージェントが担っています。本物のAWSやAPIモデルとの差分を見つけてissueにするエージェントと、issueを拾って実装・レビューするエージェントに分かれているそうです。リポジトリはPRを受け付けておらず、利用者からの報告はissueで行います。
コーディングエージェント用のスキル
AWS Emulatorと一緒に、コーディングエージェント用のaws-emulatorスキルが公開されています。AWS CLI 2.35.0以降で次のコマンドを実行すると、~/.claude/skills/aws-emulator/にSKILL.mdと8本の参照ドキュメントが置かれます。--agentを省略すると、検出されたエージェントすべてが対象になります。
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1 --agent claude-code
boto3でDynamoDB、S3、SQS、Athenaを呼ぶ小さなサンプルアプリを用意して、ユーザーガイドの例文と同じ依頼をClaude Codeに2つ出しました。
セットアップを任せる
1つ目の依頼は「Install AWS Emulator and point my project at it.」（AWS Emulatorをインストールして、プロジェクトをそこに向けて）です。頼んでみると、イメージのビルドから接続の確認までを4分半ほどで終えました。接続用の環境変数は~/.aws/emulator/9297.envに出力されます。( . ~/.aws/emulator/9297.env && aws s3 ls )のように、サブシェルで読み込んで使います。
Rancher Desktopでは、スキルが指示するdocker runも先ほどのエラーで失敗しました。-d --rm付きのため、コンテナとログは残りません。スキルのトラブルシューティングにこのエラーは載っていません。エージェントは--rmを外して起動し直し、ログから原因を調べて--userを足していました。
互換性チェックを任せる
2つ目の依頼は「Will my app in this repo work on AWS Emulator?」（このリポジトリのアプリケーションはAWS Emulatorで動きますか）です。エージェントはまず、アプリケーションのコードからAWSの呼び出しを洗い出します。次にfidelityテストのソースを読み、それぞれの呼び出しを直接検証しているテストを選びます。最後にリリースのスコアレポートと突き合わせます。エミュレータやAWSは呼び出しません。12分ほどかかりました。
判定はWILL NOT WORKで、内訳は次のとおりです。
| 項目 | 結果 |
|---|---|
| DynamoDB、S3、SQSの呼び出し（12項目） | VERIFIED |
athena:StartQueryExecution |
VERIFIED |
athena:ListWorkGroups |
FAILING |
| リージョンと認証情報を環境から受け取る前提（2項目） | UNVERIFIED |
このあとサンプルアプリをエミュレータに向けて動かしてみました。DynamoDB、S3、SQSを通るテストは成功し、AthenaのレポートはListWorkGroupsの501で失敗しました。動かせた範囲では、項目ごとの結果と合っています。StartQueryExecutionはその前で止まったので確かめていません。
判定は二択で、裏付けのない項目が1つでもあるとWILL NOT WORKになります。どのAPIが引っかかるのかは、項目ごとの結果を見るのがよさそうですね。macOSではGNU grep（ggrep）のインストールが前提です。
現時点の注意点
IAMポリシーの評価はAWSと一致しない
ユーザーガイドは、セキュリティのテストに使わないよう明記しています。エミュレータの中でポリシーを1つも付けていないIAMユーザーを作り、そのアクセスキーで操作してみました。
S3のGetObjectとPutObject、DynamoDBのScanとPutItem、SQSのSendMessage、IAMのListUsersは拒否されました。一方で、S3のCreateBucketとDeleteBucket、DynamoDBのListTables、SNSのCreateTopic、SSMのPutParameterは成功しました。AWSではどれも拒否される操作です。
ユーザーガイドにはS3バケットポリシーは確認しないとあります。1.0.322では、s3:ListBucketをDenyするバケットポリシーを付けると、エミュレータ自身のキーでもAccessDeniedになりました。ポリシーが評価されるかどうかは、オペレーションによって異なります。権限の確認は本物のAWSで行いましょう。
1つのエミュレータは1アカウント・1リージョンで使う
アカウントは000000000000の1つだけで、クロスアカウントの動作は再現されません。リージョンはどの値でも受け付けます。us-east-1で作ったDynamoDBテーブルは、ap-northeast-1を指定すると見えませんでした。ただしリージョンをまたぐ動作はサポート外で、リージョンごとに分かれるかどうかもサービスによります。複数リージョンを試すときは、リージョンごとにエミュレータを起動します。
状態と認証情報は停止すると消える
永続化のオプションはありません。再起動するとバケットやテーブルは消え、アクセスキーと証明書も新しく作り直されます。テストで使うリソースは毎回作ります。ユーザーガイドによると、長時間の稼働や負荷をかける使い方は試されていません。
fidelityスコアはサービスによって差がある
ユーザーガイドによると、現時点でAWSに近いのはリソースを作成・取得・削除するコントロールプレーンのAPIです。データプレーンやIaCツールへの対応はサービスごとに異なります。先ほどと同じ集計で、EC2は1,299件中576件、Athenaは306件中50件でした。複数のサービスにまたがるテストは6,380件中2,667件です。
Bedrockのconverseは呼び出せますが、モデルは動きません。次のような決まったメッセージが返ります。
No language model runs in this emulator. anthropic.claude-3-haiku-20240307-v1:0 generated no text for this request. The request carried 1 message(s) and 1 input token(s).
テレメトリはデフォルトでオン
利用状況とエラーのデータがAWSに送られます。リクエストやレスポンスの中身、認証情報は含まれないとされています。無効にするときはaws-emulatorに-t offを渡すか、環境変数EMULATOR_TELEMETRY=offを設定します。Dockerではdocker runに-e EMULATOR_TELEMETRY=offを足します。
まとめ
AWS Emulatorは、どのAPIがどこまで再現されているかをテストとスコアで確かめられます。デプロイ前にAPI呼び出しの誤りを見つける用途や、コーディングエージェントに試行錯誤させる環境には使えそうです。権限の確認と、データプレーンに依存するテストは、引き続き本物のAWSで行います。
リリースは11月7日から11日の間だけで12回ありました。セキュリティ修正は最新版にしか入らないので、バージョンは固定せず、スコアもリリースごとに見直しましょう。
どなたかの参考になりましたら幸いです。
