class PolicyEngine (construct) 🔹

Language	Type name
.NET	Amazon.CDK.AWS.Bedrock.Agentcore.Alpha.PolicyEngine
Go	github.com/aws/aws-cdk-go/awsbedrockagentcorealpha/v2#PolicyEngine
Java	software.amazon.awscdk.services.bedrock.agentcore.alpha.PolicyEngine
Python	aws_cdk.aws_bedrock_agentcore_alpha.PolicyEngine
TypeScript (source)	@aws-cdk/aws-bedrock-agentcore-alpha » PolicyEngine

Implements IConstruct, IDependable, IResource, IEnvironmentAware, IPolicyEngine, IPolicyEngineRef, IGrantable

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.

See also: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-engine.html

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

Initializer

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

Parameters

• scope Construct
• id string
• props PolicyEngineProps

Construct Props

Name	Type	Description
description?🔹	string	Optional description for the policy engine.
kmsKey?🔹	IKey	Custom KMS key for encryption.
policyEngineName?🔹	string	The name of the policy engine.
tags?🔹	{ [string]: string }	Tags for the policy engine.

---

description?🔹

Type: string (optional, default: No description)

Optional description for the policy engine.

Maximum 4,096 characters.

---

kmsKey?🔹

Type: IKey (optional, default: AWS owned key)

Custom KMS key for encryption.

[disable-awslint:prefer-ref-interface]

---

policyEngineName?🔹

Type: string (optional, default: 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?🔹

Type: { [string]: string } (optional, default: No tags)

Tags for the policy engine.

Maximum 50 tags.

Properties

Name	Type	Description
env🔹	ResourceEnvironment	The environment this resource belongs to.
grantPrincipal🔹	IPrincipal	The principal to grant permissions to.
node🔹	Node	The tree node.
policies🔹	Policy[]	Get the list of policies added to this policy engine.
policyEngineArn🔹	string	The ARN of the policy engine resource.
policyEngineId🔹	string	The ID of the policy engine.
policyEngineName🔹	string	The name of the policy engine.
policyEngineRef🔹	PolicyEngineReference	A reference to this PolicyEngine resource.
stack🔹	Stack	The stack in which this resource is defined.
description?🔹	string	The description of the policy engine.
kmsKey?🔹	IKey	The KMS key used to encrypt the policy engine.
tags?🔹	{ [string]: string }	Tags applied to this policy engine resource.
static PROPERTY_INJECTION_ID🔹	string	Uniquely identifies this class.

---

env🔹

Type: ResourceEnvironment

The environment this resource belongs to.

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.

---

grantPrincipal🔹

Type: IPrincipal

The principal to grant permissions to.

---

node🔹

Type: Node

The tree node.

---

policies🔹

Type: Policy[]

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.

---

policyEngineArn🔹

Type: string

The ARN of the policy engine resource.

---

policyEngineId🔹

Type: string

The ID of the policy engine.

---

policyEngineName🔹

Type: string

The name of the policy engine.

[disable-awslint:attribute-tag]

---

policyEngineRef🔹

Type: PolicyEngineReference

A reference to this PolicyEngine resource.

---

stack🔹

Type: Stack

The stack in which this resource is defined.

---

description?🔹

Type: string (optional)

The description of the policy engine.

---

kmsKey?🔹

Type: IKey (optional)

The KMS key used to encrypt the policy engine.

---

tags?🔹

Type: { [string]: string } (optional, default: No tags applied)

Tags applied to this policy engine resource.

---

static PROPERTY_INJECTION_ID🔹

Type: string

Uniquely identifies this class.

Methods

Name	Description
addPolicy(id, options)🔹	Add a policy to this policy engine. Convenience method that creates a Policy construct with this engine as the parent.
applyRemovalPolicy(policy)🔹	Apply the given removal policy to this resource.
grant(grantee, ...actions)🔹	Grants IAM actions to the IAM Principal.
grantEvaluate(grantee)🔹	Grants permissions to evaluate policies at runtime (data plane operations).
grantEvaluateForGateway(grantee, gateway)🔹	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.
grantRead(grantee)🔹	Grants read permissions on the PolicyEngine (data plane).
metric(metricName, dimensions, props?)🔹	Return the given named metric for this policy engine.
metricAuthorizationLatency(props?)🔹	Return a metric measuring the authorization latency for this policy engine.
metricAuthorizations(props?)🔹	Return a metric containing the total number of authorizations for this policy engine.
metricDeniedRequests(props?)🔹	Return a metric containing the number of denied authorization requests for this policy engine.
metricErrors(props?)🔹	Return a metric containing the number of errors during authorization for this policy engine.
toString()🔹	Returns a string representation of this construct.
with(...mixins)🔹	Applies one or more mixins to this construct.
static fromPolicyEngineAttributes(scope, id, attrs)🔹	Creates a PolicyEngine reference from an existing policy engine's attributes.

---

addPolicy(id, options)🔹

public addPolicy(id: string, options: AddPolicyOptions): Policy

Parameters

• id string — - Unique identifier for the policy construct.
• options AddPolicyOptions — - Options for creating the policy.

Returns

• Policy

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

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.

---

applyRemovalPolicy(policy)🔹

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

• policy RemovalPolicy

Apply the given removal policy to this resource.

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

---

grant(grantee, ...actions)🔹

public grant(grantee: IGrantable, ...actions: string[]): Grant

Parameters

• grantee IGrantable — - The IAM principal to grant permissions to.
• actions string — - The actions to grant.

Returns

• Grant

Grants IAM actions to the IAM Principal.

[disable-awslint:no-grants]

---

grantEvaluate(grantee)🔹

public grantEvaluate(grantee: IGrantable): Grant

Parameters

• grantee IGrantable — - The IAM principal to grant evaluation permissions to.

Returns

• Grant

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

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]

---

grantEvaluateForGateway(grantee, gateway)🔹

public grantEvaluateForGateway(grantee: IGrantable, gateway: IGateway): Grant

Parameters

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

Returns

• 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]

---

grantRead(grantee)🔹

public grantRead(grantee: IGrantable): Grant

Parameters

• grantee IGrantable — - The IAM principal to grant read permissions to.

Returns

• 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]

---

metric(metricName, dimensions, props?)🔹

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

Parameters

• metricName string — The name of the metric.
• dimensions { [string]: string } — Additional dimensions for the metric.
• props MetricOptions — Optional metric configuration.

Returns

• 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.

---

metricAuthorizationLatency(props?)🔹

public metricAuthorizationLatency(props?: MetricOptions): Metric

Parameters

• props MetricOptions — Optional metric configuration.

Returns

• Metric

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

This metric represents the time taken to evaluate authorization policies.

---

metricAuthorizations(props?)🔹

public metricAuthorizations(props?: MetricOptions): Metric

Parameters

• props MetricOptions — Optional metric configuration.

Returns

• 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.

---

metricDeniedRequests(props?)🔹

public metricDeniedRequests(props?: MetricOptions): Metric

Parameters

• props MetricOptions — Optional metric configuration.

Returns

• 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.

---

metricErrors(props?)🔹

public metricErrors(props?: MetricOptions): Metric

Parameters

• props MetricOptions — Optional metric configuration.

Returns

• Metric

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

This metric tracks errors encountered during policy evaluation.

---

toString()🔹

public toString(): string

Returns

• string

Returns a string representation of this construct.

---

with(...mixins)🔹

public with(...mixins: IMixin[]): IConstruct

Parameters

• mixins IMixin

Returns

• 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.

---

static fromPolicyEngineAttributes(scope, id, attrs)🔹

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

Parameters

• scope Construct — - The construct scope.
• id string — - Identifier of the construct.
• attrs PolicyEngineAttributes — - Attributes of the existing policy engine.

Returns

• IPolicyEngine

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