Policies

Policies are the rules that govern what your agents can and cannot do. They evaluate every action request and determine the outcome: allow, block, require approval, or allow with alert.

What Policies Do

A policy is a rule that Koladr evaluates when an agent requests an action. Each policy has:

• A name: descriptive label for the rule
• An action type: which agent action this policy applies to (e.g. refund.create, email.send)
• Conditions: a list of { field, operator, value } checks evaluated against the request payload and evidence
• An effect: what happens when every condition matches (allow, block, require approval, or allow with alert)
• A priority: tie-breaker when multiple policies match

Policies let you encode your organization's risk tolerance directly into the system. Instead of trusting every agent action blindly, you define explicit rules for how different types of actions should be handled.

How Evaluation Works

When an agent calls requestAction(), Koladr runs the action through every active policy registered for that action type:

1. Koladr loads all active policies whose action_type matches the request
2. Each policy is evaluated by checking every condition against the request context (payload, evidence, provider, resource)
3. A policy matches only when all of its conditions are true
4. Among matching policies, the most restrictive effect wins (block > require approval > allow with alert > allow)
5. If no policy matches, the workspace's default effect applies and the fall-through is recorded as a policy_default_applied event in the run timeline

Policy Effects

Allow

The action proceeds immediately without any human intervention. Use this for low-risk, well-understood actions that your agents should be able to perform autonomously.

Block

The action is stopped and cannot execute. The agent receives a decision of blockwith the policy's reason. Use this for actions that should never be performed, or for categories of actions that are not yet supported.

Require Approval

The action is paused and placed in the approval queue. A designated approver must review the full context and approve or reject the action before it can proceed. The agent receives a decision of require_approval along with an approvalRequestId it can use to poll for resolution.

Allow with Alert

The action proceeds immediately, but an alert is created in the dashboard. Use this for actions that are acceptable but worth monitoring, for example when you want visibility without friction.

Condition Fields

Conditions reference dot-paths on the request context. The paths Koladr exposes to the policy engine are:

Supported operators are eq, neq, gt, gte, lt, lte, in, not_in, contains, and exists. The dashboard's condition builder picks the right input control for each operator, but you can also paste raw JSON in the policies form.

Designing Policies

Effective policy design follows a few principles:

• Start restrictive, then loosen. Begin by requiring approval for most action types. As you observe patterns and build confidence, move low-risk actions to auto-allow.
• Use thresholds. Many actions are safe below a certain threshold (e.g. refunds under $50). Set conditions on quantitative payload.* fields like payload.amount or evidence.confidence to draw that line.
• Layer broad and narrow.Use a low-priority broad "require approval" policy as a safety net and higher-priority narrow policies for known-safe paths. The most restrictive matching effect wins regardless of priority.
• Test before saving. The policy form has a built-in Test against sample payload panel — paste a realistic request and see exactly which conditions match before the rule goes live.

Example Policies

Refunds over $50 require approval

Low-confidence external email is blocked

Sensitive CRM updates require admin approval

Policy Ordering and Conflicts

When multiple policies match an action, the most restrictive effect takes precedence:

1. Block overrides everything
2. Require approval overrides allow and allow with alert
3. Allow with alert overrides allow

When nopolicy matches, the workspace default applies (require approval out of the box). This means you can safely create broad "allow" policies alongside narrow "block" policies without worrying about conflicts — the stricter rule always wins, and ungoverned traffic still surfaces to a human by default.