/agents-deploy

name: agents-deploy
description: >
  Use when deploying your agent to AWS, or when a deploy has failed.
  Handles pre-flight validation, CDK/IAM/quota error diagnosis, version
  management, rollback, and canary deployments. Triggers on: "deploy my
  agent", "agentcore deploy", "deploy failed", "CDK error", "rollback",
  "canary deploy", "pin version", "redeploy", "deploy stuck".
  Not for production hardening — use agents-harden. Not for adding
  capabilities before deploy — use agents-build or agents-connect.
  Not for VPC configuration errors — use agents-build.
allowed-tools: Read Grep Glob Bash
metadata:
  type: skill
  version: "1.0.0"
  author: aws-agentcore
  requires-cli: ">=0.9.0"

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`](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.