agents-deploy

Files (2)

• SKILL.md
• versioning.md · references/

SKILL.md (first lines)

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

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws