View a markdown version of this page

Create a policy engine - Amazon Bedrock AgentCore
PrerequisitesCreate a policy engineIdentifiers you need afterwards

Create a 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.

Prerequisites

Before creating a policy engine, set up a gateway. For more information, see Set up an Amazon Bedrock AgentCore gateway.

Create a policy engine

The following shows how to create a policy engine.

A policy engine name must match [A-Za-z][A-Za-z0-9_]* and be at most 48 characters. It starts with a letter, and after that only letters, digits, and underscores are allowed. Hyphens are not valid, so use my_policy_engine rather than my-policy-engine. The same rule applies to policy names.

Example
AgentCore CLI

  1. In an AgentCore project, add a policy engine to the project configuration:

    agentcore add policy-engine \
  --name my_policy_engine \
  --description "My Policy Engine" \
  --attach-to-gateways my-gateway \
  --attach-mode LOG_ONLY

  2. Deploy the project to create it in your account:

    agentcore deploy --yes

    agentcore add only records the engine in agentcore/agentcore.json; agentcore deploy is what creates it. The deploy output includes the engine ID and ARN. --attach-to-gateways and --attach-mode attach the engine to a gateway in the same step — start with LOG_ONLY so an engine with no policies does not deny live traffic. To encrypt the engine with your own KMS key, add --encryption-key-arn; see Customize your policy engine’s encryption.

AWS CLI

  1. Run the following code in a terminal to create a policy engine using the AWS CLI:

    aws bedrock-agentcore-control create-policy-engine \
  --name my_policy_engine \
  --description "My Policy Engine"

    The response contains both policyEngineId and policyEngineArn. Keep both — they are used in different places, as described in Identifiers you need afterwards.

AWS Python SDK (Boto3)

  1. The following Python code shows how to create a policy engine using the AWS Python SDK (Boto3):

    import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_policy_engine(
    name='my_policy_engine',
    description='My Policy Engine'
)

print(f"Policy Engine ID: {response['policyEngineId']}")
print(f"Policy Engine ARN: {response['policyEngineArn']}")

Identifiers you need afterwards

Creating an engine returns two identifiers, and they are not interchangeable:

policyEngineId

Used by every policy operation — CreatePolicy, ListPolicies, UpdatePolicy, DeletePolicy — and by --engine in the AgentCore CLI. It looks like my_policy_engine-a1b2c3d4e5: your name, plus a generated ten-character suffix. Passing an ARN where an ID is expected is rejected as a validation error.

policyEngineArn

Used to attach the engine to a gateway, as policyEngineConfiguration.arn on CreateGateway or UpdateGateway, alongside a mode of LOG_ONLY or ENFORCE. The AgentCore CLI resolves this for you when you pass --attach-to-gateways.

For more information about creating policies, see Create a policy. For attaching an engine and switching modes, see Policy enforcement modes.