SYNAPLAN // DOCS
Launch app

03 / Using Synaplan

Assistants

On this page 9

An assistant is a saved recipe: what the AI should do (instructions), with which models, using which knowledge, which tools and skills, and when it should act. 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 on by default since 4.8; an operator who switches the flag off gets the Instructions page back 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 that: it is owned, versioned, published through the same sharing model as folders and chats, and it can react to mail, a schedule, a website widget, or a coding tool — not only to someone starting a chat.

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.
  • A mailbox rule: when mail from @acme.com arrives, the assistant drafts a reply as you — write-class actions wait for approval.

The flags (operators)#

Gated by AGENTS.ENABLED (BCONFIG group AGENTS, owner 0). Since 4.8 the flag seeds on and the migration Version20260911090000 switched it on for installs created earlier. Two companions: AGENTS.ROUTABLE_ENABLED (the message sorter may answer with an assistant marked reachable from chat) and BUNDLE.ENABLED (export & import). All three live under Operate → System configuration → Features → AI assistants and apply without a restart.

Pin a value per deployment with the environment — the admin toggle then shows as locked and names the variable:

shell
FEATURE_AGENTS_ENABLED=false            # back to the Instructions page
FEATURE_AGENTS_ROUTABLE_ENABLED=false
FEATURE_BUNDLE_ENABLED=false

SQL still works for automation that talks to the database (BOWNERID = 0, group AGENTS, setting ENABLED, value '1' / '0'). With the flag off, Manage → Assistants → Assistants becomes Instructions (/ai/instructions; either URL redirects to the active one) and assistant rows stay in the database. Publishing to a group needs People & groups sharing (IAM.GROUPS_ENABLED + IAM.SHARING_ENABLED) on as well — also the default.

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.

Manage → Assistants → Assistants (/ai/assistants) lists cards with a status pill (Draft, Published, Archived) and filters: Mine, Shared with me, Archived. Actions per card: Start chat, Edit, Clone. Pin an assistant and it stays one click away from the composer.

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, knowledge, tools and skills — the router does not re-classify it.

The builder#

Create assistant (or Edit) opens a form with seven 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. Advanced settings folds in creativity, length, language and an optional response format
Knowledge Files in the assistant's own folder, optional shared folders you can already open, and Also search the person's own files (off by default)
Tools and skills Internet lookup, file search, connected apps (MCP), and which skills it may use (summarise, write a document, email you, …). Turn a skill off and the assistant refuses it with a clear sentence
Triggers When it acts — see below. Starting a chat in Synaplan is always on
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. Shared folders you add must already be shared with you; they are not copied into an export.

Triggers#

When should this assistant act? Starting a chat with it in Synaplan is always on. Add an event so it reacts when something arrives, or a schedule so it runs at a fixed time (shortest interval: 15 minutes).

Event What arrives
Mail arrives A mailbox you connect, optionally filtered by sender, keywords, or a department
Website widget A visitor writes in a widget bound to this assistant
WhatsApp A message on a number bound to this assistant
An app or coding tool Clients may pick it as assistant:{slug}
A connected app An MCP client may pick it
Synaplan Desktop The paired desktop app may pick it

Schedules are stored under Manage → Automations → Saved tasks and run as you. Mail rules also run as you. Actions that change something outside Synaplan wait for your approval (on by default).

Publishing names the triggers that will switch to the new version — not only the groups. Each event only binds or unbinds the channel it names; bindings you made on the widget or Channels page are left alone when the event is absent from the draft.

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.
  • 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.

Export & import#

With BUNDLE.ENABLED on (the default), Account → Preferences (/settings) shows Export & import for your own items, and Operate → System configuration shows the same panel for an instance-wide file.

  • Download your assistants and instructions as one synaplan-bundle.v1 file, or bring a file from another Synaplan.
  • Import creates drafts you can review. It never copies shares, keys, tokens or knowledge files.
  • A preview lists what the file needs (a model, a mailbox, a widget). Shared folders are dropped; you re-attach them after import.
  • Model bindings travel as portable service:providerId:tag keys, not raw database ids.

The flag is seeded on since 4.8 and sits under Operate → System configuration → Features → AI assistants; FEATURE_BUNDLE_ENABLED=false pins it off for a deployment. The API is POST /api/v1/bundle/export, /api/v1/bundle/preview and /api/v1/bundle/import.

A plugin may ship a ready-made assistant pack (provides.agents). Those appear after the plugin is installed; they follow the same draft → publish path.

↑↓ navigate↵ openEsc close