Write a policy

Your policy decides, for every call an agent makes, whether it runs, waits for a person, or is refused. This page shows how to edit it in the console and walks through the rules most organizations write first.

For every field and operator, see Policy format.

How the editor works#

Open Policies. Each environment has its own policy; the page shows the one for the environment chosen in the sidebar. Admins can edit it. Auditors can read it and try it.

The page shows the version in force as readable rules, numbered in the order they are checked. Each rule shows its name, the tools and agents it covers by name, its conditions, and its effect. The list ends with Otherwise: Deny. Rules are checked from top to bottom, the first rule that matches decides, and a call that no rule matches is denied. If the environment has no policy yet, every agent call is denied.

To change the rules:

Every save creates a new version; nothing is overwritten. Gateways apply the new version on their next sync, within about 15 seconds. The Versions list beside the rules shows every version with the time it was saved. Click an older version to read it. It's read-only. Turn on Compare with the version in force to list what changed between that version and the one in force. There's no button to restore an older version. To go back to one, compare it with the version in force, undo those differences in the editor, and save. That creates a new version.

A rule card#

To remove a tool or agent, click the × on its chip.

Click Add condition to add a condition. Each condition has:

• Argument: one of the arguments of the chosen tools. The list only offers arguments that every chosen tool has. With no tools chosen, there's no list, and you type the argument's path, for example max_total.
• Item no.: for an argument inside a list, such as the quantity of an order line, which item to check. 1 is the first item.
• Is: for numbers, is, is one of, >, ≥, < or ≤. For text, is or is one of.
• Value: the value to compare with. For is one of, separate the values with commas. For a yes/no argument, choose yes or no. For an argument with a fixed list of values, choose one from the list.

Add rule offers four starting points:

To move a rule, drag the handle on the left of its card. With the keyboard, focus the handle, press Space, move the card with the arrow keys, and press Space again. You can also open the card's ⋯ menu and choose Move up or Move down. Remove rule is in the same menu. Otherwise: Deny always stays last.

Allow reads#

Most agents need to look things up. Reads don't change anything, so you usually allow them outright:

Ask for approval above an amount#

Let the purchasing agent place small orders alone, and send larger ones to an approver. You need two rules, and the narrow one goes first:

Add rule → Needs approval above an amount gives you most of the first rule. Check that the tool is "Create purchase order" and the argument is max_total.

An order with max_total of 1000 or less skips the first rule and is allowed by the second. An order above 1000 matches the first rule and waits for an approver. The comparison is exact decimal arithmetic, so 1000.01 needs approval.

Deny a dangerous operation#

A tool you've enabled can still be off-limits to agents. Click Add rule → Block a tool, name the rule no-cancelling, and choose "Cancel purchase order" under Tools. A rule that denies refuses the call and hides the tool from agents.

You'd get the same result by leaving the tool out of every rule, because anything unmatched is denied. An explicit deny shows the intent, and the agent's error names the rule.

A rule for one agent#

To write a rule for one agent, choose that agent under Agents. For example, to let only the purchasing agent create purchase orders, choose "Create purchase order" under Tools and the purchasing agent under Agents, and set Then to Allow.

The editor shows agents by name, but the rule keeps the agent's id, so renaming an agent doesn't change what it may do. If you delete an agent, rules that name it show the note "Unknown agent".

Your customers' agents are listed under Agents once they have registered. An agent that registers again is a new agent, so choose it again.

Let the customer approve#

When customers' agents use your service, a call can wait for the customer's own confirmation instead of your staff's. Set Then to Needs approval, then choose Who confirms:

A customer rule only works for outside agents. If one of your own agents matches it, the call is denied with customer_confirmation_unavailable, because there is no customer to ask. If your own agents use the same tool, put a rule for them above the customer rule, with your agents chosen under Agents. See Your customers' agents.

Order matters#

The first matching rule decides, so a broad rule placed early hides narrower rules below it. Take the amount example in the wrong order:

Here orders matches every order, so large-orders is never reached, and large orders would run without approval. The editor shows this as an error under large-orders: "Never applies: rule "orders" comes first and already covers everything this rule does. Move this rule above it, or remove it." Drag large-orders above orders to fix it.

A rule can also be hidden for only some calls. Say rule 1, purchasing-orders, allows "Create purchase order" for the purchasing agent only, and rule 2, large-orders, asks for approval above 1000 for any agent. For the purchasing agent, rule 1 decides first, so its large orders run without approval. The editor shows a warning under large-orders: "Partly hidden: rule "purchasing-orders" comes first and decides for Create purchase order." Move large-orders up, unless that's what you meant.

Only an earlier rule without conditions can hide a later one. A rule with conditions decides only the calls its conditions hold for, and every other call goes on to the next rule.

As a habit, order rules from narrow to broad: rules for one agent, then rules with conditions, then the general rules for a tool.

Conditions fail closed#

A condition can't always be checked: the argument may be missing, or a number comparison may meet a value that isn't a number. When that happens, the rule is treated in the safe direction:

So in the amount example, an order that arrives without max_total needs approval rather than running. A rule that allows never lets a call through on a condition it couldn't check. The editor reminds you of this under every allow rule with conditions.

The same applies when a condition names an argument that one of the rule's tools doesn't have, for example after you add a second tool to a rule that already has a condition. The note under the rule says what happens: a rule that allows never applies to that tool's calls, and a rule that denies or needs approval always applies to them.

Notes under a rule#

The editor checks the rules as you edit and shows notes under each card. Errors stop you from saving. Warnings and hints don't.

Try it before you save#

The Try it panel beside the editor checks a sample call against your unsaved changes. Nothing runs, nothing is saved, and nothing is recorded.

The result shows:

• The decision, such as Needs approval, and the rule that made it: "by rule large-orders", or "no rule matched (default deny)".
• Who confirms, when the customer has to.
• Whether the agent would even see the tool in its list, and whether the tool is switched off or the agent is stopped, which refuses the call anyway.
• Each rule in order, up to the one that decided, marked Skipped or Decides, with the reason. For example, for an order of 500: max_total is "500": "max_total > 1000" doesn't hold. A condition that couldn't be checked shows Skipped (fail closed) on a rule that allows, and Decides (fail closed) on a rule that denies or needs approval.

If the arguments don't fit the tool, the panel lists the errors the Gateway would answer with. The Gateway refuses such a call before the policy is asked.

Try it is also on the Policies page when you aren't editing. There it checks the version in force, so auditors can use it too.

Review and save#

Review and save is turned off while any rule has an error. Click it to open Review changes, which compares your rules with the version in force, rule by rule:

• Added and Removed rules, in words.
• Changed rules, field by field. For example, Conditions: max_total > 1000 → max_total > 5000.
• Moved rules, with their old and new positions.

If there are warnings, the dialog says how many. Click Back to editing to change something, or Save as version N to save.

If requests are waiting, the console tells you how many before saving. Click Save and cancel waiting requests to save anyway.

To stop editing without saving, click Cancel: at the top of the page before you change anything, on the bar at the bottom after. If you've changed anything, the console asks before discarding your changes. Your browser also warns you if you try to leave the page with unsaved changes.

Prefer JSON?#

The JSON tab shows the same rules as a JSON document. Edits there update the rules, and the other way round. If the JSON isn't valid, the tab says what's wrong, and you have to fix it before you can go back to Rules or click Review and save. For example, the amount rules look like this:

{
  "rules": [
    {
      "id": "large-orders",
      "match": {
        "tools": ["erp.purchase_orders.create"],
        "args": [{ "path": "max_total", "op": "gt", "value": 1000 }]
      },
      "effect": "require_approval"
    },
    { "id": "orders", "match": { "tools": ["erp.purchase_orders.create"] }, "effect": "allow" }
  ]
}

In JSON, tools and agents are named by id, not by name. Tool ids are listed on Tools & agents → Tools, and agent ids on Tools & agents → Agents. For every field and operator, see Policy format.

Related#

• Policies explains the model behind the rules.
• Policy format lists every field, operator and validation error.
• Decide approvals shows what approvers see when a rule asks for approval.

Still stuck? Contact support from the console.