deploy

Deploy your AgentCore agent to AWS, or diagnose why a deploy failed.

When to use

You're ready to deploy and want to validate config first
```
agentcore deploy
```
failed with an error
You want to preview what deploy will create without actually deploying
You want to deploy to a specific target (staging, production)
You need to roll back to a previous version, pin to a specific version, or set up canary deployments

Input

$ARGUMENTS

is optional:

/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

Process

Step 0: Verify CLI version

Run

agentcore --version

. This skill requires v0.9.0 or later. If the version is older, tell the developer to run

agentcore update

before proceeding.

Step 1: Determine the situation

Read

agentcore/agentcore.json

and

agentcore/aws-targets.json

if they exist.

Ask (or infer from context):

"Are you:

About to deploy and want to check everything first

Dealing with a failed deploy — what error did you see?

Needing to roll back or pin a specific version?"

If the developer needs versioning, rollback, or canary deployment, load

references/versioning.md

and follow its instructions.

Path A: Pre-flight validation

Run these checks before

agentcore deploy

Check 1: Validate config files

Show the developer this command to run:

bash

agentcore validate

This catches malformed

agentcore.json

before CDK even starts.

Check 2: Verify region alignment

The most common deploy failure is a region mismatch. Show the developer these commands to verify:

bash

# 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

The

region

aws-targets.json

must match your

aws configure

default region. The

account

must match the account ID from

sts get-caller-identity

Check 3: Verify Bedrock model access

Show the developer this command to check enabled models in their region:

bash

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

Cross-region inference profile IDs use a geographic prefix (

us.

eu.

apac.

) or

global.

to control where inference runs. The CLI scaffolds

global.

by default (e.g.,

global.anthropic.claude-sonnet-4-5-20250929-v1:0

), which routes to any commercial region. Geographic prefixes keep inference within that geography (e.g.,

eu.

stays in EU regions). All prefixes require model access enabled in every destination region the profile covers. Check the Bedrock docs for which regions are included in each profile prefix.

Check 4: Preview what will be deployed

bash

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

--dry-run

shows what resources will be created.

--diff

shows the CDK diff against what's currently deployed.

Check 5: Verify IAM permissions

Show the developer the permissions needed and this verification command:

bash

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*"

Run the deploy

bash

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

Memory provisioning note: If your project includes memory, deploy takes 2–5 minutes longer while the memory resource becomes ACTIVE. This is normal — not an error. Check status:

bash

agentcore status --type memory

Path B: Diagnose a failed deploy

Step B1: Read the error

If the developer pasted an error, diagnose it directly. If not, read the deploy logs:

bash

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

Step B2: Match to known failure patterns

IAM permission error:

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

Fix: Attach the required IAM permissions (see Check 5 above). The deploying identity needs IAM write access scoped to

*BedrockAgentCore*

roles.

CDK bootstrap not run:

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

Fix:

bash

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

ECR authorization error:

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

Fix:

bash

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

Model access denied during deploy:

ValidationException: The provided model identifier is invalid

Fix: Enable the model in the Bedrock console → Model access. Ensure the model ID in

agentcore.json

matches an enabled model in your target region.

Region mismatch:

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

Fix: Update

agentcore/aws-targets.json

to match your

aws configure

default region, or run

aws configure set region <REGION>

Memory stuck in CREATING:

Memory resource is in CREATING state after 10 minutes

This is unusual — normal provisioning takes 2–5 minutes. Check:

bash

agentcore status --type memory --json

If stuck, try removing and re-adding the memory resource.

Service quota exceeded:

LimitExceededException: Account limit for AgentCore runtimes exceeded

Fix: Request a quota increase in the AWS console → Service Quotas → Amazon Bedrock AgentCore.

Step B3: After fixing, re-run

bash

agentcore deploy -y

If the same error recurs, check

agentcore status

to see the current state of all resources:

bash

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

Deploying to multiple targets

Define targets in

agentcore/aws-targets.json

json

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

Deploy to a specific target:

bash

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

Output

Pre-flight check results with specific fixes for any issues found
Diagnosis of deploy failure with the specific fix
Deploy command to run after fixes are applied

agents-deploy

NPX Install

Tags

SKILL.md Content

deploy

When to use

Input

Process

Step 0: Verify CLI version

Step 1: Determine the situation

Path A: Pre-flight validation

Check 1: Validate config files

Check 2: Verify region alignment

Check 3: Verify Bedrock model access

Check 4: Preview what will be deployed

Check 5: Verify IAM permissions

Run the deploy

Path B: Diagnose a failed deploy

Step B1: Read the error

Step B2: Match to known failure patterns

Step B3: After fixing, re-run

Deploying to multiple targets

Output