# How to Deploy Applications Built with AWS Agent Toolkit on AWS

> Easily deploy applications built with AWS Agent Toolkit on AWS. Follow simple steps to create configuration files validate your setup and provision resources with agentcore deploy.

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

---

**Deploy AWS Agent Toolkit applications by creating the configuration files [`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 pre-flight validation with `agentcore validate`, and executing `agentcore deploy -y` to provision Bedrock AgentCore resources via AWS CDK.**

The `aws/agent-toolkit-for-aws` repository provides a complete deployment framework for AgentCore agents—AI-driven services that run on Amazon Bedrock. The canonical deployment logic resides in the **`agents-deploy`** skill located at [`plugins/aws-agents/skills/agents-deploy/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-deploy/SKILL.md), which orchestrates the entire process from configuration validation to resource provisioning.

## Configuration Setup

Before deploying, you must define two configuration files in your project root. These files tell the Toolkit how to build and where to deploy your agent.

**[`agentcore.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/agentcore.json)** defines the agent model, runtime, and optional memory resources. This file specifies which Bedrock model your agent uses and how it should execute.

**[`aws-targets.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/aws-targets.json)** lists the target AWS accounts and regions for deployment. Each target requires a unique name, AWS account ID, and region identifier.

Example structure for [`aws-targets.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/aws-targets.json):

```json
[
  {
    "name": "staging",
    "accountId": "123456789012",
    "region": "us-east-1"
  },
  {
    "name": "production",
    "accountId": "123456789012",
    "region": "us-west-2"
  }
]

```

## Pre-flight Validation

Run **`agentcore validate`** to execute the pre-flight checks defined in the `agents-deploy` skill. This command verifies:

- **CLI version** is greater than or equal to 0.9.0
- **Region alignment** between your AWS profile and target configurations
- **Bedrock model access** for your specified model IDs
- **CDK bootstrap status** in the target account and region
- **IAM permissions** via `aws iam simulate-principal-policy`

Check your CLI version before proceeding:

```bash
agentcore --version   # must be >= 0.9.0

```

Validate Bedrock model access in your target region:

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

```

Verify CDK bootstrap is complete:

```bash
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=$(aws configure get region)
npx cdk bootstrap "aws://$ACCOUNT/$REGION"

```

## Deployment Execution

The **`agentcore deploy`** command synthesizes and executes CDK stacks to create resources. Always run validation before deploying.

Preview changes without creating resources using the dry-run flags:

```bash

# View the CloudFormation template

agentcore deploy --dry-run

# Show diff against current state

agentcore deploy --diff

```

Deploy to the default target:

```bash
agentcore deploy -y

```

Deploy to a specific named target (e.g., staging):

```bash
agentcore deploy --target staging -y

```

According to the `agents-deploy` skill documentation, the deployment creates:
- **IAM roles** for Bedrock AgentCore
- **ECR repository** for container images
- **Lambda functions** or container runtimes
- **Optional Memory resources** (persistent storage services)

## Post-Deployment Verification

After deployment completes, verify the agent health and inspect resources.

Check deployment status:

```bash
agentcore status

```

View detailed logs in the generated log files:

```bash
ls -lt agentcore/.cli/logs/
cat agentcore/.cli/logs/deploy-*.log | tail -100

```

The **AWS MCP Server** mediates all AWS API calls from the agent and must remain configured in your agent's environment for deployment actions to function correctly.

## Advanced Deployment Options

### Rollback to Previous Versions

If deployment issues occur, rollback to a specific version:

```bash
agentcore rollback <version>

```

### Canary Deployments with Version Pinning

Pin a specific version for canary releases:

```bash
agentcore deploy --pin-version v1.2.3 -y

```

Refer to [`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) for detailed guidance on artifact management and release strategies.

## Summary

- Create **[`agentcore.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/agentcore.json)** for agent definitions and **[`aws-targets.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/aws-targets.json)** for deployment targets before running any commands.
- Execute **`agentcore validate`** to ensure CLI version ≥ 0.9.0, Bedrock access, CDK bootstrap, and IAM permissions are correct.
- Use **`agentcore deploy --dry-run`** to preview infrastructure changes before applying them.
- Deploy with **`agentcore deploy -y`** or target specific environments using **`--target <name>`**.
- Monitor post-deployment health via **`agentcore status`** and logs in `agentcore/.cli/logs/`.
- The **`agents-deploy`** skill at [`plugins/aws-agents/skills/agents-deploy/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-deploy/SKILL.md) provides the canonical reference for troubleshooting and advanced workflows.

## Frequently Asked Questions

### What IAM permissions are required to deploy AWS Agent Toolkit applications?

The deployment requires IAM permissions to create Bedrock agents, manage ECR repositories, deploy Lambda functions or container resources, and bootstrap CDK. The `agentcore validate` command runs `aws iam simulate-principal-policy` to verify your current credentials have sufficient access before attempting deployment.

### How can I deploy to multiple AWS accounts or regions?

Define each environment as a separate object in [`aws-targets.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/aws-targets.json) with unique name identifiers, account IDs, and regions. Use the `--target` flag with `agentcore deploy` to specify which configuration to deploy, allowing you to maintain separate staging and production environments within the same codebase.

### What should I do if the agentcore CLI version is below 0.9.0?

Update the CLI using `agentcore update` or your package manager. Version 0.9.0 or higher is required because earlier versions lack the validation logic and CDK synthesis capabilities described in the `agents-deploy` skill documentation.

### Where are deployment logs stored when troubleshooting failed deployments?

The Toolkit writes detailed logs to `agentcore/.cli/logs/` with timestamps. Use `ls -lt agentcore/.cli/logs/` to locate the most recent deployment log, then inspect the output for CDK synthesis errors, IAM permission denials, or Bedrock API failures.