Agents Deploy

What it does

When your agent uses it

• Deploying your agent to AWS
• A deploy has failed
• : deploy my agent
• Agentcore deploy

Example prompts

• “deploy my agent”
• “agentcore deploy”
• “deploy failed”
• “/agents-deploy”

Requirements

• Node.js
• Docker
• Pre-approved tools (allowed-tools): Read, Grep, Glob, Bash

Workflow steps

2 steps, taken from the step headings in SKILL.md.

1. 1Verify CLI version
2. 2Determine the situation

What it can do on your machine

Read from SKILL.md and the folder at commit bd49cc8. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Grep
  • Glob
  • Bash

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • aws
  • npx
  • docker

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use aws, npx and docker, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Agents Deploy loads about 2k tokens when it runs, and up to ~3k if it reads all its reference files. Until then it costs about 133 tokens; SKILL.md has 613 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~133

When it runs · the whole SKILL.md, loaded when a task matches

~2k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NotePre-approves every shell command (allowed-tools: Bash)SKILL.md

  allowed-tools: Read, Grep, Glob, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from aws/agent-toolkit-for-aws at commit bd49cc8, republished under its Apache-2.0 licence (© aws). 613 words, ~1,976 tokens.

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

metadata.version

1.0.0

metadata.author

aws-agentcore

metadata.requires-cli

>=0.9.0

/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

agentcore validate

# 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

aws bedrock list-foundation-models --region $(aws configure get region) \
  --query 'modelSummaries[?modelLifecycle.status==`ACTIVE`].modelId' \
  --output table

agentcore deploy --dry-run
agentcore deploy --diff

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*"

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

agentcore status --type memory

# View recent deploy logs
ls -lt agentcore/.cli/logs/
cat agentcore/.cli/logs/deploy-*.log 2>/dev/null | tail -100

User: arn:aws:iam::123456789012:user/dev is not authorized to perform: iam:CreateRole

This stack uses assets, so the toolkit stack must be deployed to the environment

npx cdk bootstrap aws://<YOUR_ACCOUNT_ID>/<REGION>

no basic auth credentials
Error response from daemon: Head "https://<YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/..."

aws ecr get-login-password --region <REGION> | \
  docker login --username AWS --password-stdin <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com

ValidationException: The provided model identifier is invalid

Stack ... is in region us-east-1 but the target is us-west-2

Memory resource is in CREATING state after 10 minutes

agentcore status --type memory --json

LimitExceededException: Account limit for AgentCore runtimes exceeded

agentcore deploy -y

agentcore status
agentcore status --state pending-removal  # resources marked for deletion

[
  {
    "name": "staging",
    "description": "Staging environment",
    "account": "123456789012",
    "region": "us-east-1"
  },
  {
    "name": "production",
    "description": "Production environment",
    "account": "987654321098",
    "region": "us-west-2"
  }
]

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

© aws, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in plugins/aws-agents/skills/agents-deploy of aws/agent-toolkit-for-aws.

• SKILL.md
• references/versioning.md

Open the folder on GitHubat commit bd49cc8