@aws/agentcore-cdk

L3 CDK constructs for Amazon Bedrock AgentCore. Deploy agent infrastructure with strongly-typed, declarative specifications.

Installation

npm install @aws/agentcore-cdk

Note: aws-cdk-lib and constructs are peer dependencies. If you don't already have them:

npm install @aws/agentcore-cdk aws-cdk-lib constructs

Quick Start

import { AgentCoreApplication, AgentCoreMcp } from '@aws/agentcore-cdk';
import type { AgentCoreProjectSpec } from '@aws/agentcore-cdk';
import { Stack } from 'aws-cdk-lib';

const spec: AgentCoreProjectSpec = {
  name: 'myProject',
  version: 1,
  agents: [
    {
      type: 'AgentCoreRuntime',
      name: 'myAgent',
      build: 'CodeZip',
      entrypoint: 'main.py',
      codeLocation: 'app/myAgent/',
      runtimeVersion: 'PYTHON_3_12',
    },
  ],
};

class MyStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new AgentCoreApplication(this, 'App', { spec });
  }
}

Constructs

AgentCoreApplication

Main L3 construct for deploying agent environments.

AgentCoreMcp

L3 construct for MCP gateways and tools.

AgentEnvironment

Individual agent environment construct.

Container builds in a VPC

When a Container-build agent (or harness) sets networkMode: VPC, the build infrastructure — the orchestrator Lambda and the shared CodeBuild project — is placed in the same VPC as the runtime, using networkConfig.subnets and networkConfig.securityGroups. CodeBuild additionally requires networkConfig.vpcId (its API cannot infer the VPC from subnets); it is required only for Container builds in VPC mode.

All Container agents and harnesses in a single project must build in the same VPC — the CodeBuild project is shared per stack and synthesis fails fast on a mismatch. Container builds in VPC mode allow at most 5 security groups (a CodeBuild limit), vs 16 for the runtime.

Network prerequisites. Private subnets must be able to reach the services the build uses, or the build will hang until timeout:

• The build Lambda calls CodeBuild (StartBuild/BatchGetBuilds) and must reach the CloudFormation response endpoint (S3).
• CodeBuild must reach ECR (api + dkr), S3 (source asset), CloudWatch Logs, STS, and any registry the Dockerfile pulls base images from.

Provide a NAT gateway or VPC endpoints for: ECR (api, dkr), S3 (gateway), CloudWatch Logs, CodeBuild, and STS — plus egress for public base-image pulls.

Standalone Usage

These constructs can be used independently without the CLI:

import { AgentCoreApplication, ConfigIO } from '@aws/agentcore-cdk';

// Option 1: Pass spec directly
new AgentCoreApplication(this, 'App', {
  spec: {
    name: 'myProject',
    version: 1,
    agents: [
      {
        type: 'AgentCoreRuntime',
        name: 'myAgent',
        build: 'CodeZip',
        entrypoint: 'main.py',
        codeLocation: 'app/myAgent/',
        runtimeVersion: 'PYTHON_3_12',
      },
    ],
  },
});

// Option 2: Read from disk (using built-in ConfigIO)
const configIO = new ConfigIO({ baseDir: './agentcore' });
const spec = await configIO.readProjectSpec();
new AgentCoreApplication(this, 'App', { spec });

Related Package

• @aws/agentcore - CLI tool that uses these constructs via templated CDK projects

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.