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

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

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

Run the deploy

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:

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:

Step B2: Match to known failure patterns

IAM permission error:

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:

Fix:

ECR authorization error:

Fix:

Model access denied during deploy:

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:

Fix: Update agentcore/aws-targets.json to match your aws configure default region, or run aws configure set region <REGION>.

Memory stuck in CREATING:

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

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

Service quota exceeded:

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

Step B3: After fixing, re-run

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

Deploying to multiple targets

Define targets in agentcore/aws-targets.json:

Deploy to a specific target:

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