AWS CDK Bedrock AgentCore (Alpha)

2.252.0a0 verified Fri May 01 auth: no python

The AWS CDK Construct Library for Amazon Bedrock (agent core) in an alpha state. Currently at version 2.252.0a0, it allows defining Bedrock agents, action groups, knowledge bases, and AI guardrails with the CDK. This module has a release cadence that tracks the main aws-cdk library, and breaking changes can occur as it is in alpha.

pip install aws-cdk-aws-bedrock-agentcore-alpha

Common errors

error ModuleNotFoundError: No module named 'aws_cdk.aws_bedrock_agentcore_alpha' ↓

cause Library not installed or installed under a different distribution name.

fix

Run: pip install aws-cdk-aws-bedrock-agentcore-alpha

error ImportError: cannot import name 'BedrockAgent' from 'aws_cdk.aws_bedrock_agentcore_alpha' ↓

cause Wrong import or the symbol does not exist in that version; possibly a rename.

fix

Check the exact class name in the version you installed. Try: from aws_cdk.aws_bedrock_agentcore_alpha import CfnAgent

error TypeError: __init__() got an unexpected keyword argument 'foundation_model' ↓

cause The property name has changed between versions (e.g., to 'model' or 'foundation_model_id').

fix

Check the latest API docs and use the correct property. For recent versions: model=FoundationModel.from_foundation_model_id('anthropic.claude-v2')

error JSIIError: jsii.errors.JSIIError: Expected a string, got undefined ↓

cause A required argument is missing or set to None when it should be a string.

fix

Ensure all required properties are provided, e.g., instruction must not be empty.

error AttributeError: 'BedrockAgent' object has no attribute 'agent_id' ↓

cause The property is called 'agentArn' or does not exist until the agent is deployed.

fix

Use .agent_arn to get the ARN after deployment, or check the correct property name.

Warnings

gotcha Alpha modules do not follow semantic versioning; breaking changes may occur between minor/patch releases. Pin your version appropriately. ↓

fix Use a pinned version like 2.252.0a0 and test upgrades.

gotcha Import paths for alpha modules use `aws_cdk.aws_bedrock_agentcore_alpha` (note: `alpha` suffix). Users often miss the suffix and import incorrectly. ↓

fix Use `from aws_cdk.aws_bedrock_agentcore_alpha import ...`

deprecated Some older property names like `lambda_` for Lambda function ARNs are deprecated in favor of `lambda_function_arn` or similar. ↓

fix Check the latest API docs for correct property names.

breaking The `foundation_model` property used to accept a string like 'anthropic.claude-v2' but now may require a `FoundationModel` object in newer versions. ↓

fix Use `FoundationModel.from_foundation_model_id('anthropic.claude-v2')` or similar.

Imports

BedrockAgent

wrong

from aws_cdk.aws_bedrock_agent import BedrockAgent

correct

from aws_cdk.aws_bedrock_agentcore_alpha import BedrockAgent

The module is alpha and has a different import path.

ActionGroup

wrong

from aws_cdk.aws_bedrock_agentcore import ActionGroup

correct

from aws_cdk.aws_bedrock_agentcore_alpha import ActionGroup

Older import paths may not exist or may have been renamed.

KnowledgeBase

from aws_cdk.aws_bedrock_agentcore_alpha import KnowledgeBase

Guardrail

from aws_cdk.aws_bedrock_agentcore_alpha import Guardrail

S3DataSource

from aws_cdk.aws_bedrock_agentcore_alpha import S3DataSource

Quickstart

Create a simple Bedrock agent with default settings.

from aws_cdk import App, Stack
from aws_cdk.aws_bedrock_agentcore_alpha import BedrockAgent

app = App()
stack = Stack(app, "MyStack")
agent = BedrockAgent(stack, "MyAgent",
    foundation_model="anthropic.claude-v2",
    instruction="You are a helpful assistant.",
    idle_ttl_in_seconds=600
)
app.synth()