Policy-as-code tool approvals with @ai-sdk/policy-opa

TL;DR: Install: pnpm add @ai-sdk/policy-opa What it gives you: 1. When approval logic outgrows inline functions, @ai-sdk/policy-opa moves it into Open Policy Agent policies. Same wire flow, reviewable rules.

When approval logic outgrows inline functions, @ai-sdk/policy-opa moves it into Open Policy Agent policies. Same wire flow, reviewable rules.

Install: pnpm add @ai-sdk/policy-opa

What it gives you:

1. Rules live in .rego files, separate from agent setup. They are reviewable artifacts, testable in CI with opa test, and editable without a code deploy when served from a running OPA instance.
2. The package sits on top of the public toolApproval callback. The wire flow is unchanged: tool-approval-request out, tool-approval-response back.
3. The policy input includes messages, the full model and tool-call history for the run. Rules can be history-aware: require approval after N writes, deny a second irreversible action in one conversation, track cumulative spend against a ceiling.

Strong fits (deterministic checks on structured fields):

• scopes, roles, permissions, tenant isolation
• allowlists of tools, hosts, paths
• numeric thresholds: payments above X need approval, token budgets per run
• time windows and environment gates for destructive actions

Weak fits (do not lean on policy alone):

• content-based filtering like toxicity or "bad language". Best-effort, easy to bypass. Use a dedicated moderation step and keep policy for the deterministic gate around it.

Rule of thumb: if you can point at a field in the input object and write an exact check, it belongs in policy. If the rule judges free-form meaning, it does not.

Verify by writing opa tests for the threshold boundaries before wiring the agent, then exercise approve/deny/auto paths end to end.

When to use

You hit exactly this: Policy-as-code tool approvals with @ai-sdk/policy-opa.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

the tool named in the title.

Verified against the live AI SDK docs 2026-09-26. The policy-tool-approvals guide documents @ai-sdk/policy-opa: rules in .rego, CI testing with opa test, editable without redeploy from a running OPA instance, built on the public toolApproval callback with unchanged wire flow, policy input carrying messages and full history, and the deterministic-checks rule of thumb.