Package software.amazon.awscdk.services.bedrock.agentcore.alpha

@Stability(Experimental) package software.amazon.awscdk.services.bedrock.agentcore.alpha

Amazon Bedrock AgentCore Construct Library

---

cdk-constructs: Experimental

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 Logo TypeScript | @aws-cdk/aws-bedrock-agentcore-alpha |

Migration to Stable

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

 // Before
 import software.amazon.awscdk.services.bedrock.agentcore.alpha.*;
 

 // After (for all non-Policy constructs)
 import software.amazon.awscdk.services.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

| Name | Type | Required | Description | |------|------|----------|-------------| | policyEngineName | string | No | The name of the policy engine. Valid characters: a-z, A-Z, 0-9, _ (underscore). Must start with a letter, 1-48 characters. If not provided, a unique name will be auto-generated | | description | string | No | Optional description for the policy engine (max 4,096 characters). Default: no description | | kmsKey | IKey | No | Custom KMS key for encryption. IMPORTANT: Once set, cannot be changed (requires replacement). Must be symmetric ENCRYPT_DECRYPT key. If key becomes inaccessible, all authorization decisions will be DENIED. Default: AWS owned key | | tags | { [key: string]: string } | No | Tags for the policy engine (max 50 tags). Default: no tags |

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
 PolicyEngine policyEngine = PolicyEngine.Builder.create(this, "MyPolicyEngine")
         .policyEngineName("my_policy_engine")
         .description("Policy engine for access control")
         .build();
 
 Gateway gateway = Gateway.Builder.create(this, "MyGateway")
         .gatewayName("my-gateway")
         .policyEngineConfiguration(GatewayPolicyEngineConfig.builder()
                 .policyEngine(policyEngine)
                 .mode(PolicyEngineMode.ENFORCE)
                 .build())
         .build();
 
 // Add policy to policy engine
 policyEngine.addPolicy("AllowAllActions", AddPolicyOptions.builder()
         .definition(String.format("%n    permit(%n      principal,%n      action,%n      resource == AgentCore::Gateway::\"%s\"%n    );%n  ", gateway.getGatewayArn()))
         .description("Allow all actions on specific gateway (development)")
         .validationMode(PolicyValidationMode.IGNORE_ALL_FINDINGS)
         .build());
 
 // you can add multiple policies to the policy engine
 policyEngine.addPolicy("SpecificToolPolicy", AddPolicyOptions.builder()
         .definition(String.format("%n    permit(%n      principal is AgentCore::OAuthUser,%n      action == AgentCore::Action::\"WeatherTool__get_forecast\",%n      resource == AgentCore::Gateway::\"%s\"%n    );%n  ", gateway.getGatewayArn()))
         .description("Allow specific weather tool access")
         .validationMode(PolicyValidationMode.FAIL_ON_ANY_FINDINGS)
         .build());

Type-Safe Policy Builder

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

 Gateway gateway = Gateway.Builder.create(this, "MyGateway")
         .gatewayName("my-gateway")
         .build();
 
 PolicyEngine policyEngine = PolicyEngine.Builder.create(this, "MyPolicyEngine")
         .policyEngineName("my_policy_engine")
         .build();
 
 Policy allowAllPolicy = Policy.Builder.create(this, "AllowAllPolicy")
         .policyEngine(policyEngine)
         .policyName("allow_all")
         .statement(PolicyStatement.permit().forAllPrincipals().onAllActions().onResource("AgentCore::Gateway", gateway.getGatewayArn()))
         .description("Allow all actions on specific gateway (development only)")
         .validationMode(PolicyValidationMode.IGNORE_ALL_FINDINGS)
         .build();

Policy with Specific Actions

 PolicyEngine policyEngine;
 Gateway gateway;
 
 
 // Allow specific tool actions on specific gateway
 // Action names follow pattern: "ToolName__operation"
 policyEngine.addPolicy("SpecificToolPolicy", AddPolicyOptions.builder()
         .statement(PolicyStatement.permit().forPrincipal("AgentCore::OAuthUser::your-client-id").onActions(List.of("AgentCore::Action::WeatherTool__get_forecast", "AgentCore::Action::WeatherTool__get_current")).onResource("AgentCore::Gateway", gateway.getGatewayArn()))
         .description("Allow specific weather tool operations")
         .validationMode(PolicyValidationMode.FAIL_ON_ANY_FINDINGS)
         .build());

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
 Policy conditionalPolicy = Policy.Builder.create(this, "ConditionalPolicy")
         .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)
         .build();

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
 Policy policyWithUnless = Policy.Builder.create(this, "UnlessPolicy")
         .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)
         .build();

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", AddPolicyOptions.builder()
         .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)
         .build());

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", AddPolicyOptions.builder()
         .statement(PolicyStatement.forbid().forAllPrincipals().onAction("AgentCore::Action::DeleteTool__delete_all").onResource("AgentCore::Gateway", gateway.getGatewayArn()))
         .description("Forbid delete_all operation for all users")
         .validationMode(PolicyValidationMode.FAIL_ON_ANY_FINDINGS)
         .build());

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
 Policy advancedPolicy = Policy.Builder.create(this, "AdvancedPolicy")
         .policyEngine(policyEngine)
         .definition("permit(principal, action, resource) when { context.custom > 10 };")
         .description("Advanced policy with custom Cedar logic")
         .build();
 
 // Option 2: Using fromCedar() with statement property
 policyEngine.addPolicy("CustomPolicy", AddPolicyOptions.builder()
         .statement(PolicyStatement.fromCedar("forbid(principal, action, resource) when { resource.confidential == true };"))
         .description("Custom policy from Cedar string")
         .build());

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
 Key policyKey = Key.Builder.create(this, "PolicyEngineKey")
         .enableKeyRotation(true)
         .description("KMS key for policy engine encryption")
         .build();
 
 // Create policy engine with encryption
 PolicyEngine policyEngine = PolicyEngine.Builder.create(this, "EncryptedEngine")
         .policyEngineName("encrypted_engine")
         .description("Policy engine with KMS encryption")
         .kmsKey(policyKey)
         .build();

Importing Existing PolicyEngine

Import an existing policy engine from its ARN: 

 IPolicyEngine importedEngine = PolicyEngine.fromPolicyEngineAttributes(this, "ImportedEngine", PolicyEngineAttributes.builder()
         .policyEngineArn("policy-engine-arn")
         .kmsKeyArn("kms-arn")
         .build());
 
 // Use the imported engine
 Policy policy = Policy.Builder.create(this, "PolicyForImportedEngine")
         .policyEngine(importedEngine)
         .definition("permit(principal, action, resource);")
         .build();

Importing Existing Policy

Import an existing policy from its ARN: 

 IPolicyEngine importedEngine = PolicyEngine.fromPolicyEngineAttributes(this, "ImportedEngine", PolicyEngineAttributes.builder()
         .policyEngineArn("policy-engine/my-engine-id")
         .build());
 
 IPolicy importedPolicy = Policy.fromPolicyAttributes(this, "ImportedPolicy", PolicyAttributes.builder()
         .policyArn("my-policy-arn")
         .policyEngine(importedEngine)
         .build());
 
 // Grant permissions to the imported policy
 Role role = Role.Builder.create(this, "PolicyRole")
         .assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
         .build();
 
 importedPolicy.grantRead(role);

PolicyEngine IAM Permissions

Grant various levels of access to policy engines: 

 PolicyEngine policyEngine = PolicyEngine.Builder.create(this, "MyEngine")
         .policyEngineName("my_engine")
         .build();
 
 Role lambdaRole = Role.Builder.create(this, "LambdaRole")
         .assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
         .build();
 
 // 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. 

 import software.amazon.awscdk.services.bedrockagentcore.*;
 import software.amazon.awscdk.services.bedrock.agentcore.alpha.*;
 
 
 // Create policy engine (alpha)
 PolicyEngine policyEngine = PolicyEngine.Builder.create(this, "Engine")
         .policyEngineName("my_engine")
         .build();
 
 // Create gateway (stable)
 Gateway gateway = Gateway.Builder.create(this, "Gateway")
         .gatewayName("my-gateway")
         .build();
 
 // Wire policy engine to gateway via the L1 construct
 CfnGateway cfnGateway = (CfnGateway)gateway.getNode().getDefaultChild();
 cfnGateway.getPolicyEngineConfiguration() = GatewayPolicyEngineConfigurationProperty.builder()
         .arn(policyEngine.getPolicyEngineArn())
         .mode(PolicyEngineMode.ENFORCE.getValue())
         .build();
 
 // Grant evaluate permissions to the gateway role
 gateway.role.addToPrincipalPolicy(PolicyStatement.Builder.create()
         .actions(List.of("bedrock-agentcore:GetPolicyEngine"))
         .resources(List.of(policyEngine.getPolicyEngineArn()))
         .build());
 gateway.role.addToPrincipalPolicy(PolicyStatement.Builder.create()
         .actions(List.of("bedrock-agentcore:AuthorizeAction", "bedrock-agentcore:PartiallyAuthorizeActions"))
         .resources(List.of(policyEngine.getPolicyEngineArn(), gateway.getGatewayArn()))
         .build());