How Policies Are Evaluated
Every HYPR AgentPass™ policy has the same shape:
- A condition that decides whether the policy matches
- An action that applies when the condition matches
- A mode that says whether the action is enforced yet
- A phase that says which half of the exchange the rule looks at
This page explains those pieces and how the gateway runs them, so you can predict what a policy will do before you promote it.
What a Rule Can Look At
A condition can test four kinds of detail about the exchange.
| Detail | Attributes | Examples |
|---|---|---|
| The request | request.* | The path and method, the parsed body, the signed-in person, the calling agent and any attached files |
| The reply | response.* | The status code, headers and body, and how long the backend took |
| The connector | connector.* | Which connector handled it and what kind it is. On AWS Bedrock and Microsoft 365 Copilot connectors, also the caller and surface behind the request |
| The conversation | inference.* | On a connector that reaches a model: the newest message, the model's reply, and the tools it is asking to run |
The Attribute Reference lists every attribute, with its type and when it is present.
Action and Mode Are Separate Settings
The action is what the policy does when its condition matches. The mode is whether that action is applied at all.
Action
A policy has one of three actions.
| Action, as shown on the form | On a match in Enforce mode |
|---|---|
ALLOW – Let traffic through | The request continues. The match is recorded, but the outcome is unchanged |
DENY – Block the request | The request stops at the gateway. The agent receives the policy's message |
REQUIRE_APPROVAL – Require human approval | The request is held, and an approval is raised for the agent's supervisor. It continues only if approved |
A matching ALLOW policy does not stop evaluation. If a later policy in priority order also matches and blocks, the request is still blocked. Use ALLOW to record that a rule matched, not as an exception to a block written elsewhere. An ALLOW policy records its matches only in Enforce mode. In Observe mode, it records nothing. To exempt traffic from a block, narrow the block's own condition or its connector scope.
Mode
A policy runs in one of three modes.
| Mode, as shown on the form | Behavior |
|---|---|
DISABLED – Skip evaluation entirely | The policy is not evaluated. Nothing is logged, and nothing is enforced |
OBSERVE – Evaluate and log, do not enforce | The condition is evaluated on every request in scope. Each DENY or REQUIRE_APPROVAL match is recorded as a Would block decision on the connector's Policies tab. Traffic flows unchanged. See Investigating a Policy Decision |
ENFORCE – Apply the action above on every match | The action applies |
The AI wizard always saves a new policy in Observe. The policy form preselects Observe, and you can choose another mode before you save. You change the mode in the Mode column of the policy list. The gateway asks you to confirm, with Change mode of policy "…"? When the new mode is Enforce, it reminds you to check the Observe events or run a backtest first.
The separate Enabled switch on the form turns the whole policy off, whatever its mode. Keeping a policy enabled in Observe is how you record what it would have done. Disabling it removes it from evaluation entirely.
Phase
The Phase field says which half of the exchange the rule looks at.
| Phase, as shown on the form | The rule sees |
|---|---|
Pre-Request (before forwarding) | The request as it arrives: request.*, connector.*, and on a model connector the conversation being sent (inference.* request attributes). Nothing has left the gateway yet |
Post-Response (before returning) | Everything above, plus the reply: response.*, and on a model connector what the model sent back (inference.* reply attributes) |
Blocking on the request is the stronger control, because nothing is forwarded. A rule about what a model proposes, such as a command it wants to run or a file it wants to read, can only be written on the reply, because that proposal is the reply. Governing Inference Traffic explains the choice in depth.
Priority and First Match
The Priority field is a whole number, 1000 by default. Lower numbers are evaluated first.
For each request, the gateway first narrows your policies to the ones that apply: enabled, not disabled, in the current phase, and in scope for the connector and tool. It sorts them by priority, then runs two passes:
- Every Observe policy in that set is evaluated, and each
DENYorREQUIRE_APPROVALmatch is recorded. - Enforce policies are evaluated in priority order, until one matches with
DENYorREQUIRE_APPROVAL. That policy decides the outcome, and evaluation stops. If none matches, the request continues.
The enforce pass stops at the first block or hold, so order matters when two enforcing rules could both match. Give the one whose message you want the agent to see the lower priority number.
A condition that fails to compile, because of a typo or an unbalanced bracket, takes that policy out of evaluation until it is fixed. The form checks the condition when you save, so this mainly affects a policy created outside the console.
If a condition fails while it is being evaluated, for a reason other than a missing attribute, the gateway treats it as a match.
Scoping a Policy
The Connectors field scopes a policy to the connectors you choose. Leave it empty to apply the policy to all of them. Scoping lets you require approval on one provider's traffic while allowing another's. It also keeps a reply-side rule from changing how replies arrive on connectors it was never meant for.
A policy authored with AI on a tool connector can also carry a tool scope: the specific tools on that connector it applies to. It is then evaluated only for calls to those tools. You set the tool scope in the AI wizard when you create the policy. The form shows it, and points you back to the wizard to change it.
You can also state the scope inside the condition itself, with connector.template or connector.name. Doing both works. The field does the scoping, and the guard in the expression makes the intent readable to whoever reviews the rule later.
What a Match Does, by Kind of Traffic
The action is the same word everywhere, but what the agent or user experiences depends on the kind of connector.
| Traffic | DENY | REQUIRE_APPROVAL |
|---|---|---|
| A tool call on an MCP connector | The agent receives a tool error carrying the policy's message. It can read it and change course | The call is held. An approval is raised for the agent's owner. When the gateway cannot attribute the request to anyone, it goes to the policy's Supervisor Email |
| A REST or other HTTP request | The gateway answers with a 403 and the policy's message. Nothing is forwarded | The request is held for approval in the same way |
The request to a model (Pre-Request on an inference connector, reading request.*) | 403 with the message. The conversation is never sent to the provider | Held for approval |
A model's reply, judged by a rule that reads inference.* | Replies stream. The gateway holds only the tool-call block and judges it. On a match, it ends the reply with a short note naming the policy and its message. Text already streamed stays, but the tool call is never delivered, so it never runs | Not available. See Where Require Approval Applies |
A model's reply, judged by a rule that reads only response.* | The whole reply is held until the rule runs, then blocked with the message or released | Held for approval |
| A Microsoft 365 Copilot reply | Copilot replies are always judged whole. On a match, the user sees a blocked notice instead of the answer | Not available. See Where Require Approval Applies |
A DENY or REQUIRE_APPROVAL policy always needs a message, because it is the text the agent or user receives. Write it for the person who will read it.
A blocked agent receives the policy's name and your message, never the condition itself. A refusal therefore does not reveal how the rule is built.
On an inference connector, a matching reply-side rule deliberately shortens the reply. On a Microsoft 365 Copilot connector, any enabled reply-side rule makes replies arrive complete instead of streaming, for every conversation on that connector. Keep such rules in Observe until you have seen what they catch, and scope them to the connector you mean.
Where Require Approval Applies
REQUIRE_APPROVAL needs a person to approve, and a request that can wait. Some traffic has neither.
| Traffic | Require approval |
|---|---|
MCP tool calls, REST connectors, and Pre-Request rules on inference connectors that read request.* | Yes |
Any rule whose condition reads inference.* | No. Inference rules allow or block, and the gateway refuses to enforce REQUIRE_APPROVAL on one. You can save such a rule in Observe, to record where approval would have been required, but not promote it. To keep a person in the loop, write the approval on the tool call the agent makes, or run the rule in Observe and review its matches |
| Requests from a service agent | No human can approve, so the call does not complete. Choose block or allow for these agents, or scope the policy to supervised agents |
| Microsoft 365 Copilot replies | Block or allow |
| Copilot Studio turns and Agent Portal file uploads | No. REQUIRE_APPROVAL blocks the request with the policy's message, and no approval is raised |
An approval goes to the agent's owner, or to the supervisor the gateway resolved for the request. The policy's Supervisor Email is the fallback when the request carries no attributable identity at all. Approving and Denying Agent Actions covers what the supervisor sees, and what each answer does to the agent.
A Rule About a Detail the Gateway Never Learned Never Acts
Many attributes are present only when the gateway could resolve them. For example:
request.user, when someone signed inrequest.files, when a request carries filesconnector.aws.bedrock.user_email, when the developer was namedinference.*, on a connector that reaches a modeldata.*, when something classified the call
When such a detail is missing, a condition that tests it is not a match. The policy does nothing, with no error, and nothing in the Request Log suggests it is idle.
That is the safe direction for the gateway to take, but it affects how you write a block. A DENY written as "the signed-in person is not from my domain" blocks the outsiders it names. It also lets through every request that carried no identity at all.
Write the block so the missing case matches too. Test presence with !has(…), as in !has(request.user) || !request.user.endsWith("@example.com"), or test an attribute that is always present. A guard on one of these attributes also says which traffic the rule governs:
connector.templateorconnector.namerequest.file_countconnector.aws.bedrock.identity_source, on Bedrockconnector.m365.copilot.surface, on Copilot
Then check the rule in Observe mode before you enforce it. The Attribute Reference marks which attributes are always present, and which arrive only when resolved.
Policies and Tool Access by Role
Policies are not the only control on what an agent may do. Controlling MCP Tool Access by Role decides which MCP tools an agent may see and call at all, based on its supervisor's role, before any policy runs.
- Use tool access by role for the standing answer to "may this kind of user's agents use this tool?"
- Use a policy for a rule about a particular call: its arguments, its timing, the person or connector behind it, or a step that should need a human each time.
A policy can also be written against what a tool handles, not what it is called. Classifying the Data Your Tools Handle lets you label your tools and connectors. You can then condition on tool.*, data.*, response.data.* and a connector's data_ceiling. A rule such as "hold anything Restricted for approval" then keeps working as connectors gain and rename tools.
Related
- Policies — the section overview
- Writing a Policy by Hand — the form field by field
- Authoring a Policy with AI — draft a rule from plain English
- Classifying the Data Your Tools Handle — label your tools, then write rules against the label