AgentCore Policy, in Cedar.

AgentCore Policy is the rule engine yesterday's tip teased — the last component that fires before a tool call ever reaches Lambda, an OpenAPI target, an MCP server, or a Browser session. It sits in front of an AgentCore Gateway, speaks open-source Cedar, and enforces default-deny, forbid-wins authorization on every tools/call.

01The problem Policy in AgentCore exists to solve

The agent loop is non-deterministic by design. The model decides which tool to call, with what arguments, and when. Most of the time that's exactly what you want — but "most of the time" isn't an audit posture, and "the model decided" isn't a control. From the Policy overview: "AI agents can dynamically adapt to solve complex problems… However, this flexibility introduces new security challenges, as agents may inadvertently misinterpret business rules, or act outside their intended authority."

Three failure modes you've probably seen:

• Prompt-injection-as-privilege-escalation. A tool result tells the model to call RefundTool___process_refund with amount: 999999, and it does.
• Identity confusion. The agent invokes a high-blast-radius tool on behalf of a user who shouldn't have been able to reach it directly.
• In-code "guardrails". The team writes if user.role == "admin": in the agent prompt or the tool body, and that check is the only thing standing between a junior user and an irreversible action.

02How Cedar is wired into a Gateway

You need three pieces, in order. From the Core concepts page:

The two attach modes (set on agentcore add policy-engine --attach-mode):

• ENFORCE — every tools/call is intercepted, every policy is evaluated, every denial is returned to the agent as an error.
• MONITOR — same evaluation, but the answer doesn't gate the call. Decisions still log to CloudWatch. This is how you ship Cedar in shadow before flipping it on.

The minimal CLI to wire it up, from the Getting Started:

A small bootstrap pitfall worth knowing: policies that reference a specific gateway ARN in the resource field need a two-phase deploy — first create the gateway, grab the ARN from agentcore status, then write the Cedar file. Cedar does not allow wildcards on the resource.

03Anatomy of a Cedar policy

Every Cedar statement has the same three slots — scope (principal, action, resource), effect (permit or forbid), and an optional condition (when or unless). The canonical refund policy from the Understanding Cedar docs:

Read it left to right: when the principal is an OAuth user named "John", calling the RefundTool___process_refund tool on the refund-gateway Gateway, and the refund amount is under $500, the request is permitted. Any of those clauses fails, the rule doesn't match. If no rule matches, the gateway returns DENY (see §05).

The two principal types you can name in the scope, from the Policy scope page:

• AgentCore::OAuthUser — when the gateway uses OAuth/JWT inbound auth. The principal ID is the JWT sub claim; every other claim (username, scope, role, department, …) is stamped onto the entity as tags and read with principal.getTag("…").
• AgentCore::IamEntity — when the gateway uses AWS_IAM inbound auth. The principal has an id attribute containing the IAM ARN (assumed-role form: arn:aws:sts::<account>:assumed-role/<role>).

Actions are exact-match. There is no wildcard on actions — you either name the tool (AgentCore::Action::"ToolName___operation") or you group tools under a Gateway Target and write the rule against that target (action in AgentCore::Action::"ReadToolsTarget").

04The authorization request the gateway builds

For every tools/call, the Gateway constructs a Cedar request from two inputs — the JWT (or IAM identity) and the MCP tool payload — and hands it to the policy engine. From the Authorization flow doc:

Two things to notice. The tool's input parameters land in context.input.* exactly as the agent submitted them — that's the only way a Cedar rule can react to "what is being requested," which is why the refund-amount condition above is on context.input.amount. And the JWT claims arrive as entity tags, not as nested object access — you reach them through principal.getTag("username"), not principal.username.

05Default-deny, forbid-wins, and why both matter

Cedar's evaluation algorithm, verbatim from the Understanding Cedar page:

1. If any forbid policy matches, the decision is DENY.
2. If no forbid matches and at least one permit matches, the decision is ALLOW.
3. If nothing matches, the decision is DENY (default deny).

Two non-obvious corollaries:

• forbid is not redundant with default-deny. Default-deny only catches the absence of a permit. A forbid rule actively beats a matching permit. That's how you write "all users may view model results, except high-sensitivity ones" without rewriting the permit.
• unless on forbid is not a grant. It only narrows the forbid's scope. The docs are explicit: "A forbid policy can never result in an ALLOW decision." If nothing else matches, the result is still DENY.

When a request is denied, the gateway returns an MCP error result with the text AuthorizeActionException - Tool Execution Denied, including the reason — usually "No policy applies to the request (denied by default)."

06Tool listing is a separate, weaker check

The first thing an MCP client does is call tools/list. The policy engine evaluates that call too — but it can't, by definition, know the input parameters yet. From the Use a Gateway with Policy doc: "A principal is only allowed to see tools in the listing that they would be permitted to call by policy. Because the full context of a tool call is not available during listing, this means a principal is allowed to list a tool if there exists any set of circumstances under which a call to that tool would be permitted."

So tools/list returns the superset — every tool the principal might be allowed to call. The real authorization happens on tools/call, where the gateway has the actual input parameters and can evaluate context.input.* conditions. A tool appearing in the list is not a guarantee that calling it will succeed.

07NL2Cedar — natural-language authoring with automated reasoning

You don't have to write Cedar by hand. The CLI's --generate flag calls the policy authoring service, which takes a sentence and returns a Cedar policy validated against the gateway's auto-generated schema. Example from the NL2Cedar docs: "Allow principal with username 'refund-agent' to process refunds when the refund amount is less than $500." — produces exactly the canonical refund policy in §03.

Three quiet features worth knowing:

• Schema-aware generation. Because the engine's schema knows the tool's argument types, NL2Cedar refuses to write a rule against a field that doesn't exist or compares a string to a number.
• Automated-reasoning checks. Generated policies are inspected for being vacuous (always allows), dead (never allows), or trivially satisfiable before they go live. This is the same Cedar analysis described in Core concepts.
• Geography-bounded inference. Inference for NL2Cedar is routed within your geography (US, EU, APAC). Your data stays in the origination region; only the inference may roam within the geo.

The CLI shape:

The --gateway flag is required for --generate because the service needs the deployed gateway ARN to resolve the schema.

08Limits worth knowing

From the AgentCore Policy Service Quotas table:

• Maximum policy size: 10 KB per individual policy. Not adjustable. Composite rules belong in multiple policies, not in one giant statement.
• Total policy size per resource: 200 KB. Not adjustable.
• Policies per engine: 1,000. Not adjustable.
• Policy engines per account per Region: 1,000. Not adjustable.
• Cedar schema size: 400 KB per policy engine. The schema is the combined schema generated from all tools across all attached gateways. If you exceed it, the fix is to split engines — one per gateway, not one per agent.
• Generated policies per engine: 50,000 over a rolling 7-day window. Sized for CI-driven authoring, not for serving runtime authorization.
• Throttling. CreatePolicyEngine / UpdatePolicyEngine / DeletePolicyEngine / StartPolicyGeneration are 1 TPS. Almost every other API on the list (GetPolicy*, ListPolicy*, CreatePolicy, UpdatePolicy, DeletePolicy) is 5 TPS. These are control-plane limits — they do not cap data-plane authorization throughput, which scales with the Gateway.

Two gotchas not in the quota table:

• Wildcards. Cedar does not support action == AgentCore::Action::*. To group tools, define a Gateway Target and write the rule as action in AgentCore::Action::"TargetName".
• Two-phase deploy for ARN-scoped policies. If your Cedar resource pins a specific gateway ARN (which is the recommended posture in production), you can't ship the policy on the very first deploy. Create the gateway, read back its ARN with agentcore status, then add the policy and redeploy.

09Try it in five minutes

Assuming you already have the AgentCore CLI installed and a project scaffolded:

The response on the over-limit refund is an MCP isError: true with Tool Execution Denied: Tool call not allowed due to policy enforcement. Drop the amount under 1,000 and the same call succeeds.

Tomorrow we'll cover AgentCore Evaluations — three evaluation types (online, on-demand, batch), the built-in LLM-judge evaluators keyed Builtin.*, and the Lambda contract for a custom code-based evaluator that returns {label, value, explanation}.