Agents DeploySAFE

Official, AWS-supported MCP servers, skills, and plugins to help AI agents build on AWS

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

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

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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Agents Deploy](https://modelsatlas.com/skills/aws/agents-deploy/badge.svg)](https://modelsatlas.com/skills/aws/agents-deploy/)

Not your listing, or something out of date? Claim or update your listing.