Cookbook
Give an agent only what it needs
The first thing to do in a new workspace, and the one people do last. An agent given less is not a hobbled agent: it is one that cannot make the mistake you have not thought of yet.
The situation
You are about to connect something that writes to your customer record without a person reading each write. Maybe several somethings: the one that logs your email, the one you talk to, the nightly job that syncs a spreadsheet.
The instinct is to give each of them everything, because it is one less thing to debug. The instinct is wrong in a specific and recoverable way, and the fix costs about a minute per credential.
What must be true when you are done
- Each agent holds the narrowest credential that lets it do its job.
- An agent that only reads cannot be talked into writing, by a prompt or by a mistake.
- You can tell which credential made any given change, afterwards.
- Revoking one takes effect on its very next request.
What the permissions actually are
| Scope | What it lets an agent do |
|---|---|
| crm:read | Read everything in the workspace. The floor for anything useful. |
| crm:write | Create and update records, log interactions, move deals. |
| crm:configure | Change the pipeline, define fields, define your own types. |
| data:export | Take the whole workspace out as a file. |
| crm:admin | Everything above, plus undoing a change and managing this workspace's credentials. The broadest thing you can mint, and the only scope that can undo. |
Merging, and undoing
Two things people expect to find on that list are not there, and the answers differ.
Merging is part of writing. A credential with
crm:write can combine two records, and there is no narrower
scope that permits merging alone. That is worth knowing before you hand
out a write token: a merge is harder to think about than an edit, and it
is reversible by unmerge rather than by undo.
Undoing needs crm:admin, and that is broad.
Reverting a change is the one operation here with no narrow scope: the
only credential that can undo is one that can also read, write, configure
and manage this workspace's credentials. If what you wanted was an agent
that can undo its own mistakes and nothing else, you cannot have it today,
and the useful shape is usually the opposite. Give the agent
crm:write, let a person undo from the history, and keep the
broad credential for the people who already hold the broad role.
Note what is not on that list at all. Nothing an agent can hold lets it delete the workspace, manage members, change billing, or erase a person's data. Those are things a human being does while signed in, and no credential carries them, so no prompt can reach them.
The part that makes it work
An agent is not told about tools it cannot use.
This is the difference between a permission system and a permission dialog. Connect a read-only agent and it does not see a write tool at all:
Agent
An agent that can see a tool will eventually try it, and a refusal at that point is correct but wasteful: it has already decided to act, it burns a turn, and a persistent one will look for another way. An agent that never sees the tool plans around its absence from the start.
It can also ask what it holds, so a well-written agent tells you it cannot do something rather than failing at it.
And the refusal underneath, in case
Hiding is not enforcing. If a credential does reach an operation outside its scopes, whatever route it came by, it is refused.
Agent
Read that last line twice, because it is the part people get wrong when somebody leaves. A credential's power is the intersection of its own scopes with the CURRENT role of the person who created it, read live. So demoting a departing colleague reduces every token they minted, at once, without anybody hunting for a list of them. And nobody can mint a credential more powerful than themselves.
What to give each of yours
The agent you talk to gets read and write. Not configure: it does not need to redefine your pipeline mid-conversation, and the day it decides to is the day you find out what that costs.
The email logger gets read and write, and nothing else. It creates contacts and records interactions. It has no business merging.
The reporting job gets read. This is the one people over-permission out of habit, and it is the one most likely to be running somewhere you have half forgotten.
The one-off cleanup gets merge and revert, and gets revoked when it is finished. A credential for a task that ended is the most common thing found during an incident.
Verify it
- Ask each agent what it can do. It should tell you its capabilities, and they should match what you intended rather than what was convenient at the time.
- Try one thing it should not be able to do. A read-only credential asked to write should be refused, and the refusal should name the scope.
- Read the change history. Every change names the credential behind it, so "which agent did this" is answerable rather than inferred from timing.
Run it again
Every time you connect something, and once a quarter across everything you have connected. The quarterly pass finds the credential minted for a migration eighteen months ago that still has configure, which nobody has thought about since the day it was useful.