Experimental

@aws-cdk/aws-bedrock-agentcore-alpha is an experimental (alpha) package: its API may change in any release, without a major version bump.

PolicyEngine L2 construct

Container that manages Cedar authorization policies associated with gateways.

PolicyEngine enables deterministic authorization control for Bedrock agents, allowing fine-grained access control to tools and actions via Cedar policy language.

Stability: Experimental
CloudFormation: AWS::BedrockAgentCore::PolicyEngine
L1 type: CfnPolicyEngine
Source: lib/policy/policy-engine.ts

Example

const importedEngine = agentcore.PolicyEngine.fromPolicyEngineAttributes(
  this,
  "ImportedEngine",
  {
    policyEngineArn: "policy-engine/my-engine-id",
  }
);

const importedPolicy = agentcore.Policy.fromPolicyAttributes(
  this,
  "ImportedPolicy",
  {
    policyArn: "my-policy-arn",
    policyEngine: importedEngine,
  }
);

// Grant permissions to the imported policy
const role = new iam.Role(this, "PolicyRole", {
  assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
});

importedPolicy.grantRead(role);

python

imported_engine = agentcore.PolicyEngine.from_policy_engine_attributes(self, "ImportedEngine",
    policy_engine_arn="policy-engine/my-engine-id"
)

imported_policy = agentcore.Policy.from_policy_attributes(self, "ImportedPolicy",
    policy_arn="my-policy-arn",
    policy_engine=imported_engine
)

# Grant permissions to the imported policy
role = iam.Role(self, "PolicyRole",
    assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
)

imported_policy.grant_read(role)

java

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);

csharp

// Install: dotnet add package Amazon.CDK.AWS.Bedrock.Agentcore.Alpha
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);

// Install: go get github.com/aws/aws-cdk-go/awsbedrockagentcorealpha/v2
importedEngine := agentcore.PolicyEngine_FromPolicyEngineAttributes(this, jsii.String("ImportedEngine"), &PolicyEngineAttributes{
	PolicyEngineArn: jsii.String("policy-engine/my-engine-id"),
})

importedPolicy := agentcore.Policy_FromPolicyAttributes(this, jsii.String("ImportedPolicy"), &PolicyAttributes{
	PolicyArn: jsii.String("my-policy-arn"),
	PolicyEngine: importedEngine,
})

// Grant permissions to the imported policy
role := iam.NewRole(this, jsii.String("PolicyRole"), &RoleProps{
	AssumedBy: iam.NewServicePrincipal(jsii.String("lambda.amazonaws.com")),
})

importedPolicy.GrantRead(role)

Initializer

new PolicyEngine(scope: Construct, id: string, props?: PolicyEngineProps)

python

PolicyEngine(scope: Construct, id: str, props: typing.Optional[PolicyEngineProps] = None)

java

new PolicyEngine(Construct scope, String id, PolicyEngineProps props)

csharp

new PolicyEngine(Construct scope, string id, PolicyEngineProps? props = null)

NewPolicyEngine(Scope Construct, Id *string, Props PolicyEngineProps)

Construct Props

descriptionstringdescriptionstrdescriptionStringDescriptionstringDescription*string= No description#

Optional description for the policy engine.

Maximum 4,096 characters.

kmsKeyIKeykms_keyIKeykmsKeyIKeyKmsKeyIKeyKmsKeyIKey= AWS owned key#

Custom KMS key for encryption.

[disable-awslint:prefer-ref-interface]

policyEngineNamestringpolicy_engine_namestrpolicyEngineNameStringPolicyEngineNamestringPolicyEngineName*string= Auto-generated unique name#

The name of the policy engine.

Valid characters: a-z, A-Z, 0-9, _ (underscore) Must start with a letter, 1-48 characters Pattern: ^[A-Za-z][A-Za-z0-9_]*$

tags{ [key: string]: string }tagstyping.Mapping[str, str]tagsMap<String, String>TagsIDictionary<string, string>Tags*map[string]*string= No tags#

Tags for the policy engine.

Maximum 50 tags.

Properties

descriptionstringdescriptionstrdescriptionStringDescriptionstringDescription*string#

The description of the policy engine.

envResourceEnvironmentenvResourceEnvironmentenvResourceEnvironmentEnvResourceEnvironmentEnvResourceEnvironmentrequired#

The environment this resource belongs to.

notes

For resources that are created and managed in a Stack (those created by creating new class instances like new Role(), new Bucket(), etc.), this is always the same as the environment of the stack they belong to.

For referenced resources (those obtained from referencing methods like Role.fromRoleArn(), Bucket.fromBucketName(), etc.), they might be different than the stack they were imported into.

grantPrincipalIPrincipalgrant_principalIPrincipalgrantPrincipalIPrincipalGrantPrincipalIPrincipalGrantPrincipalIPrincipalrequired#

The principal to grant permissions to.

kmsKeyIKeykms_keyIKeykmsKeyIKeyKmsKeyIKeyKmsKeyIKey#

The KMS key used to encrypt the policy engine.

nodeNodenodeNodenodeNodeNodeNodeNodeNoderequired#

The tree node.

policiesPolicy[]policiestyping.List[Policy]policiesList<Policy>PoliciesPolicy[]Policies*[]Policyrequired#

Get the list of policies added to this policy engine.

Returns an array of Policy constructs that were added using addPolicy(). This allows you to iterate over all policies associated with this engine.

policyEngineArnstringpolicy_engine_arnstrpolicyEngineArnStringPolicyEngineArnstringPolicyEngineArn*stringrequired#

The ARN of the policy engine resource.

policyEngineIdstringpolicy_engine_idstrpolicyEngineIdStringPolicyEngineIdstringPolicyEngineId*stringrequired#

The ID of the policy engine.

policyEngineNamestringpolicy_engine_namestrpolicyEngineNameStringPolicyEngineNamestringPolicyEngineName*stringrequired#

The name of the policy engine.

[disable-awslint:attribute-tag]

policyEngineRefPolicyEngineReferencepolicy_engine_refPolicyEngineReferencepolicyEngineRefPolicyEngineReferencePolicyEngineRefPolicyEngineReferencePolicyEngineRefPolicyEngineReferencerequired#

A reference to this PolicyEngine resource.

PROPERTY_INJECTION_IDstringproperty_injection_idstrPROPERTY_INJECTION_IDStringPROPERTY_INJECTION_IDstringPROPERTY_INJECTION_ID*stringrequiredstatic#

Uniquely identifies this class.

stackStackstackStackstackStackStackStackStackStackrequired#

The stack in which this resource is defined.

tags{ [key: string]: string }tagstyping.Mapping[str, str]tagsMap<String, String>TagsIDictionary<string, string>Tags*map[string]*string= No tags applied#

Tags applied to this policy engine resource.

Methods

addPolicy(id: string, options: AddPolicyOptions): Policydef add_policy(self, id: str, options: AddPolicyOptions) -> Policypublic Policy addPolicy(String id, AddPolicyOptions options)public Policy AddPolicy(string id, AddPolicyOptions options)func AddPolicy(Id *string, Options AddPolicyOptions) Policy#

Add a policy to this policy engine. Convenience method that creates a Policy construct with this engine as the parent.

notes · 2 parameters · returns

Automatic Sequential Chaining: By default, policies are automatically chained sequentially to prevent concurrent creation issues with the AWS Bedrock AgentCore service. Each new policy will depend on the previous policy added to this engine.

This ensures policies are created one at a time, avoiding "Resource stabilization failed" errors that occur with concurrent policy operations.

Parameters

ididididId — - Unique identifier for the policy construct.
optionsoptionsoptionsoptionsOptions — - Options for creating the policy.

Returns: The created Policy construct

applyCrossStackReferenceStrength(strength: ReferenceStrength): voiddef apply_cross_stack_reference_strength(self, strength: ReferenceStrength) -> Nonepublic void applyCrossStackReferenceStrength(ReferenceStrength strength)public void ApplyCrossStackReferenceStrength(ReferenceStrength strength)func ApplyCrossStackReferenceStrength(Strength ReferenceStrength)#

Override the cross-stack reference strength for this resource.

notes · 1 parameter

When set, any cross-stack reference to this resource will use the specified mechanism instead of the global default determined by the @aws-cdk/core:defaultCrossStackReferences context key. This is useful for selectively weakening specific references to avoid the "deadly embrace" problem without changing the app-wide default.

Parameters

strengthstrengthstrengthstrengthStrength — - The reference strength to use for this resource.

applyRemovalPolicy(policy: RemovalPolicy): voiddef apply_removal_policy(self, policy: RemovalPolicy) -> Nonepublic void applyRemovalPolicy(RemovalPolicy policy)public void ApplyRemovalPolicy(RemovalPolicy policy)func ApplyRemovalPolicy(Policy RemovalPolicy)#

Apply the given removal policy to this resource.

notes

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

fromPolicyEngineAttributes(scope: Construct, id: string, attrs: PolicyEngineAttributes): IPolicyEngine

@staticmethod def from_policy_engine_attributes(scope: Construct, id: str, attrs: PolicyEngineAttributes) -> IPolicyEngine

public static IPolicyEngine fromPolicyEngineAttributes(Construct scope, String id, PolicyEngineAttributes attrs)public static IPolicyEngine FromPolicyEngineAttributes(Construct scope, string id, PolicyEngineAttributes attrs)func FromPolicyEngineAttributes(Scope Construct, Id *string, Attrs PolicyEngineAttributes) IPolicyEnginestatic#

Creates a PolicyEngine reference from an existing policy engine's attributes.

3 parameters · returns

Parameters

scopescopescopescopeScope — - The construct scope.
ididididId — - Identifier of the construct.
attrsattrsattrsattrsAttrs — - Attributes of the existing policy engine.

Returns: An IPolicyEngine reference to the existing policy engine

grant(grantee: IGrantable, ...actions: string[]): Grantdef grant(self, grantee: IGrantable, actions: str) -> Grantpublic Grant grant(IGrantable grantee, String actions)public Grant Grant(IGrantable grantee, string actions)func Grant(Grantee IGrantable, Actions *string) Grant#

Grants IAM actions to the IAM Principal.

[disable-awslint:no-grants]

2 parameters · returns

Parameters

granteegranteegranteegranteeGrantee — - The IAM principal to grant permissions to.
actionsactionsactionsactionsActions — - The actions to grant.

Returns: An IAM Grant object representing the granted permissions

grantEvaluate(grantee: IGrantable): Grantdef grant_evaluate(self, grantee: IGrantable) -> Grantpublic Grant grantEvaluate(IGrantable grantee)public Grant GrantEvaluate(IGrantable grantee)func GrantEvaluate(Grantee IGrantable) Grant#

Grants permissions to evaluate policies at runtime (data plane operations).

notes · 1 parameter · returns

This is the primary permission needed by Gateway execution roles to evaluate authorization decisions during agent requests. Grant this to roles that need to call AuthorizeAction or PartiallyAuthorizeActions at runtime.

[disable-awslint:no-grants]

Parameters

granteegranteegranteegranteeGrantee — - The IAM principal to grant evaluation permissions to.

Returns: An IAM Grant object representing the granted permissions

grantEvaluateForGateway(grantee: IGrantable, gateway: IGateway): Grantdef grant_evaluate_for_gateway(self, grantee: IGrantable, gateway: IGateway) -> Grantpublic Grant grantEvaluateForGateway(IGrantable grantee, IGateway gateway)public Grant GrantEvaluateForGateway(IGrantable grantee, IGateway gateway)func GrantEvaluateForGateway(Grantee IGrantable, Gateway IGateway) Grant#

Grants the full set of permissions required for a gateway execution role to use this policy engine, correctly scoped to both the policy engine and gateway ARNs.

Per the AWS docs:

GetPolicyEngine → policy engine ARN only
AuthorizeAction + PartiallyAuthorizeActions → policy engine ARN and gateway ARN

[disable-awslint:no-grants]

2 parameters · returns

Parameters

granteegranteegranteegranteeGrantee — - The IAM principal (gateway execution role) to grant permissions to.
gatewaygatewaygatewaygatewayGateway — - The gateway that will use this policy engine [disable-awslint:prefer-ref-interface].

Returns: A combined IAM Grant representing all granted permissions

grantRead(grantee: IGrantable): Grantdef grant_read(self, grantee: IGrantable) -> Grantpublic Grant grantRead(IGrantable grantee)public Grant GrantRead(IGrantable grantee)func GrantRead(Grantee IGrantable) Grant#

Grants read permissions on the PolicyEngine (data plane).

This grants runtime read access to policy engine configuration. Use this for monitoring, observability, or read-only administrative roles that need to inspect policy engine settings at runtime.

[disable-awslint:no-grants]

1 parameter · returns

Parameters

granteegranteegranteegranteeGrantee — - The IAM principal to grant read permissions to.

Returns: An IAM Grant object representing the granted permissions

isConstruct(x: any): boolean@staticmethod def is_construct(x: Any) -> boolpublic static Boolean isConstruct(Object x)public static bool IsConstruct(object x)func IsConstruct(X interface{}) *boolstatic#

Checks if `x` is a construct.

notes · 1 parameter · returns

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters

xxxxX — Any object.

Returns: true if x is an object created from a class which extends Construct.

isOwnedResource(construct: IConstruct): boolean@staticmethod def is_owned_resource(construct: IConstruct) -> boolpublic static Boolean isOwnedResource(IConstruct construct)public static bool IsOwnedResource(IConstruct construct)func IsOwnedResource(Construct IConstruct) *boolstatic#

Returns true if the construct was created by CDK, and false otherwise.

isResource(construct: IConstruct): boolean@staticmethod def is_resource(construct: IConstruct) -> boolpublic static Boolean isResource(IConstruct construct)public static bool IsResource(IConstruct construct)func IsResource(Construct IConstruct) *boolstatic#

Check whether the given construct is a Resource.

metric(metricName: string, dimensions: { [key: string]: string }, props?: MetricOptions): Metric

def metric(self, metric_name: str, dimensions: typing.Mapping[str, str], props: typing.Optional[MetricOptions] = None) -> Metric

public Metric metric(String metricName, Map<String, String> dimensions, MetricOptions props)public Metric Metric(string metricName, IDictionary<string, string> dimensions, MetricOptions? props = null)func Metric(MetricName *string, Dimensions *map[string]*string, Props MetricOptions) Metric#

Return the given named metric for this policy engine.

By default, the metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

3 parameters

Parameters

metricNamemetric_namemetricNamemetricNameMetricName — The name of the metric.
dimensionsdimensionsdimensionsdimensionsDimensions — Additional dimensions for the metric.
propspropspropspropsProps — Optional metric configuration.

metricAuthorizationLatency(props?: MetricOptions): Metricdef metric_authorization_latency(self, props: typing.Optional[MetricOptions] = None) -> Metricpublic Metric metricAuthorizationLatency(MetricOptions props)public Metric MetricAuthorizationLatency(MetricOptions? props = null)func MetricAuthorizationLatency(Props MetricOptions) Metric#

Return a metric measuring the authorization latency for this policy engine.

This metric represents the time taken to evaluate authorization policies.

1 parameter

Parameters

propspropspropspropsProps — Optional metric configuration.

metricAuthorizations(props?: MetricOptions): Metricdef metric_authorizations(self, props: typing.Optional[MetricOptions] = None) -> Metricpublic Metric metricAuthorizations(MetricOptions props)public Metric MetricAuthorizations(MetricOptions? props = null)func MetricAuthorizations(Props MetricOptions) Metric#

Return a metric containing the total number of authorizations for this policy engine.

This metric tracks all authorization requests processed by the policy engine.

1 parameter

Parameters

propspropspropspropsProps — Optional metric configuration.

metricDeniedRequests(props?: MetricOptions): Metricdef metric_denied_requests(self, props: typing.Optional[MetricOptions] = None) -> Metricpublic Metric metricDeniedRequests(MetricOptions props)public Metric MetricDeniedRequests(MetricOptions? props = null)func MetricDeniedRequests(Props MetricOptions) Metric#

Return a metric containing the number of denied authorization requests for this policy engine.

This metric tracks authorization requests that were explicitly denied by policies.

1 parameter

Parameters

propspropspropspropsProps — Optional metric configuration.

metricErrors(props?: MetricOptions): Metricdef metric_errors(self, props: typing.Optional[MetricOptions] = None) -> Metricpublic Metric metricErrors(MetricOptions props)public Metric MetricErrors(MetricOptions? props = null)func MetricErrors(Props MetricOptions) Metric#

Return a metric containing the number of errors during authorization for this policy engine.

This metric tracks errors encountered during policy evaluation.

1 parameter

Parameters

propspropspropspropsProps — Optional metric configuration.

toString(): stringdef to_string(self, ) -> strpublic String toString()public string ToString()func ToString() *string#

Returns a string representation of this construct.

with(...mixins: IMixin[]): IConstructdef with(self, mixins: IMixin) -> IConstructpublic IConstruct with(IMixin mixins)public IConstruct With(IMixin mixins)func With(Mixins IMixin) IConstruct#

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

PolicyEngine L2 construct ​

Example ​

Initializer ​

Construct Props ​

Properties ​

Methods ​

PolicyEngine L2 construct

Example

Initializer

Construct Props

Properties

Methods