Templates and copies: your own versions of an app's agents

Draft for review

Every agent an app brings is a template: what the app ships for that agent at one app version, read-only. Nobody asks a template and it never runs. The agents people ask are copies made from templates. A copy has its own name, its own one line ("Answers new demo requests within minutes"), its own way of talking, a subset of the template's tools, its own limits, and works for the company, some teams, some people, or one person. When the app is updated, no copy changes: each copy shows "v2 available" to whoever manages it, and that person chooses what to take.

There is one kind of agent. A team's agent and a person's own agent are the same thing, a copy, and differ only in whom they work for (the user's decision of 8 October 2026). A copy that works for one person is that person's own; Your own agents, and private ones covers those. Who may make and change copies is a permission, manage agents; see Manage agents.

This page covers templates, making a copy, who it works for, changing it, template updates, and pausing and archiving. It describes the golive branch. What is not possible yet is listed at the end.

Words#

People who only use agents read "a version of Sales Assistant for Sales", "your own version"; the word "copy" is on the managers' screens. Eval cases are called checks on every screen.

What the upgrade changed#

A company that ran OrchKernel before templates and copies existed is moved at the first start of the new binary, once, and nothing anyone uses changes:

• Each app's agents became their templates' company copies, with the same ids, threads, delegations, repeats and history. Alice still asks Sales Assistant.
• Each agent's settings moved from the app's record onto the agent: who it acts for became works for, marked required (it keeps acting for them without their turning it on), its budget became its monthly limit, and its trust and on or off stayed as they were. An earlier copy (a "fork") became a copy of its template.
• An agent whose lifetime budget was already spent was paused, with the reason "Its budget was used up before the upgrade", so the upgrade starts nothing that had stopped.
• Every admin got one notice: "Agents are now copies of their app's templates. Nothing changed for anyone. Managers can now make their own copies." It lists each agent's new monthly limit ("Sales Assistant: $50.00 a month, was $50.00 in total") and the agents paused for their budget.
• Each team lead got a grant of manage agents kept from team lead, with exactly what a lead could do before (see Manage agents).

A fresh Enable does the same in one step: it records the templates and makes each one's company copy with the Enable sheet's agent settings. In the demo every app is enabled this way.

Where you find templates and copies#

Someone who neither is an admin nor holds manage agents and opens Apps reads "Only admins and people who manage agents open Apps. Your agents are on My agents."

A holder sees, on an app's page, only Overview (read-only), Templates and Agents: "Make copies of this app's agents for the teams you manage agents for, and keep them up to date."

The Templates tab#

One card per template, with "Each template is an agent the app ships, read-only. Make a copy to give a team, a list of people or one person their own version, with its own name, way of talking, tools and limits. A copy never changes when the app is updated; whoever manages it chooses." above them.

The card's menu holds Update every copy that can take it (holders and admins), and for admins Apply required parts to every copy, Pause every copy and Resume every copy.

Some templates are never copied: the Context app's agents, the built-in agents (Architect, Coordinator, Designer, Schema Steward) and a template whose role is an admin's. The Inbox Assistant is copied only as each person's own (The inbox assistant).

Making a copy#

Make a copy opens a sheet, "Make a copy of Sales Assistant" (full screen on a phone), in five numbered sections:

The foot sums it up ("Works for 2 people in Sales · up to $200.00 a month") beside Make the copy. A problem the server finds shows at its field.

The copy is made at its source's behaviour. Anything you changed in section 3 is filed as a change to the copy right after, which waits for someone else to read it (Behaviour changes). The notes say so: "Made Inbound Sales Assistant", then "Your instruction changes are waiting for review by another manager or an admin".

Try it: Eli makes Inbound and Outbound Sales Assistant#

1. As ada, give Eli (an engineer) manage agents for Sales: People, tab Permissions, Grant, Person Eli Novak, Some teams, Sales, Grant (Manage agents).
2. As eli, open the sidebar's Apps section and choose Manage agents. It opens Apps > Agents I manage: "The agents you set up for others."
3. Open Enabled, CRM, tab Templates. On Sales Assistant choose Make a copy.
4. Name it Inbound Sales Assistant, one line "Answers new demo requests within minutes". Under Who it works for choose Teams: Support reads "Outside the teams you manage agents for" and cannot be ticked. Tick Sales; the note reads "Works for 2 people."
5. On How it talks and who it serves choose Edit: Tone "Warm and brief", Who it serves "Inbound demo requests". On Steps choose Edit, add a line "Demo requests: answer within minutes with two times from the calendar", and choose Keep.
6. Choose Make the copy. The notes read "Made Inbound Sales Assistant" and that its instruction changes wait for review. On CRM's Agents tab its row reads Change in review.
7. Make a second copy, Outbound Sales Assistant, "Reaches new prospects by email", for Sales, and untick Create calendar event under What it can use. Taking a tool away needs nobody's review.
8. As sam, open Inbox. The change to Inbound waits for him (he manages agents for Sales and did not propose it): it says what it is ("Inbound Sales Assistant's own instructions") and that its checks passed. Approve, then Promote. Eli could not have done either himself.

As alice, the agent picker offers both new copies with their one lines, beside Sales Assistant. On My agents Inbound reads "Offered to you" until she asks it the first time; then it works for her.

When making a copy is refused#

A holder whose grant was kept from team lead may make a copy, but it waits for an admin, as a lead's copy did before: the answer is 202 with an approval in the admins' inbox.

Ids: a shared copy's id is the template's id and the name, sales-assistant-inbound (then -2, -3); a personal copy's id is opaque, pc- and ten letters. Its skills are copied as <skill>-<the rest of its id> at version 1. Every id a copy or a template holds is reserved: hiring an agent with it is refused (409 id_reserved), live or archived.

Who a copy works for#

Works for names the company, teams and people, minus Except…:

• The company is every active person who is not an admin.
• A team is its members who are not admins. The picker says so: "Admins are not included through teams. Add Ada Park by name to include them."
• A person named is included, an admin too (only an admin may name an admin or a holder).
• One person alone makes a personal copy: "This makes a personal copy for Alice Chen. Alice turns it on, and may make it private."

A holder's people search finds only people in their teams, so a holder who cannot open People can still choose Alice.

Works for is an offer. A copy acts for a person only once that person turns it on. Asking it the first time turns it on ("Ask it, and it works for you"), and so does Turn on on My agents or on the copy's page. Not for me or Turn off for me turns it off for them again. Until then the copy acts for nobody, and My agents shows it as "Offered to you".

Required for them. An admin may mark a copy required: it then acts for everyone it works for without their turning it on, and they cannot turn it off ("Sales Assistant is required for you by an admin; it stays on"). The company copies made at the upgrade or at Enable are required, so nothing changed for anyone.

Each person a copy acts for gets one delegation, owned by the app ("via CRM", see Delegations): act as them, limited to the copy's tools, collections and data classes, no passing on. People who join or leave a team, are deactivated or offboarded, or turn the copy on or off, gain or lose it at once.

When a copy stops working for someone (its works for changed, it was archived, they left the team), they get an inbox notice, "Inbound Sales Assistant no longer works for you (Eli Novak, 9 Oct)": their repeats on it pause, and approvals and questions its runs left for them are cancelled with a line in the thread.

Changing a copy#

A copy changes in two ways.

Settings#

Settings (on the copy's row menu, or on its page) opens "Settings of Inbound Sales Assistant":

• Name and purpose. On a copy that works for others, a new name or one line reaches other people's pickers, so another manager or an admin reads it first; the save answers "Saved; the new name and one line wait for another manager or an admin to review".
• Who it works for, the same picker.
• Limits.
• Updates and requests: Take template updates on its own when they only add, and People it works for may ask for their own.

Everything else applies at once. If someone saved since you opened the sheet, it reloads: "Someone changed it since you opened it: it has been reloaded, so save again." If your permission was taken away meanwhile, the save is refused with who and when: "You no longer manage agents for Sales: Ada Park removed it at 10:02".

Only an admin changes a copy's trust tier (through the API, see For developers) or raises a limit above the ceilings.

Behaviour changes: instructions, checks and tools#

Instructions, the How it talks card, guardrails, approval points, checks, tools, memory, template updates and restores go through the change pipeline (Changing a skill or playbook): a proposal on the copy, its checks run, then reviewed and promoted. A copy has at most one open behaviour change (409 proposal_open).

What a copy's change may carry is fixed: playbook text, checks, tools within the template's, memory within the template's. Anything else (a skill's permissions or collections, its run caps or triggers, the agent's role, team, reports to, trust, budget, model rules, the template link) is refused with 409 copy_setting, naming the field. A change made against an older version of the copy is refused at promote with 409 copy_moved ("Inbound changed after this proposal was made: make it again from the current version"), so a stale change never undoes a later tightening.

Once a change is promoted, the copy's card and the top of each person's conversation with it say so in one line: "Updated 9 Oct by Eli Novak: new steps for demo requests".

Rules a copy carries#

A copy's own approval rules only tighten: they deny a step, or ask someone before it. Each matches that copy only. The approver is the person it works for, an admin, or a named person who may read what the step carries (naming yourself needs an admin); on a personal copy every rule asks its owner, whoever writes it. A rule records its author, and removing it needs at least its author's authority ("Ada Park, an admin, set this rule; only an admin removes it"). A copy made from another copy inherits that copy's rules. Copy rules arrive with storage version 5; before it they are refused with not_ready. There is no screen for them yet.

Rules that name a template cover its copies#

A rule of an app, or of the company's policy, that denies a step or asks for approval and names a template covers every copy of that template, so no copy escapes it. The founder app's founder-investor-mail-needs-admin holds every copy of Investor-Update Writer, and the gate's trail says "matched as a copy of investor-update-writer". An allow rule never reaches through a template: it covers only the exact agent it names. See Policy, rules and kill switches.

Template updates#

Updating an app#

When the binary carries a newer version of a bundled app (or a newer version of a company app is promoted), the app's page shows Update to v2 to admins. The demo starts on CRM version 1 so that you meet it there.

The update card, "Update CRM from v1 to v2", lists:

• What gets looser, first and in warn, when anything does (a rule removed or relaxed, a tool's risk lowered, a tool added, a row rule widened, a trigger added). Such an update waits for a second admin.
• What's new: the notes of each version.
• What changes for the app: collections, tools, rules, triggers and pages.
• Agent templates: changed, new ("new, with a copy made off and working for nobody") and retired ("retired; its copies keep working with what they have").
• The copies concerned: "2 copies of Sales Assistant can take v2 (changed: guardrails, steps)".

Update to v2 installs the app's new parts and records the new templates. It changes no copy: "CRM is at v2. No agent changed: each copy offers the update to whoever manages it." A tool the update removes is refused to the copies that still list it ("The CRM app no longer has calendar.create"), shown under Needs attention.

"v2 available"#

Each copy whose template changed then reads v2 available on its row and its page, for its managers and admins; the people who only use it see nothing. Update opens "Update Inbound Sales Assistant to Sales Assistant v2":

• What's new in v2, then a count: "2 changed in the template · 1 changed in both · 1 required · 6 the same".
• One row per section, with its state: Changed in the template, You changed this, Changed in both, Required by the template. Open a row for before and after (side by side, stacked on a phone).
• A section Changed in both needs a choice: Keep mine, Take the template's, or Edit. Apply waits until each has one.
• A required part reads Included with a lock and cannot be left out.
• A choice that would take out a guardrail says "Takes out a guardrail".
• Sections that are the same, or yours alone, fold at the end.

Apply (it reads Apply selected once anything stays yours) files the update as a change to the copy and runs its checks: "7 checks passed", or "1 check didn't pass" with Drop this check, Change what it expects and Ask an admin. With no model, "No AI model is set up, so changes wait for an admin." The update is reviewed as any change is. Once promoted the copy is at v2; a section you kept shows as "You changed this" against v2 next time.

Not now leaves the copy where it is; its row reads "v2 left". When v3 arrives the badge comes back, with the diff from where the copy is.

On a personal copy the owner first sees one button, Take the update, keep my changes: the template's parts where only it changed, the owner's where both changed, and every required part. Choose part by part opens the full sheet.

Automatic updates, required parts and many copies#

• Take template updates on its own when they only add (a copy's setting, off by default; on a personal copy only its owner sets it): an update that only adds guardrails, approval points and checks, or lines at the end of a section, is applied once its checks pass. Anything else waits. When the manager who turned it on loses the permission, it turns off.
• Required update: a copy that lacks a part its template now requires reads "Required update". An admin's Apply required parts to every copy files one change per copy with only those parts; personal copies wait for their owners' OK. For the copies left, the admin may pause them until updated or from a date, and their cards read "Running without a required guardrail since 9 Oct".
• Update every copy that can take it (holders, admins) files the update for every copy in your teams that has nothing changed in both and nothing that weakens it, and names the rest.
• Its source changed: a copy made from another copy (International from Inbound) is offered that copy's later changes the same way.

Pausing, archiving and restoring#

Pausing an app pauses every copy of its templates. See Policy, rules and kill switches.

A copy's row carries one state capsule, the first that holds: Archived, Paused by an admin, Paused, Needs attention (a tool removed, works for nobody, a required update past its date, its model not cleared for its data), Waiting to be turned on, On. "v2 available", "v2 left", "Required update", Change in review and "Its source changed" go on the second line.

The Agents tab#

Apps > Agents, and each app's Agents tab, list the copies you manage:

Search by name or owner, and filter by app, works for, and Update available, Private or Paused. Personal copies fold into one row a template ("Sales Assistant · 2 personal copies") that opens to their list, searched by owner, 50 a page. On a phone each row is a list row with its actions in the row's menu. With nothing made yet: "No copies yet. Make one from a template."

History#

A copy keeps two histories: its settings (each record version, who authorised it) and its behaviour (each promoted change, with the template version). GET /copies/:id/history lists both, newest first. Restoring a settings version writes a new version equal to the old one; restoring a behaviour version files a change through the pipeline.

Not possible yet#

• Setting a copy's approval rules, its trust tier, or keeping its limit as a one-time total, on the screen: the API only. The upgrade notice names Keep as a one-time total but has no button for it.
• A schedule section in the Make a copy sheet: add team schedules on the copy's page once it is made (Team schedules).
• A History tab for a copy on the screen; use the API.
• "Their manager" as the approver of a copy's rule, before storage version 5 (not_ready).
• Copies of the built-in agents and of the Context app's agents.
• Deleting a copy's history.

Known problems on this page#

• A holder does not see the ceilings. The Limits fields read "within the limits your admin sets" for a holder, not the ceiling itself, because the company's settings answer only admins; a limit above it is refused when the copy is saved ("monthly limit: up to $1000.00, set by your admin").
• Promote buttons on copies. The Directory's Promote to standard and Promote to trusted are refused for a copy with "sales-assistant's trust tier is set by the crm app; change it on /apps/crm", but the app's page has no trust field any more: an admin changes it with PATCH /copies/:id { "patch": { "trust": "trusted" } }.

For developers#

API#

All under /api, with Authorization: Bearer <token> (see Tokens).

A copy's record:

A patch may not null state, limits, rules or works_for (422). The app record's agents is refused from now on: "agents.sales-assistant: agent settings moved: change them on the agent (PATCH /copies/sales-assistant)".

Errors: 422 invalid with problems, evals_required, not_ready; 409 copy_exists, version_conflict, copy_setting, app_has_copies (ok pack install on an app with copies), not_copyable, proposal_open, copy_moved, id_reserved, required; 403 denied with the reason; 404 for a copy you may not see.

Events#

CLI#

The CLI works on the state file, with the server stopped:

S="--state orchkernel-demo/state.db"
ok $S --as eli template list --app crm
ok $S --as eli template show crm/sales-assistant --version 1
ok $S --as eli copy make crm/sales-assistant --name "Inbound Sales Assistant" --works-for team:sales --tools gmail.send --month 200.00
ok $S --as eli copy list --app crm --updates
ok $S --as eli copy show sales-assistant-inbound
ok $S --as eli copy set sales-assistant-inbound '{"limits":{"run_cents":50}}'
ok $S --as eli copy update sales-assistant-inbound --show          # the diff in words
ok $S --as eli copy update sales-assistant-inbound --take steps=mine,guardrails=template
ok $S --as eli copy update sales-assistant-outbound --leave
ok $S --as eli copy pause|resume|archive|restore <id> [--reason ...]
ok $S --as eli copy history <id>
ok $S --as ada app update crm            # the update card; --to 2 updates

ok agent library and ok agent fork <id> --slug acme still work: a fork is a copy working for nobody, made off. Output is the JSON the API answers.