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.

Account menu → 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.

Registering an agent

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

Give it a description while you know what it is for. The field is optional and up to 500 characters, and it is the one place to record why this agent exists and who runs it — the name cannot carry that, because the name is what gets stamped on every comment and suggestion the agent writes inside a document. The description never appears in a document: it sits on the agent’s row in this console, and it is searched from the roster. You can change it later — see Describing an agent afterwards below — so registering without one costs you nothing.

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. Beside I’ve saved it, that dialog also offers Grant access…, pre-selecting the agent you just registered: a fresh agent holds nothing until something is granted to it, and the moment you registered it is the moment you know what it is for.

The same dialog tells you where the agent connects. Under the credential it shows the MCP endpoint — your DraftMesh address followed by /mcp, for example https://draftmesh.example.com/mcp — and an MCP client config you can copy straight into a client that reads the common mcpServers format:

{
  "mcpServers": {
    "draftmesh": {
      "type": "http",
      "url": "https://draftmesh.example.com/mcp",
      "headers": { "Authorization": "Bearer <the agent credential>" }
    }
  }
}

The agent speaks MCP over streamable HTTP to that one address and sends its credential as a bearer token on every request. The config contains the credential, so it is shown once along with it; the endpoint alone is not secret, and it stays on the agent’s detail in this console for whenever you wire the agent up later.

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.

Describing an agent afterwards

Most rows in the registry were never registered through the dialog above. Every machine someone connects DraftMesh from adds an agent of its own, and nobody was asked for a description on the way — which is a shame, because whose laptop is this? is the question those rows raise most often.

So the description can be written at any time. On the roster, Add a description (or Edit, where there already is one) opens the field in place; Save commits it and saving an empty field clears it. A revoked agent can be described too, deliberately: why we retired this is worth recording against the row that records what it could reach.

The name cannot be changed this way, and that is not an oversight. The name is stamped as the author of every comment and suggestion the agent has written, inside .md files that have already been synced, exported, and opened in other editors. Renaming here would silently re-attribute work in documents DraftMesh no longer holds. If a name is wrong, register the agent again under the right one and revoke the old row.

Each edit is recorded in the audit ledger as agent.updated, naming who made it and which agent it was about. The text itself is not copied into the ledger — a field meant to be corrected should not accumulate an uncorrectable history of its own drafts.

Finding one in the roster

The roster is longer than the agents you registered by hand. Every machine someone connects DraftMesh from registers an agent of its own, and a revoked agent keeps its row — revoking is not deleting, and the record of what that agent could reach is the point. So a healthy organization’s registry runs to dozens of rows, and three controls sit above it:

• Search matches a word against agent names and descriptions — a plain substring, so review finds Release notes reviewer and anything whose description mentions reviewing. It searches the whole registry, not the rows currently on screen.
• Status narrows to Active or Revoked. Revoked on its own is the fastest way to see what has been retired and what its grants still are.
• Sort is Registered (the order they were added, the default) or Name (A–Z), which ignores capitalization.

They combine, they page correctly — Load more keeps whatever you have narrowed to — and Clear filters puts the whole registry back. When a search or filter matches nothing the roster says exactly that, so an empty list is never mistaken for an organization with no agents. An auditor gets all three: they narrow a list, they do not change anything.

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. Where they are set differs: the Share panel is for people, and an agent’s access is set in Automate this document…, on the document’s Agents tab — the same place its standing rule is authored — with Access review listing every agent grant across the workspace. An admin can also give an agent access from this console, without opening a document: Grant access… on the agent’s row here, or on the credential dialog straight after registering it, asks for a workspace, a whole workspace or one document in it, and a level. When your organization has only one workspace it is chosen for you; the scope never is, so you still pick the whole workspace or a document yourself. Edit may still need the document’s owner — the console offers the level rather than hiding it, and when the owner is somebody else the server’s own refusal is shown to you verbatim.

Two settings, side by side: This document, and Rest of workspace. The document setting wins where the two disagree — including when it is lower, which is how you narrow one agent on one sensitive file without touching what it can do everywhere else.

Rest of workspace reaches the whole workspace, its list included. An agent granted the whole workspace can open any document in it by path — including one it creates — and can also list, map and search that workspace, since a whole-workspace grant already lets it name any path. Document grants never do: an agent holding only document grants in a workspace cannot list, map or search it, and is told nothing about the rest of that workspace — naming the documents it should work on stays with the person who connects it.

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 the document’s owner — never a default, never something the agent can arrange for itself, and not something any other admin can do on the owner’s behalf. (For a document an agent created, the owner is the person who operates that agent.)

An edit grant can additionally carry decide — permission to accept or reject suggestions on that one document. Same rules, stricter still: owner-only, per document (a workspace-wide grant can never carry it), and shown in Access review as its own badge, because it is the one grant that closes review threads without a human click. An agent holding edit without it that tries to decide is refused with an answer naming the grant it holds and that decide was not granted, so it replies on the suggestion or asks the owner instead of retrying.

And there is a floor no grant can lift. No agent credential or personal API token can ever record an approval, roll back a version, or manage sharing. Sign-off stays a human act on every document, whatever else the owner delegated, and DraftMesh enforces that server-side rather than trusting the caller to decline.

Nor does a grant reach your organization’s activity record. The hosted service keeps a diagnostics record of each request it serves (the route, the workspace id, the status and timing, and which account it was served for), and an agent connected through the hosted door can read it with its read_diagnostics tool — but only the records of its own requests: a registered agent’s credential sees what that agent did, and a person’s connector sees what that person did. Neither ever sees other members’ activity or the workspaces they worked in, whatever documents it was granted, and a personal API token has no diagnostics door at all. The health answer an agent gets is the same coarse one a member gets: the service is up, for how long, and its API version.

Turning off one person’s connector

Separate from agents you registered: a connector is an MCP client someone attaches to their own DraftMesh account — the sort of thing an AI assistant on their laptop uses. Account menu → Administration… → People → Members (as observed) carries a Block control for each person, and a blocked connector is refused on its very next call. It closes the connector door and nothing else: that person keeps their account, their sign-in, their devices, and the web app.

A block is your organization’s decision about your organization’s door. It stops their connector when it acts as you. If the same person also belongs to another organization, that organization’s door is unaffected, and its admins can neither see your block nor lift it. That cuts both ways — someone else blocking them elsewhere does not close your door either.

People whose DraftMesh account lives in another organization get the same control, in two tables of their own just below. Organization members homed elsewhere lists members of your WorkOS organization whose account is homed elsewhere — usually because they signed in somewhere before accepting your invitation — read from the organization’s membership roster, including people who hold no share here; if that roster cannot be read, the table says so rather than showing an empty list. People with shares is derived from the shares your organization gave out, so it names the people you granted something to, whether or not they are members. Neither person can appear in the list above, because they have no member record homed in your organization; they are listed by the account id shown on the row, which is what the block is recorded against. Neither table is everyone who could ever act as your organization. An admin can also Remove… a person from Organization members homed elsewhere: it ends their membership of your organization and their access here, frees no seat because they hold none here, and leaves their own workspace and other organizations untouched.

One person this lever cannot reach: someone who has never signed in anywhere has no account id to record a block against. They also cannot attach a connector, for the same reason, so there is nothing to block until they do.

To shut every connector and every agent at once, rather than one person’s, use the organization-wide switch in Agents instead.

Memory writes and skill installs

Two more organization-wide levers sit beside the agent switch in Agents. Both are admin-only, both are recorded in the audit ledger when they change (org.agent_memory_ceiling_changed, org.skill_install_gate_changed), and an auditor sees their state with no control.

• Memory writes — the ceiling on every memory workspace’s memory policy (see AI assistants): Direct, Propose or Off. It is the most any memory workspace in your organization allows: an owner can choose a stricter policy for their own memory, never a looser one. Propose makes every assistant’s memory entry wait for a person to accept it; Off stops assistants adding memory entries anywhere, while they can still read. Tightening it asks you to confirm; loosening it is one click. It takes effect on the next write.
• Skill installs — Require approved skills. While it is on, every skill in your organization installs, exports and syncs only the version a person signed off on its SKILL.md, whatever the skill’s own install gate says; a skill nobody has signed off installs nothing until someone does. Turning it on asks you to confirm; turning it off is one click.

Agent activity allowance

Agents are never seats. Registering an agent, connecting one, or leaving one idle costs nothing. What is counted is what agents do: each organization has a monthly pooled allowance of agent actions, shared by every agent in it. An action is an agent’s save, suggestion, comment, question or answer, decision on a suggestion, task delivery, or subscription firing. Reads are free, and a person’s own connected assistant, acting as that person, is not metered.

Overview shows the month’s usage on its Agent activity tile: actions used, the allowance, and when the month resets. At 80% of the allowance DraftMesh warns admins, once per month. At the cap, agent actions pause with a clear error naming the allowance and the reset date, until the month resets. Agent actions are never sold: DraftMesh works with the AI tools you already pay for and sells no AI usage, so nothing is ever billed for agent activity. If your agents regularly need more than the allowance, contact support@draftmesh.com.

The organization-wide switch, revoking an agent, and pausing or disconnecting a subscription always work, whatever the allowance says — the cap stops agents acting, never you stopping them.

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 Automate this document… 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 Standing instructions, the field answering “What should the agent do every time it wakes up?”. Its target is the document you connect it from. Workspace-wide rules exist on the API and are listed as Every document in this workspace, but the dialog always connects the open document.

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 instructions, and Delete to remove it. (The Agents tab’s own Connected agents list offers the same two as Edit… and Disconnect, plus Revoke access for the agent’s own grant on that document.) 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.

When a rule’s creator has been removed, made an auditor, or lost all access to its workspace, the rule shows Connected by someone who no longer has access. A paused rule keeps Resume, with a reminder that it will pause again until that access is restored.

A rule never acts beyond the person who connected it. Each task it starts is capped at what that person can do on the document now, not at what the rule was set to. If they have since moved to a Reviewer seat or lost edit access, the task gets the lower level. If they are removed from the organization, made an auditor, or left with no access to anything in the rule’s workspace, the rule is paused automatically and anything it had queued is dropped. Automatic pauses are recorded in the audit log. If they keep access to anything in the workspace, the rule keeps running at the level that access gives them, which can be view on every document there. A suspended organization never pauses a rule. Resume works once the person who connected it has access again; resumed earlier, it pauses itself on its next firing. A rule is never moved to another person, and a person who is no longer an admin cannot resume their own rule. Another admin can. An agent @-mentioned in a comment is capped the same way, at the mentioning person’s current access.

Suspending the person who connected a standing rule skips its firings without pausing the rule. The next event after reinstatement runs normally; events during suspension are not replayed. This differs from removal, which pauses the rule and requires an explicit resume. In-flight tasks fail at their next callback and do not revive after reinstatement. Mentions still create their markers, but notification, mention and onboarding emails from the organization are not sent to suspended members. Existing sign-off requests remain open.

Disconnecting a rule does not revoke the agent’s access. Standing access outlives the rule by design: the agent keeps whatever it was granted on the document, visible in the Agents tab and in Access review, and editable by reopening Automate this document… for it. To withdraw the agent’s own grant on the document from the document itself, use Revoke access on its row; to withdraw its workspace-wide access, set Rest of workspace to No access under Edit….

A task already in flight also depends on its requester’s current access. On each request using its task callback credential, DraftMesh checks that the requester still holds at least the task’s original capability. If their access has dropped below it, they have lost access to the document, or they have become an auditor or been removed from the organization, the task fails and its callback credential stops working. Restoring access does not restart that task; send a new request. The failure reason is recorded once against the task in the audit log. The agent’s separate standing credential still follows its own grants.

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.

Delivery 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. To connect one, point its MCP client at the MCP endpoint shown when you register it and on its detail here — https://<your DraftMesh address>/mcp — with its credential in an Authorization: Bearer <credential> header; the config snippet under Registering an agent above is the whole of it. A registered agent can also call the REST API at https://<your DraftMesh address>/v1 with the same bearer after its credential has been rotated to the current dm_agt_… form. Older unprefixed credentials remain MCP-only until they are rotated, and task-scoped callback credentials remain MCP-only. What it may then do is exactly what it has been granted — a call its grant does not cover is refused. The outbound side — the task payload DraftMesh POSTs to its Webhook and that payload’s HMAC signature — is verified with the signing secret shown when the webhook is set.