View a markdown version of this page

Create a policy engine - Amazon Bedrock AgentCore
PrerequisitesCreate a policy engineIdentifiers you need afterwards
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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, ensure you have a gateway setup. For more information, see Building a 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 in a name — use my_policy_engine, not 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.

Amazon CLI

  1. Run the following code in a terminal to create a policy engine using the Amazon 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.

Amazon Python SDK (Boto3)

  1. The following Python code shows how to create a policy engine using the Amazon 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.