agents-deploy

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: 1. About to deploy and want to check everything first 2. Dealing with a failed deploy — what error did you see? 3. 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:

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:

# 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 in 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:

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

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:

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

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:

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:

# 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:

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:

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:

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

agentcore deploy -y

If the same error recurs, check agentcore status to see the current state of all resources:

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

Deploying to multiple targets

Define targets in 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"
  }
]

Deploy to a specific target:

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