agents-deploy

deploy

AgentCore エージェントを AWS にデプロイするか、デプロイが失敗した原因を診断します。

使用する場面

• デプロイする準備ができており、まず設定を検証したい場合
• agentcore deploy がエラーで失敗した場合
• 実際にはデプロイせず、デプロイによって作成される内容をプレビューしたい場合
• 特定のターゲット（ステージング、本番環境）にデプロイしたい場合
• 以前のバージョンにロールバックする、特定のバージョンに固定する、またはカナリアデプロイを設定する必要がある場合

入力

$ARGUMENTS は任意です。

/agents-deploy                     # interactive — pre-flight check or diagnose failure
/agents-deploy preflight           # validate config and IAM before deploying
/agents-deploy diagnose            # diagnose a failed deploy (paste error or read logs)
/agents-deploy preview             # show what deploy will create without deploying
/agents-deploy rollback            # roll back to a previous version

プロセス

ステップ 0：CLI バージョンを確認する

agentcore --version を実行します。このスキルには v0.9.0 以降が必要です。バージョンが古い場合は、先に agentcore update を実行するよう開発者に伝えてください。

ステップ 1：状況を確認する

agentcore/agentcore.json と agentcore/aws-targets.json が存在する場合は、それらを読み込みます。

次のように尋ねる（または状況から推測する）：

「どの状況ですか？

1. これからデプロイするので、まずすべてを確認したい
2. デプロイに失敗した — どのようなエラーが表示されましたか？
3. ロールバックする、または特定のバージョンに固定する必要がある」

開発者がバージョン管理、ロールバック、またはカナリアデプロイを必要としている場合は、references/versioning.md を読み込み、その指示に従います。

---

パス A：デプロイ前の検証

agentcore deploy の前に、次のチェックを実行します。

チェック 1：設定ファイルを検証する

開発者に、次のコマンドを実行するよう案内します。

agentcore validate

これにより、CDK が起動する前に、不正な形式の agentcore.json を検出できます。

チェック 2：リージョンの一致を確認する

デプロイ失敗の最も一般的な原因は、リージョンの不一致です。確認するため、開発者に次のコマンドを案内します。

# Your configured AWS region
aws configure get region

# The region in your deployment target
cat agentcore/aws-targets.json

# The account you're actually authenticated as
aws sts get-caller-identity

aws-targets.json の region は、aws configure のデフォルトリージョンと一致している必要があります。account は、sts get-caller-identity で取得したアカウント ID と一致している必要があります。

チェック 3：Bedrock モデルへのアクセスを確認する

開発者に、リージョンで有効なモデルを確認する次のコマンドを案内します。

aws bedrock list-foundation-models --region $(aws configure get region) \
  --query 'modelSummaries[?modelLifecycle.status==`ACTIVE`].modelId' \
  --output table

クロスリージョン推論プロファイル ID には、推論の実行場所を指定するため、地理的なプレフィックス（us.、eu.、apac.）または global. を使用します。CLI はデフォルトで global. を設定します（例：global.anthropic.claude-sonnet-4-5-20250929-v1:0）。これは、あらゆる商用リージョンにルーティングされます。地理的なプレフィックスを使うと、推論をその地域内に限定できます（例：eu. は EU リージョン内に限定されます）。どのプレフィックスでも、プロファイルの対象となるすべての宛先リージョンでモデルアクセスを有効にする必要があります。各プロファイルプレフィックスに含まれるリージョンについては、Bedrock のドキュメントを確認してください。

チェック 4：デプロイ内容をプレビューする

agentcore deploy --dry-run
agentcore deploy --diff

--dry-run は、作成されるリソースを表示します。--diff は、現在デプロイされている内容との差分を CDK で表示します。

チェック 5：IAM 権限を確認する

開発者に、必要な権限と次の確認コマンドを案内します。

aws iam simulate-principal-policy \
  --policy-source-arn $(aws sts get-caller-identity --query Arn --output text) \
  --action-names iam:CreateRole \
  --resource-arns "arn:aws:iam::*:role/*BedrockAgentCore*"

デプロイを実行する

agentcore deploy -y          # auto-confirm (alias: agentcore dp -y)
agentcore deploy -y -v       # verbose — shows resource-level events
agentcore deploy --target staging -y   # deploy to a specific target

メモリプロビジョニングに関する注意： プロジェクトにメモリが含まれている場合、メモリリソースが ACTIVE になるまで、デプロイに 2～5 分ほど余計にかかります。これは正常であり、エラーではありません。次のコマンドでステータスを確認してください。

agentcore status --type memory

---

パス B：失敗したデプロイを診断する

ステップ B1：エラーを確認する

開発者がエラーを貼り付けている場合は、その内容を直接診断します。貼り付けていない場合は、デプロイログを読み込みます。

# View recent deploy logs
ls -lt agentcore/.cli/logs/
cat agentcore/.cli/logs/deploy-*.log 2>/dev/null | tail -100

ステップ B2：既知の失敗パターンと照合する

IAM 権限エラー：

User: arn:aws:iam::123456789012:user/dev is not authorized to perform: iam:CreateRole

修正方法：必要な IAM 権限を付与します（上記のチェック 5 を参照）。デプロイに使用する ID には、*BedrockAgentCore* ロールに対する IAM 書き込みアクセス権が必要です。

CDK ブートストラップが未実行：

This stack uses assets, so the toolkit stack must be deployed to the environment

修正方法：

npx cdk bootstrap aws://<YOUR_ACCOUNT_ID>/<REGION>

ECR 認証エラー：

no basic auth credentials
Error response from daemon: Head "https://<YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/..."

修正方法：

aws ecr get-login-password --region <REGION> | \
  docker login --username AWS --password-stdin <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com

デプロイ中にモデルへのアクセスが拒否される：

ValidationException: The provided model identifier is invalid

修正方法：Bedrock コンソール → Model access でモデルを有効にします。agentcore.json のモデル ID が、対象リージョンで有効になっているモデルと一致することを確認してください。

リージョンの不一致：

Stack ... is in region us-east-1 but the target is us-west-2

修正方法：agentcore/aws-targets.json を aws configure のデフォルトリージョンに合わせて更新するか、aws configure set region <REGION> を実行します。

メモリが CREATING 状態のままになる：

Memory resource is in CREATING state after 10 minutes

これは通常と異なります。通常のプロビジョニングには 2～5 分かかります。次を確認してください。

agentcore status --type memory --json

停止したままの場合は、メモリリソースを削除して再追加してみてください。

サービスクォータの超過：

LimitExceededException: Account limit for AgentCore runtimes exceeded

修正方法：AWS コンソール → Service Quotas → Amazon Bedrock AgentCore でクォータの引き上げをリクエストします。

ステップ B3：修正後に再実行する

agentcore deploy -y

同じエラーが再発する場合は、agentcore status を実行して、すべてのリソースの現在の状態を確認してください。

agentcore status
agentcore status --state pending-removal  # resources marked for deletion

---

複数のターゲットへのデプロイ

agentcore/aws-targets.json でターゲットを定義します。

[
  {
    "name": "staging",
    "description": "Staging environment",
    "account": "123456789012",
    "region": "us-east-1"
  },
  {
    "name": "production",
    "description": "Production environment",
    "account": "987654321098",
    "region": "us-west-2"
  }
]

特定のターゲットにデプロイします。

agentcore deploy --target staging -y
agentcore deploy --target production -y

出力

• プリフライトチェックの結果と、検出された問題に対する具体的な修正方法
• デプロイ失敗の診断と具体的な修正方法
• 修正を適用した後に実行するデプロイコマンド