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
• Conditions — criteria that determine when the policy applies (action type, parameter values, agent identity, risk context)
• An effect — what happens when the conditions match (allow, block, require approval, or allow with alert)

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 all applicable policies:

1. Koladr receives the action request with its type, parameters, and context
2. All active policies are checked against the request
3. Matching policies are evaluated in priority order
4. The most restrictive matching effect wins
5. The result is returned to the agent

If no policies match, the default behavior is to allow the action. This means you only need to write policies for the cases where you want to restrict or review actions.

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 "blocked" status with 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 "pending_approval" status.

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.

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 based on amounts, counts, or other quantifiable parameters.
• Consider the agent. A well-tested production agent may deserve more autonomy than a newly deployed one. You can scope policies to specific agents.
• Layer your policies. Use a combination of broad default policies and narrow exception policies to cover your full action space.

Example Policies

Refunds over $50 require approval

Low-confidence external email is blocked

Sensitive actions require operator review

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
4. Allow is the default

This means you can safely create broad "allow" policies alongside narrow "block" policies without worrying about conflicts — the stricter rule always wins.