The Agent Policy Matrix: Mapping Roles, Tools and Permissions for Non-Human Users

Permissions for agents fail when they are scattered across prompts, code and vendor settings. A policy matrix is a design pattern that puts them in one table that engineers, admins and auditors can all read.

The shape of the matrix

Rows are agent roles. Columns are actions on object types. In the fullest version of the pattern, cells contain one of three values: allow, hold for human review, or deny.

Role	Read company	Create note	Create task	Update person	Update deal stage	Delete
Analyst	allow	deny	deny	deny	deny	deny
Assistant	allow	allow	allow	hold	hold	deny
Operator	allow	allow	allow	allow	hold	hold

This is an illustrative example of the pattern.

What AI PRO CRM does today

AI PRO CRM uses a fixed, simpler model rather than a configurable matrix: three agent presets, four human roles (Owner, Admin, Member, Viewer), and no policy rules or review queue. Analyst agents are read-only. Assistant agents can also add an internal note to an existing company; Operator is currently the same. No agent can create tasks, update people, move deal stages or delete anything. Each agent has a daily cap on successful writes, set by your plan.

Rules for a maintainable matrix

Roles are few. Three or four is plenty. If you need a fifth, ask whether an existing role with a narrower set of tools would do.

Deny is the default. Any cell you have not thought about is deny. Agents discover new actions all the time; the matrix should not silently permit them.

Hold is the workhorse. In systems that support human review, most interesting cells start as held and move to allow as evidence accumulates.

Sensitive fields get their own column. Deal value, billing details and anything marked personal data are often governed separately from the object they live on.

Layering with role ceilings

A matrix works best inside a role ceiling. If the Analyst role's ceiling is read-only, no matrix edit can grant it a write. This protects against fat-finger changes in an admin screen.

Testing the matrix

Treat it like code. Write tests that assert each cell's outcome for a synthetic agent, and run them in CI. Changes to the matrix should go through review.

Reviewing it over time

Every quarter, pull your audit records, count outcomes per cell and ask two questions: which held cells were accepted without edits almost every time (candidates for allow), and which allowed cells led to corrections or reversals (candidates for hold or deny).

FAQ

Should humans be in the same matrix?
Yes. Human roles are rows too. It keeps the model consistent.

Can a single agent have more than one role?
Better not. One role per agent keeps reasoning simple; create two agents if needed. In AI PRO CRM each agent has exactly one preset.