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).
Manage Policies and Policy Engines
Use these operations to manage your Policy Engines and policies.
The Amazon CLI and the Amazon SDKs act on any policy engine in your account. The AgentCore CLI is scoped to a
single AgentCore project: it can delete the engines and policies that project manages, and agentcore status
shows their deployed state, but it has no equivalent for reading or updating a resource it did not create. Use
the Amazon CLI or an SDK for those.
List Policy Engines
View all Policy Engines in your account.
Select one of the following methods:
Example
-
Amazon CLI
-
-
aws bedrock-agentcore-control list-policy-engines
-
Amazon Python SDK (Boto3)
-
-
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.list_policy_engines()
for engine in response['policyEngines']:
print(f"Policy Engine: {engine['name']} (ID: {engine['policyEngineId']})")
print(f"Status: {engine['status']}")
print(f"Created: {engine['createdAt']}")
print(f"ARN: {engine['policyEngineArn']}")
List summaries without decrypting
Alongside ListPolicyEngines and ListPolicies, the service offers summary variants that return identifiers,
names, and status but omit the encrypted content — a policy engine’s summary carries no description, and a
policy’s summary carries no definition.
aws bedrock-agentcore-control list-policy-engine-summaries
aws bedrock-agentcore-control list-policy-summaries \
--policy-engine-id my_policy_engine-a1b2c3d4e5
There are two reasons to prefer them.
-
They work when a customer managed key does not. The full list and get operations verify the key and decrypt
before returning, so they fail while the key is disabled, deleted, or has its grant revoked. The summary
operations touch neither, so they remain the only way to enumerate what exists. See
Key unavailable: you cannot list or read your policies.
-
They are cheaper for inventory. If you only need to know which policies exist and whether they are ACTIVE,
you do not need the statements decrypted.
They are separate IAM actions — bedrock-agentcore:ListPolicyEngineSummaries and
bedrock-agentcore:ListPolicySummaries — so grant them explicitly; see
AgentCore Gateway and Policy in AgentCore IAM Permissions.
Get Policy Engine
Retrieve detailed information about a specific Policy Engine:
Example
-
Amazon CLI
-
-
aws bedrock-agentcore-control get-policy-engine --policy-engine-id my_policy_engine-a1b2c3d4e5
-
Amazon Python SDK (Boto3)
-
-
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.get_policy_engine(
policyEngineId='my_policy_engine-a1b2c3d4e5'
)
print(f"Policy Engine: {response['name']}")
print(f"ID: {response['policyEngineId']}")
print(f"ARN: {response['policyEngineArn']}")
print(f"Status: {response['status']}")
print(f"Created: {response['createdAt']}")
print(f"Updated: {response['updatedAt']}")
List policies in a Policy Engine
View all policies within a specific Policy Engine:
Example
-
Amazon CLI
-
-
aws bedrock-agentcore-control list-policies --policy-engine-id my_policy_engine-a1b2c3d4e5
-
Amazon Python SDK (Boto3)
-
-
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.list_policies(
policyEngineId='my_policy_engine-a1b2c3d4e5'
)
for policy in response['policies']:
print(f"Policy: {policy['name']} (ID: {policy['policyId']})")
print(f"Status: {policy['status']}")
print(f"Description: {policy.get('description', 'No description')}")
print(f"Created: {policy['createdAt']}")
Get Policy
Retrieve detailed information about a specific policy:
Example
-
Amazon CLI
-
-
aws bedrock-agentcore-control get-policy --policy-engine-id my_policy_engine-a1b2c3d4e5 --policy-id my_policy-a1b2c3d4e5
-
Amazon Python SDK (Boto3)
-
-
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.get_policy(
policyId='my_policy-a1b2c3d4e5',
policyEngineId='my_policy_engine-a1b2c3d4e5'
)
print(f"Policy: {response['name']}")
print(f"ID: {response['policyId']}")
print(f"ARN: {response['policyArn']}")
print(f"Status: {response['status']}")
print(f"Created: {response['createdAt']}")
print(f"Updated: {response['updatedAt']}")
print(f"Cedar Statement: {response['definition']['policy']['statement']}")
Update existing policies
UpdatePolicy replaces the policy’s definition outright — there is no partial update, so send the complete
statement you want. Like CreatePolicy, it returns HTTP 202 and validates asynchronously; wait for ACTIVE
rather than treating the response as success.
A statement must constrain the resource, either to a specific gateway with resource == or to the type with
resource is AgentCore::Gateway. An unconstrained resource is rejected at the call with a
ValidationException.
If the updated policy is a temporal policy, or the update adds or removes temporal expressions, updating it invalidates the engine’s active temporal policy sessions. In-flight sessions return an HTTP 409 ConflictException and must be restarted. For more information, see Session invalidation.
Example
-
Amazon CLI
-
-
aws bedrock-agentcore-control update-policy \
--policy-id my_policy-a1b2c3d4e5 \
--policy-engine-id my_policy_engine-a1b2c3d4e5 \
--definition '{
"policy": {
"statement": "permit (principal, action == AgentCore::Action::\"RefundTool___process_refund\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5\");"
}
}'
-
Amazon Python SDK (Boto3)
-
-
import boto3
client = boto3.client('bedrock-agentcore-control')
client.update_policy(
policyId='my_policy-a1b2c3d4e5',
policyEngineId='my_policy_engine-a1b2c3d4e5',
definition={
'policy': {
'statement': (
'permit (principal, '
'action == AgentCore::Action::"RefundTool___process_refund", '
'resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5");'
)
}
}
)
waiter = client.get_waiter('policy_active')
waiter.wait(policyEngineId='my_policy_engine-a1b2c3d4e5', policyId='my_policy-a1b2c3d4e5')
Delete policies
Delete a policy from the Policy Engine.
Example
- AgentCore CLI
-
-
For a policy your AgentCore project manages, remove it from the project and deploy:
agentcore remove policy --name my_policy --engine my_policy_engine --yes
agentcore deploy --yes
agentcore remove only edits the project configuration; the policy is deleted from your account on the next
agentcore deploy.
-
Amazon CLI
-
-
aws bedrock-agentcore-control delete-policy --policy-engine-id my_policy_engine-a1b2c3d4e5 --policy-id my_policy-a1b2c3d4e5
-
Amazon Python SDK (Boto3)
-
-
import boto3
client = boto3.client('bedrock-agentcore-control')
client.delete_policy(policyId='my_policy-a1b2c3d4e5', policyEngineId='my_policy_engine-a1b2c3d4e5')
waiter = client.get_waiter('policy_deleted')
waiter.wait(policyEngineId='my_policy_engine-a1b2c3d4e5', policyId='my_policy-a1b2c3d4e5')
Delete Policy Engine
Delete an entire Policy Engine and all its policies.
-
You cannot delete a policy engine that is currently attached to a gateway. Detach it first by updating the
gateway configuration; see Update existing gateway with Policy Engine.
-
You cannot delete a policy engine that still has policies in it. Delete every policy first, then delete the
engine.
Example
- AgentCore CLI
-
-
For an engine your AgentCore project manages, remove it from the project and deploy:
agentcore remove policy-engine --name my_policy_engine --yes
agentcore deploy --yes
Removing a gateway does not remove the policy engine attached to it; remove the engine separately.
-
Amazon CLI
-
-
aws bedrock-agentcore-control delete-policy-engine --policy-engine-id my_policy_engine-a1b2c3d4e5
-
Amazon Python SDK (Boto3)
-
-
import boto3
client = boto3.client('bedrock-agentcore-control')
client.delete_policy_engine(policyEngineId='my_policy_engine-a1b2c3d4e5')