Assistants

An assistant is a saved recipe: what the AI should do (instructions), with which models, using which knowledge. Whoever builds one can publish it to a group or to everyone on the instance, keep improving it, and every user always talks to the current published version. Users can clone a published assistant and make it their own.

Assistants replace the older Instructions page (/ai/instructions). They are off until an operator turns them on; with the flag off, Instructions works exactly as before.

Why this exists

A prompt topic under Instructions had a system prompt, a model and a knowledge folder — but it belonged to one person, had no versions (editing changed the live prompt for everyone), and could not be handed to "Support" only. An assistant fixes all three: it is owned, versioned, and published through the same sharing model as folders and chats.

Use cases:

  • A support assistant with the product manual as knowledge, published to the Support group. The owner refines the instructions and publishes v2; agents get it on their next message.
  • A tender-writing assistant for one department, with the house style in its instructions and past tenders in its folder.
  • A personal draft you try in the builder for a week before publishing anything.

Turn assistants on (operators)

Gated by AGENTS.ENABLED (BCONFIG group AGENTS, owner 0, seeded 0). It is not yet a switch in System configuration; set it in the database:

INSERT INTO BCONFIG (BOWNERID, BGROUP, BSETTING, BVALUE)
VALUES (0, 'AGENTS', 'ENABLED', '1')
ON DUPLICATE KEY UPDATE BVALUE = '1';

Reload the app. Manage → Instructions becomes Manage → Assistants (/ai/assistants; the old URL redirects). Rollback is the same statement with '0'; assistant rows stay in the database. Publishing to a group needs People & groups sharing (IAM.GROUPS_ENABLED + IAM.SHARING_ENABLED) on as well.

Optional: php bin/console app:agents:seed-system turns the seeded system prompts into published system assistants that everyone can use. It is idempotent and is not part of app:seed.

The gallery

Manage → Assistants lists cards with a status pill (Draft, Published, Archived) and filters: Mine, Shared with me, Archived. Actions per card: Start chat, Edit, Clone.

Start chat opens an empty chat pinned to that assistant. The chat shows "Talking to {name}", offers up to three starter prompts (Try one of these), and every message in it runs with the assistant's instructions, models and knowledge — the router does not re-classify it.

The builder

Create assistant (or Edit) opens a form with five sections. Changes are saved to your draft; nobody else sees a draft.

Section What you set
Basics Name, description, greeting, starter prompts (Add starter)
Instructions The system prompt. People chatting with the assistant never see this text
Models Chat, vision and search model — or Use my default per capability
Knowledge Files in the assistant's own folder (Add a file), How many passages to use, Minimum match
Publish Changelog, Publish, Share, Archive / Restore, Delete, version list and usage

Try a draft in the sidebar streams an answer from the current draft in an incognito test chat — it does not appear in your history.

Knowledge files are only used when someone talks to this assistant. The person chatting runs under their own budget, rate limits and memories; the assistant's knowledge is the owner's and is read-only for them.

Publish, versions, archive

  • Publish snapshots the definition and the instruction text into an immutable version and makes it the one everyone uses. Add a changelog line so the version list stays readable. Publishing an unchanged draft is refused ("Nothing changed since the last version").
  • Users always run the latest published version. The owner keeps editing the draft; nothing changes for users until the next publish. "People who can use this assistant will get this version on their next message."
  • Archive hides the assistant from new chats; open chats keep working. Restore brings it back.
  • Delete is offered for drafts and archived assistants.
  • Versions and Usage (per version, per day; no user identities) are listed in the Publish section.

Share and clone

Share is available once a version is published. It is the same dialog as for folders and chats — a person, a group, or everyone on this instance — with Can view (see and clone), Can use (start chats), Can edit (change the assistant). Recipients find it under Assistants → Shared with me. Ownership never moves; see People & groups.

Clone copies the published definition and instructions into a new draft you own ("Copied as a new draft"). Knowledge files are not copied — the clone starts with an empty folder of its own. Anyone with at least Can view may clone; the owner may clone an unpublished draft.

Not yet

Tools, skills and triggers (mail rules, schedules, widget binding) are planned builder sections and are not in the UI yet. The From plugins filter is present but empty until plugin-shipped assistants land. A shared folder picker for knowledge is not in the builder yet — an assistant's knowledge is its own folder.

Related pages