# Agents Deploy

Use when deploying your agent to AWS, or when a deploy has failed.

- Repository: https://github.com/aws/agent-toolkit-for-aws (3366 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aws/agent-toolkit-for-aws --skill agents-deploy -g -a claude-code -y`
Codex: `npx skills add aws/agent-toolkit-for-aws --skill agents-deploy -g -a codex -y`
Cursor: `npx skills add aws/agent-toolkit-for-aws --skill agents-deploy -g -a cursor -y`
Gemini CLI: `npx skills add aws/agent-toolkit-for-aws --skill agents-deploy -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add aws/agent-toolkit-for-aws`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/aws/agent-toolkit-for-aws/blob/HEAD/plugins/aws-agents/skills/agents-deploy/SKILL.md