How to Deploy Agents Created with AWS Agent Toolkit: Complete CDK Guide

Deploy AgentCore agents by configuring agentcore.json and aws-targets.json, running agentcore validate for pre-flight checks, and executing agentcore deploy -y to provision IAM roles, ECR repositories, and Lambda runtimes via AWS CDK.

The AWS Agent Toolkit enables developers to build AgentCore agents—AI-driven services that run on Amazon Bedrock. Deploying these agents requires orchestrating configuration files, validation routines, and CDK-based infrastructure provisioning. This guide explains how to deploy agents created with the AWS Agent Toolkit using the canonical agents-deploy skill as implemented in the aws/agent-toolkit-for-aws repository.

Prerequisites and Configuration Files

Before deploying, you must define two mandatory configuration files in your project root.

agentcore.json specifies the agent model, runtime parameters, and optional memory resources. This file defines the core behavior and infrastructure requirements for your AgentCore agent.

aws-targets.json lists the deployment targets—including target names, AWS account IDs, and regions—where the agent will be provisioned. According to the agents-deploy skill documentation, these files reside in the agentcore/ directory by convention.

Pre-Flight Validation Workflow

The Toolkit enforces a strict validation phase to prevent deployment failures. Run agentcore validate to execute the pre-flight checks codified in the skill definition.

The validation process verifies:

• CLI version compatibility – Requires agentcore CLI version ≥ 0.9.0
• Region alignment – Ensures configured regions match your AWS profile
• Bedrock model access – Confirms your account has access to the specified foundation models
• CDK bootstrap status – Validates that AWS CDK bootstrap resources exist in the target account and region
• IAM permissions – Simulates principal policies using aws iam simulate-principal-policy

Execute the complete validation sequence:

# Verify CLI version

agentcore --version

# Run comprehensive validation

agentcore validate

# Check target configuration

cat agentcore/aws-targets.json | jq '.[] | {name, region, accountId}'

Deployment Execution

Once validation passes, use the agentcore deploy command to provision resources. The Toolkit uses AWS CDK (or optionally SAM) to synthesize and deploy CloudFormation stacks.

Preview Changes with Dry-Run

Before creating resources, preview the infrastructure changes:

# Generate CloudFormation template without deploying

agentcore deploy --dry-run

# View difference between current and desired state

agentcore deploy --diff

These commands reference the CDK synth and diff operations documented in lines 109–114 of the skill file.

Execute Deployment

Deploy to your default target or specify a named target from aws-targets.json:

# Deploy to default target with confirmation bypass

agentcore deploy -y

# Deploy to specific target (e.g., staging)

agentcore deploy --target staging -y

The deployment process creates the following AWS resources:

• IAM roles – Service-linked roles for Bedrock AgentCore execution
• ECR repository – Container registry for agent artifacts
• Lambda functions – Serverless compute runtime (or container-based alternatives)
• Memory resources – Optional persistent storage service for agent state

Post-Deployment Verification

After deployment completes, verify resource health and monitor logs.

Check deployment status across all components:

agentcore status

Inspect detailed logs generated during the deployment:

# List recent log files

ls -lt agentcore/.cli/logs/

# View latest deployment logs

tail -100 agentcore/.cli/logs/deploy-*.log

Versioning and Rollback Operations

The Toolkit supports advanced deployment strategies including version pinning and rollbacks.

Rollback to previous version:

agentcore rollback <version-id>

Canary deployments with version pinning:

agentcore deploy --pin-version vX.Y.Z -y

These operations reference the versioning logic documented in plugins/aws-agents/skills/agents-deploy/references/versioning.md.

Summary

• Configuration – Define agentcore.json for agent specs and aws-targets.json for deployment targets before running any commands.
• Validation – Execute agentcore validate to verify CLI version, Bedrock access, CDK bootstrap, and IAM permissions.
• Deployment – Use agentcore deploy -y to provision IAM roles, ECR repos, Lambda functions, and optional memory resources via CDK.
• Verification – Monitor deployment health using agentcore status and inspect logs in agentcore/.cli/logs/.
• Advanced ops – Leverage agentcore rollback and --pin-version for safe deployment strategies.

Frequently Asked Questions

What is the minimum required version of the agentcore CLI?

The AWS Agent Toolkit requires agentcore CLI version 0.9.0 or higher. Earlier versions lack the validation routines and CDK integration necessary for proper AgentCore deployment. Run agentcore --version to verify your installation before proceeding with deployment operations.

Why does deployment fail with a CDK bootstrap error?

The agentcore deploy command requires CDK bootstrap resources to exist in your target AWS account and region. If you encounter bootstrap errors, run npx cdk bootstrap aws://<account-id>/<region> to provision the necessary staging resources. The pre-flight validation (agentcore validate) specifically checks for this prerequisite using the CDK bootstrap status API.

How do I deploy to multiple AWS accounts or regions?

Define multiple targets in your aws-targets.json file, specifying unique target names, account IDs, and regions for each environment. Use the --target <name> flag with agentcore deploy to specify which target configuration to use. For example: agentcore deploy --target production -y deploys to the production target defined in your configuration.

Where are deployment logs stored for troubleshooting?

Deployment logs are written to the agentcore/.cli/logs/ directory in your project root. Each deployment creates timestamped log files (e.g., deploy-2024-*.log) that capture CDK synthesis output, CloudFormation events, and AWS API responses. Use tail or cat commands on these files to diagnose deployment failures or verify resource creation status.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}