Admin: Governing AI agents

A registered agent is not a feature you switch on. It is a principal in your organization, with its own name, its own credential, and its own access — governed the same way a person is, and revocable the same way.

⚙ Settings → Administration… → Agents is where that governance happens.

For what agents can do inside a document, and how someone connects one to their own machine, see AI assistants (MCP).

Registering an agent

Registering mints two things at once: a principal your organization now contains, and a bearer credential that authenticates as it.

The credential is shown exactly once. When it appears, copy it — DraftMesh stores only a hash of it and cannot show it to you again. That is a security property, not an interface quirk: a credential a console can re-display is a credential the console is storing.

If a credential is lost or leaked, Rotate issues a new one and the old one stops working on the very next request. There is no grace period.

Revoking an agent

Revoke ends the agent’s participation, and it cascades:

• Its credentials are deleted — the token stops working immediately, not at expiry.
• Any task still in flight is marked failed (agent revoked), visibly, rather than sitting pending forever against an endpoint nothing will sign for again.
• Its doc-connected subscriptions are disabled — kept, and visibly off, so you can still see what it had been connected to — and anything they had already queued is dropped.

Revoke is idempotent; revoking twice is safe.

One thing revoke does not do: it does not remove the agent’s document shares. A revoked agent cannot authenticate, so those grants do nothing — but they stay in the list until you remove them. Access review shows them, marked Agent revoked — this grant is inert, which is where to clean them up.

What an agent can reach

An agent holds document grants exactly as a person does, at the same four levels, and it appears in the same share roster. Nothing about it is a special case.

The default is suggest. An agent reads, comments, and proposes; its text enters a document only when a human accepts it. Granting an agent edit is a deliberate, per-document decision by an admin — never a default and never something the agent can arrange for itself.

And there is a floor no grant can lift. No agent credential can ever accept or reject a suggestion, record an approval, roll back a version, or manage sharing. Deciding is a human act, and DraftMesh enforces that server-side rather than trusting the agent to decline.

Sending work out: webhooks and connections

Two settings decide where your documents’ contents can travel, so both are admin-only and both are recorded.

• Webhook — the HTTPS endpoint DraftMesh POSTs signed tasks to. Its signing secret is show-once, like a credential; the roster displays only a short non-secret key id so you can tell which secret is live. You can clear the endpoint or rotate the secret at any time.
• Doc-connected subscriptions — standing rules that fire tasks automatically when a document is edited or commented on, with no human in the loop per event. Because a rule is broader authority than any single task, creating, changing, and removing one is an admin act and each is recorded.

A rule is created with Connect an agent… and names what should wake the agent — The document is edited, The document is created, Someone adds a comment, Someone adds a suggestion, Someone asks a question, A comment or suggestion is resolved or reopened — plus a standing instruction answering “what should the agent do every time it wakes up?”. Its target is one document, or Every document in this workspace.

Each rule appears under the agent’s Connections, badged Enabled or Paused, with Pause / Resume to stop and restart it without losing it, Edit… to change its triggers and instruction, and Disconnect to remove it. Every firing shows up in the agent’s request list, so a rule that has run away with itself is visible rather than merely suspected.

A subscription cannot be retargeted after it is created — you cannot point an existing rule at a different document. Disconnect it and connect again. That keeps a rule’s identity and its target from drifting apart.

Task history

Each agent’s history shows what was sent, what came back, and what did not arrive. Failed deliveries are the point of it — a dead-letter reason is shown in full on its row rather than hidden behind a hover, because an operator opening this panel is usually there precisely because something did not arrive.

Wiring your own agent

This topic covers governing agents. The engineering side — the MCP tool contract, the outbound task payload and its HMAC signature, retries and idempotency, subscriptions and Agent Card delivery — is covered in a separate operator guide, Connecting your own agent, together with the task webhook contract and a sample receiver. It is not published here — ask us for it and we will send the current copy.