Technical Guide
OPA Rego for AI Agent Tool Calls: Five Policy Patterns, Tested Before You Ship
Five Rego patterns for AI agent tool calls, each tested in the OPA Playground, plus when to use a behavioral rule or guardrail and what a missing default does.
Published on


OPA Rego for AI Agent Tool Calls: Five Policy Patterns, Tested Before You Ship
By Tahir Mahmood, Co-founder & CTO, OpenBox ยท Last updated 20 November 2026
In brief: In OpenBox, an AI agent governance platform, a Rego policy is a stateless permission check on a single operation, such as one tool call. Use a behavioral rule when the decision depends on earlier actions, and a guardrail when it depends on content. This guide gives five tested Rego patterns and starts with a missing default result. |
Policy, behavioral rule or guardrail: which control fits an AI agent tool call?
Use a Rego policy when the decision depends on a single operation. A Rego policy is policy as code: a file the platform evaluates against each operation. OpenBox (docs.openbox.ai) separates three layers: guardrails validate and transform content, policies make stateless permission checks, and behavioral rules detect multi-step patterns across a session.
As the author's own rule of thumb, ask whether the decision needs the content, the single call or the history.
In the Authorize phase, operations flow through guardrails first, then OPA policy, then behavioral rules, and the pipeline ends in a governance decision. OpenBox's Temporal announcement of 13 July 2026 lists five governance decisions: ALLOW, CONSTRAIN, REQUIRE_APPROVAL, BLOCK and HALT. It describes CONSTRAIN as running an action inside a sandbox and REQUIRE_APPROVAL as pausing it for a human.
The policies page documents CONTINUE and REQUIRE_APPROVAL as example decision values for Rego. This article makes no claim about which other decisions a Rego policy can return. For how blocking, approval and halting differ in practice, see OpenBox's kill switch article.
The table restates the layer guide in the OpenBox Authorize docs.
Layer | Reach for it when | Example from the docs | How it executes |
Guardrails | You need to validate or transform data flowing in or out: content safety, PII, banned terms | Mask credit-card numbers before they reach the LLM | Enabled guardrails run in order, each feeding the next |
Policies | You need a stateless permission check on a single operation: field-level conditions, thresholds, role gates | Block invoice creation above $1,000 without approval | Follows the logic in your Rego file; one policy can hold multiple rules |
Behavioral rules | You need to detect multi-step patterns across a session: sequences, frequencies, combinations | Halt file generation if the agent never queried the database | Checked in priority order; stops at the first rule that triggers a verdict |
The docs list four guardrail types: PII Detection, Content Filtering, Toxicity and Ban Words. Each type can run on input, output or both. For the argument that model-level safeguards alone are not enough, see OpenBox's article on why model guardrails aren't enough, which argues for enforceable governance at the action boundary.
What should the policy input contain for an AI agent tool call?
A policy input should carry the fields your rules read. The OpenBox policies page lists six key input fields: activity_type, activity_output.tool, activity_output.args, event_type, risk_tier and spans. The page ties them to Temporal activities, so check your own SDK's event model before copying a rule.
Field | Set by | What the docs say it carries |
activity_type | Agent-defined | The type of Temporal activity being evaluated. In the demo agent, agent_toolPlanner calls the LLM and returns a structured tool call |
activity_output.tool | Agent-defined | The name of the tool the agent plans to call, for example CreateInvoice |
activity_output.args | Agent-defined | The arguments passed to the tool, defined by your tool schema |
event_type | Platform | The Temporal event type, for example ActivityCompleted |
risk_tier | Platform | The agent's assessed risk tier, 1 to 4, assigned in agent settings |
spans | Platform | Operation-level classifications; each span has a semantic_type such as database_select, file_read or llm_completion |
The guides for LangChain, LangGraph, Mastra, n8n and Deep Agents each have their own Event Model page, so check it before assuming this input shape carries over.
Other OPA-for-agents guides recommend richer inputs. Permit.io's May 2026 post argues that a policy fed only subject, action and resource cannot reason about delegation boundaries, and proposes fields such as the actor, the delegating user, a delegation chain and the parent agent. The OpenBox page calls its six fields the key fields, so treat them as a starting point and confirm what your agent actually sends.
What happens when no Rego rule matches?
Without a default, Rego returns no value at all. When the Playground evaluated an unmatched tool call against a policy with no default, the output was an empty document, {}. The OpenBox policies page recommends a default so a policy always produces a decision. It does not describe what happens when there is none.
The OPA documentation states that without a default definition a rule's document is undefined. Other agent-policy docs make the default an explicit choice. The AI SDK's OPA package treats a call with no matching rule as allow unless the policy defaults to deny, and treats backend errors and unrecognised results as denials. TrueFoundry's AI Gateway docs recommend default deny for OPA guardrails on MCP tool invocations.
In the examples on the OpenBox policies page, the default is CONTINUE. A default of CONTINUE is a decision about everything the policy did not anticipate, so write it deliberately. Pattern 3 below shows a default-closed alternative for tool planning.
Five Rego patterns for AI agent tool calls, tested
The five patterns gate a tool by name, set an approval threshold on an argument, send unlisted tools to approval, restrict operation types by risk tier, and resolve overlapping rules with else. Each is shown as a rule with the inputs it was tested against and the result.
Every pattern below was run in the OPA Rego Playground (OPA v1.22.4) on 20 November 2026, using the input fields from the policies page. Pattern 1 and Pattern 2a come from the OpenBox docs. Pattern 2b and Patterns 3 to 5 are the author's own, and Pattern 4 simplifies the docs' risk-tier example. The Playground runs Rego v1 syntax, and the docs' own examples use the if keyword, so the snippets do too.
Pattern 1: gate a tool by name
This is the docs example. It uses the demo agent's agent_toolPlanner activity and CreateInvoice tool, so substitute your own names. For approval-gate design beyond the rule itself, see OpenBox's human-in-the-loop explainer.
package openbox
default result := {"decision": "CONTINUE", "reason": ""}
result := {"decision": "REQUIRE_APPROVAL", "reason": "Invoice creation requires human approval before proceeding"} if {
input.activity_type == "agent_toolPlanner"
input.activity_output.tool == "CreateInvoice"
}
Test input | Result |
Tool CreateInvoice, Amount 1395.71 | REQUIRE_APPROVAL |
Tool CurrentPTO | CONTINUE |
No activity_output at all | CONTINUE (the default) |
The last row is the one to notice: an input that names no tool falls through to the default.
Pattern 2: approval threshold on an argument
Pattern 2a is the docs example for routing high-value invoices to a human. It uses object.get to read the amount.
package openbox
default result := {"decision": "CONTINUE", "reason": ""}
result := {"decision": "REQUIRE_APPROVAL", "reason": "High-value invoice requires human approval before proceeding"} if {
input.activity_type == "agent_toolPlanner"
input.activity_output.tool == "CreateInvoice"
object.get(input.activity_output.args, "Amount", 0) >= 1000
}
Test input | Result |
Amount 1395.71 | REQUIRE_APPROVAL |
Amount 999.99 | CONTINUE |
Amount 1000 | REQUIRE_APPROVAL |
Amount missing | CONTINUE |
Amount null | CONTINUE |
args missing | CONTINUE |
Amount "99" (a string) | REQUIRE_APPROVAL |
Four rows show the weakness. A missing amount, a null amount and missing arguments all pass, and the string "99" triggers approval as a side effect of the comparison, not by a rule you wrote. The docs advise avoiding assumptions that optional fields are present. Pattern 2b, the author's hardening, sends those cases to approval.
package openbox
default result := {"decision": "CONTINUE", "reason": ""}
is_invoice if {
input.activity_type == "agent_toolPlanner"
input.activity_output.tool == "CreateInvoice"
}
amount := object.get(object.get(input.activity_output, "args", {}), "Amount", null)
needs_review if {
is_invoice
not is_number(amount)
}
needs_review if {
is_invoice
amount >= 1000
}
result := {"decision": "REQUIRE_APPROVAL", "reason": "Invoice amount missing, not a number, or at or above 1000"} if needs_review
Test input | Result |
Amount 1395.71 or 1000 | REQUIRE_APPROVAL |
Amount 999.99 | CONTINUE |
Amount missing, null or a string, or args missing | REQUIRE_APPROVAL |
Tool CurrentPTO | CONTINUE |
Pattern 3: a default-closed allowlist for tool planning
This author-written pattern flips the default for one activity type. Any planned tool not on the allowlist goes to a human. The activity_type condition keeps the closed default to tool planning, and other activities fall through to CONTINUE, as the last row shows.
package openbox
allowed_tools := {"CurrentPTO", "ListFlights"}
default result := {"decision": "CONTINUE", "reason": ""}
tool_allowed if input.activity_output.tool in allowed_tools
result := {"decision": "REQUIRE_APPROVAL", "reason": "Tool is not on the allowlist"} if {
input.activity_type == "agent_toolPlanner"
not tool_allowed
}
Test input | Result |
Tool CurrentPTO (on the allowlist) | CONTINUE |
Tool DeleteAccount (not on it) | REQUIRE_APPROVAL |
No activity_output at all | REQUIRE_APPROVAL |
A different activity type | CONTINUE |
Pattern 4: risk tier and span types
This author-written simplification of the docs' risk-tier example restricts more operation types at tier 4 than at tier 3, as the docs example does. It reads risk_tier and the semantic_type of each span.
package openbox
default result := {"decision": "CONTINUE", "reason": ""}
restricted_types := {
3: {"database_select", "file_read"},
4: {"database_select", "file_read", "llm_completion"},
}
hit if {
some span in input.spans
span.semantic_type in restricted_types[input.risk_tier]
}
result := {"decision": "REQUIRE_APPROVAL", "reason": sprintf("Tier %d: restricted operation type", [input.risk_tier])} if hit
Test input | Result |
Tier 4, span llm_completion | REQUIRE_APPROVAL ("Tier 4: restricted operation type") |
Tier 3, span database_select | REQUIRE_APPROVAL ("Tier 3: restricted operation type") |
Tier 3, span llm_completion | CONTINUE |
Tier 1, span database_select | CONTINUE |
risk_tier given as the string "4" | CONTINUE |
spans missing | CONTINUE |
risk_tier missing | CONTINUE |
The last three rows fall through to CONTINUE. If a tier can arrive as a string or not at all in your setup, add a rule for that case, as Pattern 2b does for amounts.
Pattern 5: resolve overlapping rules with else
When two complete rules match the same input with different values, OPA reports an error. In the Playground, an invoice of 1500 from a tier 4 agent, matched by one rule on amount and another on tier with different reasons, returned eval_conflict_error: rule data.openbox.result produced conflicting values. This author-written version gives the rules an explicit order, with the final else acting as the default.
package openbox
result := {"decision": "REQUIRE_APPROVAL", "reason": "High-value invoice"} if {
input.activity_output.args.Amount >= 1000
} else := {"decision": "REQUIRE_APPROVAL", "reason": "Agent is in risk tier 3 or 4"} if {
input.risk_tier >= 3
} else := {"decision": "CONTINUE", "reason": ""}
Test input | Result |
Amount 1500, tier 4 | REQUIRE_APPROVAL ("High-value invoice") |
No amount, tier 3 | REQUIRE_APPROVAL ("Agent is in risk tier 3 or 4") |
No amount, tier 1 | CONTINUE |
The OpenBox Authorize page says multiple rules can exist within a single policy, which is where overlaps arise.
How do I test a Rego policy before it reaches production?
Test it in the OPA Rego Playground first, as the OpenBox policies page recommends, then paste it into the Policy Editor. For each rule, the author's suggested test matrix has four inputs:
โข A match: the input the rule exists for.
โข A near miss: the same tool with a value just under the threshold, such as 999.99 against 1000.
โข A missing field: no args, no Amount, no spans.
โข A wrong type: a string where a number is expected.
If you keep policies in version control, OPA's test runner runs rules prefixed test_ with opa test. The AI SDK docs and Permit.io both recommend it for agent policies, and the OpenBox policies page recommends the Playground without mentioning opa test.
When does a stateless Rego policy need a behavioral rule instead?
When the decision depends on what the agent already did. The OpenBox policies page states that policies do not track prior actions or session history. Behavioral rules do: each pairs a trigger with required prior states, and the docs' sample halts a file write if no database query came before it.
Fragmentation is the case that matters. OpenBox's reversibility article argues that a policy engine evaluating each call in isolation cannot detect an irreversible action split across individually permitted calls. As a hypothetical, ten invoices of 999.99 each pass Pattern 2, because each is judged alone. The docs assign sequences, frequencies and combinations to behavioral rules.
Both layers can apply to one call. Policies run before behavioral rules in the Authorize pipeline, so a call can pass the Rego check and still meet a behavioral rule. OpenBox's article on chained approved steps covers an agent breaching a system by chaining actions that were each approved, and its piece on task splitting and re-prompting covers per-action governance.
What should I ship first when writing OPA Rego for AI agent tool calls?
Ship an explicit default and a missing-field rule before any threshold. In the tests above, the unmatched call and the missing argument were the cases that passed unnoticed, and each took one extra rule to close. Then move anything that needs history to a behavioral rule, and anything that needs content to a guardrail.
OpenBox, an AI agent governance platform, documents guardrails, policies and behavioral rules under the Authorize phase of its Trust Lifecycle, and its complete guide to AI agent governance covers the wider programme. For related controls, see OpenBox on structural guardrails, pre-flight LLM routing controls and what an LLM gateway can't see.
Frequently asked questions
What does my agent code see when a policy returns REQUIRE_APPROVAL?
In the OpenBox Temporal Python plugin, governance decisions surface as Temporal ApplicationError exceptions. REQUIRE_APPROVAL surfaces as ApprovalPending, which is retryable, so the plugin polls for an approval decision on each retry. A rejection surfaces as ApprovalRejected and a timeout as ApprovalExpired, and neither is retryable.
Can one policy hold multiple Rego rules?
Yes. OpenBox's Authorize page says policies execute based on the logic in your Rego file and that multiple rules can exist within a single policy. Rules that match the same input with different results cause an evaluation conflict in OPA, as Pattern 5 shows, so give overlapping rules an explicit order with else.
Does the documented policy input shape apply to every OpenBox SDK?
The documented fields refer to Temporal activities, so the policies page does not establish that the same shape applies to every SDK. The LangChain, LangGraph, Mastra, n8n and Deep Agents guides each have an Event Model page. Check the page for your SDK before copying a rule.
Sources |
OpenBox. Policies. docs.openbox.ai. https://docs.openbox.ai/trust-lifecycle/authorize/policies. Accessed 20 November 2026. OpenBox. Behavioral Rules. docs.openbox.ai. https://docs.openbox.ai/trust-lifecycle/authorize/behaviors. Accessed 20 November 2026. OpenBox. Guardrails. docs.openbox.ai. https://docs.openbox.ai/trust-lifecycle/authorize/guardrails. Accessed 20 November 2026. OpenBox. Authorize (Phase 2). docs.openbox.ai. https://docs.openbox.ai/trust-lifecycle/authorize. Accessed 20 November 2026. OpenBox. Error Handling, Temporal Plugin (Python). docs.openbox.ai. https://docs.openbox.ai/developer-guide/temporal-python/error-handling. Accessed 20 November 2026. OpenBox. Event Model pages: LangChain, LangGraph, Mastra, n8n, Deep Agents. docs.openbox.ai. https://docs.openbox.ai/developer-guide/langchain/event-model. Accessed 20 November 2026. OpenBox. As Enterprises Move AI Agents Into Production, OpenBox AI and Temporal Introduce Runtime Governance for Long-Running Agents, 13 July 2026. https://www.openbox.ai/blog/temporal-and-ai-agent-governance. Accessed 20 November 2026. OpenBox. Reversibility Policy Primitive, 26 June 2026. https://www.openbox.ai/blog/reversibility-policy-primitive. Accessed 20 November 2026. OpenBox. Blog index (article descriptions), openbox.ai/blog. https://www.openbox.ai/blog. Accessed 20 November 2026. Open Policy Agent. Policy Language (default keyword, conflicting rules). https://www.openpolicyagent.org/docs/policy-language. Accessed 20 November 2026. Open Policy Agent. Policy Testing (opa test). https://www.openpolicyagent.org/docs/policy-testing. Accessed 20 November 2026. Open Policy Agent. Rego Playground, OPA v1.22.4, used for all tests. https://play.openpolicyagent.org/. Accessed 20 November 2026. AI SDK. Policy-Based Tool Approvals. ai-sdk.dev. https://ai-sdk.dev/docs/agents/policy-tool-approvals. Accessed 20 November 2026. TrueFoundry. OPA Guardrails, AI Gateway documentation. https://www.truefoundry.com/docs/ai-gateway/opa-guardrails. Accessed 20 November 2026. Permit.io. OPA for Protecting AI Agents and Agentic Stacks (Eli Moshkovich), 24 May 2026. https://www.permit.io/blog/opa-for-protecting-ai-agents-and-agentic-stacks. Accessed 20 November 2026. |

