Manage agents: who sets up agents

Last updated October 9, 2026

On this page

Draft for review

Who may make, change and assign the company's agents is a permission, manage agents. Admins hold it for the whole company without a grant. An admin may give it to anyone, for the whole company or for some teams: a team lead, but just as well an engineer who looks after the sales agents. It is not tied to leading a team.

A person who holds it is a holder. The Grant sheet says what it allows, in four lines:

  • Make copies of app agents for the teams they cover, and change, pause or archive them (Templates and copies)
  • Make an agent for one person in those teams, who turns it on
  • Review changes to those agents, never their own
  • Decide people's requests for their own agents

This page covers granting and revoking the permission, what it covers, today's team leads, and what holders and leads may do. It describes the golive branch. What is not possible yet is listed at the end.

Granting it#

Grants live on People, tab Permissions (admins): "Who may make, change and assign agents besides admins. Admins hold every permission without a grant."

  1. As ada, open People > Permissions and choose Grant.
  2. Who: A person (pick one) or Everyone with a role. A role grant covers everyone who holds the role, now and later; the role box lists the roles people hold with how many ("eng_lead · 1 person"). A role nobody holds warns first: "Nobody holds the role ops_nobody today. The grant waits for whoever takes it." Press Grant again to grant it anyway.
  3. Permission: Manage agents, with what it allows in four lines.
  4. For: The company, or Some teams and the teams. The company reads "A second admin approves this before it covers anything."
  5. A Note, then Grant.

The table lists each grant: who, "Manage agents", for whom ("Sales", "The company"), who granted it and when ("Ada Park · 9 Oct"), the note, and its state: Live, Waiting for a second admin, Kept from team lead · today's limits, Suspended while deactivated, Lapsed: no longer leads or Revoked. Show revoked lists the revoked ones.

The holder reads it on their Profile: "You manage agents for Sales (granted by Ada Park on 9 Oct)". Their sidebar's Apps section ends with Manage agents, which opens Apps > Agents I manage. The person drawer on People shows "Manages agents for Sales" under their role.

Granting, revoking, approving and making a grant full need a sign-in in the workspace within the last ten minutes; no API token can do them ("Sign in to the workspace to do this; a token cannot."). The person is told in their inbox.

A grant for the whole company#

A grant for the company needs a second admin: until another admin presses Approve on its row, it reads Waiting for a second admin and covers nothing. A company with only one admin approves its own, marked self-approved.

Revoking#

Revoke asks first ("Eli Novak stops managing agents for Sales at once. What they filed stays for someone else to decide.") and takes effect at the next check: a sheet the holder had open is refused when they save, with who and when: "You no longer manage agents for Sales: Ada Park removed it at 10:02". Changes they filed stay, marked; someone who still manages those agents may promote them, and any manager may reject them. Copies they made keep working; automatic updates they turned on turn off.

A role grant follows role changes at once, both ways: a grant to the role eng_lead covers Erin until her role changes, and covers whoever becomes an engineering lead next. A deactivated person's grants are suspended until they are reactivated; offboarding revokes them.

What a grant covers#

Scope Covers
The company Every copy
Teams A copy whose works for is all inside those teams: a listed team, or people who are members of one. Never a copy for the whole company
A personal copy Covered when its owner is a member of a listed team, by a full grant only
A request for one's own agent Covered when the person asking is a member of a listed team

A grant names teams, not membership: Eli, in Engineering, manages agents for Sales. A copy that works for Sales and Support is listed for a Sales holder and may be read, but shows "Partly outside the teams you manage agents for: ask an admin" in place of its actions. A team that is removed covers nothing; its grants read "Sales (removed)".

A grant counts only for its person acting as themselves, in their own session or with their own token. It never counts for an agent, whatever its role, nor for a run acting for the holder: an agent asked by Eli cannot change a copy.

Some things stay an admin's whatever the grant:

  • naming an admin or another holder in a copy's works for, and marking a copy required for people;
  • widening an agent: giving back a tool or memory its template has;
  • a copy's trust tier, and a limit above the company's ceilings;
  • enabling, updating or pausing an app, and its connections;
  • granting the permission. A holder never grants it onward.

The grant manages agents; it is not a power to read the company's records. A holder of manage agents for Sales who is not a member of Sales does not read Sales' WhatsApp conversations, for example.

Grants kept from team leads#

Before this permission existed, a team's lead could copy their team's agents (with an admin's approval) and propose and review their changes. At the upgrade, each lead was given a grant for the teams they lead, so nothing a lead could do stopped working and nothing more became possible (the user's decision of 8 October 2026). In the demo, Sam (Sales), Maya (Support), Pat (Product), Erin (Engineering) and Fiona (the Founder's office) hold one.

A kept grant reads Kept from team lead · today's limits, granted "at the upgrade" (on the lead's Profile: "You manage agents for Support (granted by OrchKernel on 9 Oct, kept from team lead with today's limits)"), and keeps today's limits:

  • a copy they make waits for an admin;
  • a change that gives a tool or skill waits for an admin;
  • they make no agent for one person, cover nobody's personal copy, and decide no requests.

It covers only the teams the person still leads, and lapses for a team when they stop leading it. An admin may revoke it, or turn it into a full grant with Make it a full grant ("Sam Ortiz keeps managing agents for Sales, without today's limits: their copies apply without an admin, and they decide people's requests."). The same offer is in the lead's drawer on People: "Manages agents for Sales with a lead's limits. Make it a full grant?"

A new lead, with no grant, keeps only a lead's powers over people and runs. The Permissions tab lists them, "Has a lead's powers over people and runs only. Also let them manage agents for Support?", with Let them, which opens the Grant sheet filled in.

What holders, owners and leads may do#

Action A holder covering it An admin The owner of a personal agent A team lead without a grant
Make a shared copy Yes, for their teams, naming no admin or holder Yes No No
Make an agent for one person Yes, for someone in their teams other than themselves; made off until they turn it on Yes Through a request No
Change settings Yes (a new name or one line is reviewed) Yes Name, one line, model, private, replaces, automatic updates, pause and resume, lower limits No
Change instructions, checks, tools Propose, and review others' Yes Their own No
Give back a tool or memory Propose; an admin reviews Yes Propose; an admin reviews No
Change someone's personal agent Only with its owner's OK Only with its owner's OK n/a No
Decide people's requests for their own agent For people in their teams, never their own Yes No No
Decide a personal agent's approvals and drafts No No Yes, alone No
Pause Yes Yes, a switch only an admin lifts Their own Shared copies that work for their team; never a personal agent
Archive and restore Yes Yes Their own No
Grant or revoke the permission No Yes No No

Hand-hired agents of a team (not copies) are covered the same way: Eli's grant for Sales covers an agent hired onto Sales. Built-in and outside agents stay admins'.

Requests for one's own agent#

People ask for their own agent on My agents (Your own agents, and private ones). Every holder covering the person gets the request in their inbox, never the person asking: "Alice Chen asks for her own copy of Inbound Sales Assistant", with her note and the tools it will use, Approve and Reject. The one named on the request is the holder with the narrowest teams who is available. A request nobody touched for three days goes to admins too. A holder's own request goes to another holder covering them, else to admins. The approver may lower its limits before approving, nothing else.

A request whose tools reach data the person does not already reach (a Metrics Reviewer reading Stripe revenue, for a sales rep) needs an admin, who sees each tool and what it reaches.

Not possible yet#

  • A sheet that sets a team's lead: People has none, so "Also let them manage agents for Support?" is offered on the Permissions tab and in the lead's drawer instead.
  • Permissions other than manage agents (manage apps, approve spending, manage connections).
  • Granting from a token, by design.

For developers#

API#

All under /api.

Method and path Who Purpose
GET /permissions Admins: every grant; a holder: their own Grants: id, permission, subject ({ person } or { role }), scope ("company" or { teams }), state, kept_from_lead, words for each
POST /permissions Admins, signed in within ten minutes { permission: "manage_agents", subject, scope, note }; 201
DELETE /permissions/:id The same { note }: revoke
POST /permissions/:id/approve Another admin, the same Approve a grant for the company
POST /permissions/:id/full Admins, the same Make it a full grant
GET /permissions/roles Anyone signed in The roles people hold, how many, and what each carries
GET /permissions/lead-offers Admins Leads without a full grant for their team
GET /permissions/personal-templates, PUT /permissions/personal-templates Anyone reads; admins change { pack, agent, open }: People may ask for their own
GET /me/permissions Anyone Your grants and the Profile lines
GET /me/agent-requests, POST /me/agent-requests, POST /me/agent-requests/check, DELETE /me/agent-requests/:id Anyone Your requests (Your own agents)
POST /agent-requests/:id/decide Holders covering the person, admins { approve, note, limits }
GET /people/search?for=manage_agents&q= Holders, admins People in your teams, for the works-for picker

Errors: 403 denied with the reason, 403 session_required for a token on a route that needs a sign-in, 409 request_open (a second request for the same agent while one waits), 422 invalid.

Events#

Event When
permission_granted, permission_revoked grant, permission, subject (person:<id> or role:<name>), scope, by, note
permission_grant_approved The second admin approved a grant for the company
copy_requested request, from, person; the decision is the approval's own event

CLI#

With the server stopped:

sh
ok --state orchkernel-demo/state.db --as ada permission list
ok --state orchkernel-demo/state.db --as ada permission grant manage-agents --to eli --teams team:sales --note "Runs the sales agents"
ok --state orchkernel-demo/state.db --as ada permission grant manage-agents --role eng_lead --teams team:product
ok --state orchkernel-demo/state.db --as ada permission grant manage-agents --to eli --company   # a second admin approves
ok --state orchkernel-demo/state.db --as dana permission approve <id>
ok --state orchkernel-demo/state.db --as ada permission revoke <id> --note "Moved teams"