How to Deploy Applications Built with AWS Agent Toolkit on AWS

Deploy AWS Agent Toolkit applications by creating the configuration files agentcore.json and 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, 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 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 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:

[
  {
    "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:

agentcore --version   # must be >= 0.9.0

Validate Bedrock model access in your target region:

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

Verify CDK bootstrap is complete:

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:

# View the CloudFormation template

agentcore deploy --dry-run

# Show diff against current state

agentcore deploy --diff

Deploy to the default target:

agentcore deploy -y

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

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:

agentcore status

View detailed logs in the generated log files:

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:

agentcore rollback <version>

Canary Deployments with Version Pinning

Pin a specific version for canary releases:

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

Refer to plugins/aws-agents/skills/agents-deploy/references/versioning.md for detailed guidance on artifact management and release strategies.

Summary

• Create agentcore.json for agent definitions and 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 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 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.

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