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

> Deploy AWS Agent Toolkit agents easily using CDK. Configure agentcore.json and aws-targets.json, run validation, and deploy with agentcore deploy for seamless AWS resource provisioning.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Deploy AgentCore agents by configuring [`agentcore.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/agentcore.json) and [`aws-targets.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-deploy/SKILL.md), 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:

```bash

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

```bash

# 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/aws-targets.json):

```bash

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

```bash
agentcore status

```

Inspect detailed logs generated during the deployment:

```bash

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

```bash
agentcore rollback <version-id>

```

**Canary deployments with version pinning:**

```bash
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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-deploy/references/versioning.md).

## Summary

- **Configuration** – Define [`agentcore.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/agentcore.json) for agent specs and [`aws-targets.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.