Amazon.CDK.AWS.Bedrock.Agentcore.Alpha

Amazon Bedrock AgentCore Construct Library

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

The Policy submodule is the only submodule that remains in alpha. All other constructs have graduated to stable in aws-cdk-lib/aws-bedrockagentcore and we recommend migrating to the stable versions.

Language	Package
TypeScript	@aws-cdk/aws-bedrock-agentcore-alpha

Migration to Stable

All constructs except Policy have moved to aws-cdk-lib/aws-bedrockagentcore:

// Before
using Amazon.CDK.AWS.Bedrock.Agentcore.Alpha;

// After (for all non-Policy constructs)
using Amazon.CDK.AWS.BedrockAgentCore;

The following constructs are now in stable:

• Runtime: Runtime, RuntimeEndpoint, AgentRuntimeArtifact, NetworkConfiguration, Observability
• Gateway: Gateway, GatewayTarget, GatewayAuthorizer, GatewayCredentialProvider, Interceptor
• Tools: BrowserCustom, CodeInterpreterCustom
• Memory: Memory, MemoryStrategy
• Evaluation: OnlineEvaluationConfig, Evaluator, EvaluatorSelector
• Identity: OAuth2CredentialProvider, ApiKeyCredentialProvider, WorkloadIdentity

What Remains in Alpha

The Policy submodule remains experimental:

• PolicyEngine
• Policy
• PolicyStatement
• PolicyValidationMode
• PolicyEngineMode

Policy Engine

A policy engine is a collection of policies that evaluates and authorizes agent tool calls. When associated with a gateway, the policy engine intercepts all agent requests and determines whether to allow or deny each action based on the defined policies.

For more information, see the Policy in Amazon Bedrock AgentCore documentation.

PolicyEngine Properties

Understanding Cedar Policies in AgentCore

Policies are constructed using Cedar language, an open source language for writing and enforcing authorization policies. Cedar policies in AgentCore follow a specific structure with three main components: Principal, Action, and Resource. Understanding how these components work together is critical for writing effective policies.

Policy Structure

Every Cedar policy has this basic structure:

permit(              // or forbid
  principal,         // Who is making the request
  action,            // What operation they want to perform
  resource           // What Gateway/tool they want to access
)
when {               // Optional conditions
  // Additional constraints
};

Example Policy

permit(
  principal,
  action == AgentCore::Action::"ApplicationToolTarget___create_application",
  resource == AgentCore::Gateway::"<gateway-arn>"
) when {
  context.input.coverage_amount <= 1000000
};

Basic PolicyEngine and Policy Creation

Create a policy engine and add policies to it.

Policy Engine Mode

When associating a policy engine with a gateway, you can control the enforcement behavior using PolicyEngineMode:

• PolicyEngineMode.LOG_ONLY (default) — evaluates actions and adds traces but does not enforce decisions. Use this mode for testing and validation before enabling enforcement.
• PolicyEngineMode.ENFORCE — actively allows or denies agent operations based on Cedar policy evaluation.

// Create a Policy engine
var policyEngine = new PolicyEngine(this, "MyPolicyEngine", new PolicyEngineProps {
    PolicyEngineName = "my_policy_engine",
    Description = "Policy engine for access control"
});

var gateway = new Gateway(this, "MyGateway", new GatewayProps {
    GatewayName = "my-gateway",
    PolicyEngineConfiguration = new GatewayPolicyEngineConfig {
        PolicyEngine = policyEngine,
        Mode = PolicyEngineMode.ENFORCE
    }
});

// Add policy to policy engine
policyEngine.AddPolicy("AllowAllActions", new AddPolicyOptions {
    Definition = $@"
        permit(
          principal,
          action,
          resource == AgentCore::Gateway::""{gateway.gatewayArn}""
        );
      ",
    Description = "Allow all actions on specific gateway (development)",
    ValidationMode = PolicyValidationMode.IGNORE_ALL_FINDINGS
});

// you can add multiple policies to the policy engine
policyEngine.AddPolicy("SpecificToolPolicy", new AddPolicyOptions {
    Definition = $@"
        permit(
          principal is AgentCore::OAuthUser,
          action == AgentCore::Action::""WeatherTool__get_forecast"",
          resource == AgentCore::Gateway::""{gateway.gatewayArn}""
        );
      ",
    Description = "Allow specific weather tool access",
    ValidationMode = PolicyValidationMode.FAIL_ON_ANY_FINDINGS
});

Type-Safe Policy Builder

For a more type-safe approach, use the PolicyStatement builder instead of writing raw Cedar syntax.

var gateway = new Gateway(this, "MyGateway", new GatewayProps {
    GatewayName = "my-gateway"
});

var policyEngine = new PolicyEngine(this, "MyPolicyEngine", new PolicyEngineProps {
    PolicyEngineName = "my_policy_engine"
});

var allowAllPolicy = new Policy(this, "AllowAllPolicy", new PolicyProps {
    PolicyEngine = policyEngine,
    PolicyName = "allow_all",
    Statement = PolicyStatement.Permit().ForAllPrincipals().OnAllActions().OnResource("AgentCore::Gateway", gateway.GatewayArn),
    Description = "Allow all actions on specific gateway (development only)",
    ValidationMode = PolicyValidationMode.IGNORE_ALL_FINDINGS
});

Policy with Specific Actions

PolicyEngine policyEngine;
Gateway gateway;


// Allow specific tool actions on specific gateway
// Action names follow pattern: "ToolName__operation"
policyEngine.AddPolicy("SpecificToolPolicy", new AddPolicyOptions {
    Statement = PolicyStatement.Permit().ForPrincipal("AgentCore::OAuthUser::your-client-id").OnActions(new [] { "AgentCore::Action::WeatherTool__get_forecast", "AgentCore::Action::WeatherTool__get_current" }).OnResource("AgentCore::Gateway", gateway.GatewayArn),
    Description = "Allow specific weather tool operations",
    ValidationMode = PolicyValidationMode.FAIL_ON_ANY_FINDINGS
});

Policy with Conditions

Use when clauses to add advanced conditions based on principal tags (from OAuth token) or context:

PolicyEngine policyEngine;
Gateway gateway;


// Policy with when conditions using principal tags
var conditionalPolicy = new Policy(this, "ConditionalPolicy", new PolicyProps {
    PolicyEngine = policyEngine,
    PolicyName = "conditional_access",
    Statement = PolicyStatement.Permit().ForPrincipal("AgentCore::OAuthUser").OnAllActions().OnResource("AgentCore::Gateway", gateway.GatewayArn).When().PrincipalAttribute("department").EqualTo("Engineering").And().ContextAttribute("input.priority").EqualTo("high").Done(),
    Description = "Allow engineers for high-priority requests",
    ValidationMode = PolicyValidationMode.FAIL_ON_ANY_FINDINGS
});

Policy with Exclusions (unless)

Use unless clauses to exclude specific conditions from a policy. The policy applies when the unless conditions are NOT met:

PolicyEngine policyEngine;
Gateway gateway;


// Allow access unless the user is suspended
var policyWithUnless = new Policy(this, "UnlessPolicy", new PolicyProps {
    PolicyEngine = policyEngine,
    PolicyName = "unless_suspended",
    Statement = PolicyStatement.Permit().ForPrincipal("AgentCore::OAuthUser").OnAllActions().OnResource("AgentCore::Gateway", gateway.GatewayArn).Unless().PrincipalAttribute("suspended").EqualTo(true).Done(),
    Description = "Allow all actions unless user is suspended",
    ValidationMode = PolicyValidationMode.FAIL_ON_ANY_FINDINGS
});

You can combine when and unless clauses in the same policy:

PolicyEngine policyEngine;
Gateway gateway;


// Allow engineers unless they are on probation
policyEngine.AddPolicy("CombinedConditions", new AddPolicyOptions {
    Statement = PolicyStatement.Permit().ForPrincipal("AgentCore::OAuthUser").OnAllActions().OnResource("AgentCore::Gateway", gateway.GatewayArn).When().PrincipalAttribute("department").EqualTo("Engineering").Done().Unless().PrincipalAttribute("status").EqualTo("probation").Done(),
    Description = "Allow engineers unless on probation",
    ValidationMode = PolicyValidationMode.FAIL_ON_ANY_FINDINGS
});

Forbid (Deny) Policy

Use forbid to explicitly deny access. Forbid policies override permit policies.

PolicyEngine policyEngine;
Gateway gateway;


// Explicitly deny dangerous tool operations
policyEngine.AddPolicy("DenyDangerous", new AddPolicyOptions {
    Statement = PolicyStatement.Forbid().ForAllPrincipals().OnAction("AgentCore::Action::DeleteTool__delete_all").OnResource("AgentCore::Gateway", gateway.GatewayArn),
    Description = "Forbid delete_all operation for all users",
    ValidationMode = PolicyValidationMode.FAIL_ON_ANY_FINDINGS
});

Raw Cedar for Advanced Cases

For advanced Cedar features not supported by the builder, use raw Cedar strings:

PolicyEngine policyEngine;


// Option 1: Using definition property
var advancedPolicy = new Policy(this, "AdvancedPolicy", new PolicyProps {
    PolicyEngine = policyEngine,
    Definition = "permit(principal, action, resource) when { context.custom > 10 };",
    Description = "Advanced policy with custom Cedar logic"
});

// Option 2: Using fromCedar() with statement property
policyEngine.AddPolicy("CustomPolicy", new AddPolicyOptions {
    Statement = PolicyStatement.FromCedar("forbid(principal, action, resource) when { resource.confidential == true };"),
    Description = "Custom policy from Cedar string"
});

Note: You must specify either definition (raw Cedar string) or statement (PolicyStatement builder), but not both.

Accessing Policies on PolicyEngine

You can access the list of policies added to a PolicyEngine using policyEngine.policies.

PolicyEngine with KMS Encryption

Encrypt policy data with a custom KMS key.

// Create a custom KMS key
var policyKey = new Key(this, "PolicyEngineKey", new KeyProps {
    EnableKeyRotation = true,
    Description = "KMS key for policy engine encryption"
});

// Create policy engine with encryption
var policyEngine = new PolicyEngine(this, "EncryptedEngine", new PolicyEngineProps {
    PolicyEngineName = "encrypted_engine",
    Description = "Policy engine with KMS encryption",
    KmsKey = policyKey
});

Importing Existing PolicyEngine

Import an existing policy engine from its ARN:

var importedEngine = PolicyEngine.FromPolicyEngineAttributes(this, "ImportedEngine", new PolicyEngineAttributes {
    PolicyEngineArn = "policy-engine-arn",
    KmsKeyArn = "kms-arn"
});

// Use the imported engine
var policy = new Policy(this, "PolicyForImportedEngine", new PolicyProps {
    PolicyEngine = importedEngine,
    Definition = "permit(principal, action, resource);"
});

Importing Existing Policy

Import an existing policy from its ARN:

var importedEngine = PolicyEngine.FromPolicyEngineAttributes(this, "ImportedEngine", new PolicyEngineAttributes {
    PolicyEngineArn = "policy-engine/my-engine-id"
});

var importedPolicy = Policy.FromPolicyAttributes(this, "ImportedPolicy", new PolicyAttributes {
    PolicyArn = "my-policy-arn",
    PolicyEngine = importedEngine
});

// Grant permissions to the imported policy
var role = new Role(this, "PolicyRole", new RoleProps {
    AssumedBy = new ServicePrincipal("lambda.amazonaws.com")
});

importedPolicy.GrantRead(role);

PolicyEngine IAM Permissions

Grant various levels of access to policy engines:

var policyEngine = new PolicyEngine(this, "MyEngine", new PolicyEngineProps {
    PolicyEngineName = "my_engine"
});

var lambdaRole = new Role(this, "LambdaRole", new RoleProps {
    AssumedBy = new ServicePrincipal("lambda.amazonaws.com")
});

// Grant read permissions
policyEngine.GrantRead(lambdaRole);

// Grant evaluation permissions
policyEngine.GrantEvaluate(lambdaRole);

Using Policy with Stable Gateway

Since Gateway is now in aws-cdk-lib/aws-bedrockagentcore but Policy remains in alpha, use the L1 escape hatch to associate a policy engine with a stable gateway:

Proper L2 integration will be added in a future update.

using Amazon.CDK.AWS.BedrockAgentCore;
using Amazon.CDK.AWS.Bedrock.Agentcore.Alpha;


// Create policy engine (alpha)
var policyEngine = new PolicyEngine(this, "Engine", new PolicyEngineProps {
    PolicyEngineName = "my_engine"
});

// Create gateway (stable)
var gateway = new Gateway(this, "Gateway", new GatewayProps {
    GatewayName = "my-gateway"
});

// Wire policy engine to gateway via the L1 construct
var cfnGateway = (CfnGateway)gateway.Node.DefaultChild;
cfnGateway.PolicyEngineConfiguration = new GatewayPolicyEngineConfigurationProperty {
    Arn = policyEngine.PolicyEngineArn,
    Mode = PolicyEngineMode.ENFORCE.Value
};

// Grant evaluate permissions to the gateway role
gateway.Role.AddToPrincipalPolicy(new PolicyStatement(new PolicyStatementProps {
    Actions = new [] { "bedrock-agentcore:GetPolicyEngine" },
    Resources = new [] { policyEngine.PolicyEngineArn }
}));
gateway.Role.AddToPrincipalPolicy(new PolicyStatement(new PolicyStatementProps {
    Actions = new [] { "bedrock-agentcore:AuthorizeAction", "bedrock-agentcore:PartiallyAuthorizeActions" },
    Resources = new [] { policyEngine.PolicyEngineArn, gateway.GatewayArn }
}));