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

Agent Versioning and Rollback

Every agentcore deploy creates a new version of your agent runtime. This reference covers how versions work, how to pin to a specific version, and how to roll back when a deploy goes wrong.

How versioning works

• Each agentcore deploy produces a new runtime version
• The alias (usually DEFAULT) points to the currently-live version
• Old versions remain accessible by ARN for rollback
• Local dev (agentcore dev) always runs the current code — no version concept

Inspecting versions

The AgentCore CLI currently manages the project config (agentcore.json → agentcore deploy) but doesn't expose version/alias operations directly. For those, use the AWS CLI against the bedrock-agentcore-control data plane.

# List all versions of your agent
aws bedrock-agentcore-control list-agent-runtime-versions \
  --agent-runtime-id <AGENT_RUNTIME_ID>

# Get details on a specific version
aws bedrock-agentcore-control get-agent-runtime \
  --agent-runtime-id <AGENT_RUNTIME_ID> \
  --qualifier <VERSION>

The <AGENT_RUNTIME_ID> comes from agentcore status --json | jq '.runtimes[0].agentRuntimeId'.

Invoking a specific version

By default, callers hit the alias (current version). To pin a call to a specific version, pass qualifier in the invoke request:

response = client.invoke_agent_runtime(
    agentRuntimeArn="<AGENT_RUNTIME_ARN>",
    qualifier="3",  # invoke version 3 specifically
    payload=payload,
    runtimeSessionId=session_id,
)

This is useful for:

• Canary testing — send a small percentage of traffic to a new version before cutting over
• A/B comparison — run two versions in parallel and compare outputs
• Debugging — reproduce an issue against a specific version

Rolling back

If a deploy breaks something, roll back by redeploying the previous known-good code:

# Option 1: git checkout the previous commit and redeploy
git checkout <PREVIOUS_COMMIT>
agentcore deploy -y

# Option 2: point the alias at an older version (no code rollback needed)
aws bedrock-agentcore-control update-agent-runtime-alias \
  --agent-runtime-id <AGENT_RUNTIME_ID> \
  --alias-name DEFAULT \
  --routing-configuration agentRuntimeVersion=<OLDER_VERSION>

Option 2 is faster — no rebuild or redeploy, just a pointer swap. Option 1 is cleaner because your code matches what's running.

Canary deployment

Split traffic between two versions to validate a new deploy before full rollout:

aws bedrock-agentcore-control update-agent-runtime-alias \
  --agent-runtime-id <AGENT_RUNTIME_ID> \
  --alias-name DEFAULT \
  --routing-configuration \
    agentRuntimeVersion=<NEW_VERSION>,weight=10 \
    agentRuntimeVersion=<OLD_VERSION>,weight=90

This routes 10% of traffic to the new version. Monitor agents-optimize eval scores and error rates before increasing the weight.

Version cleanup

AgentCore retains versions indefinitely — they don't auto-delete. If you've deployed hundreds of times, consider periodically deleting old versions:

aws bedrock-agentcore-control delete-agent-runtime-version \
  --agent-runtime-id <AGENT_RUNTIME_ID> \
  --version <OLD_VERSION>

Never delete the current live version.

Staging targets

For teams that want separate dev/staging/prod environments, use deployment targets:

// agentcore/aws-targets.json
[
  {"name": "default", "account": "<DEV_ACCOUNT>", "region": "us-east-1"},
  {"name": "staging", "account": "<STAGING_ACCOUNT>", "region": "us-east-1"},
  {"name": "production", "account": "<PROD_ACCOUNT>", "region": "us-west-2"}
]

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

Each target gets its own runtime — versions are separate per target.

Cross-references

• If a rollback is needed because of a specific failure, use agents-debug to diagnose first
• For staging/production best practices, see agents-harden
• For running evals against a specific version before cutover, see `agents-optimize/references/evals.md`