Instructions
Write and manage the reusable, typed instruction blocks that agent versions on a site compose into their system prompt.
Instructions are the site-wide, reusable content that agent versions select and compose into their system prompt. They replace the single free-text field a version used to have. Write a block once and select it on as many of the site's agent versions as you like; editing a block never silently changes a version that's already live (see Instructions and versions below).
Open a site, then Instructions in the dashboard sidebar's Assistant group for the list of its blocks, or go to /dashboard/sites/<siteId>/instructions.
Editing instructions requires a permission
Viewing this list requires the Agents: View permission; creating, editing, or deleting a block requires Agents: Edit. Both built-in roles, Admin and Member, have this by default. See Roles to check or grant it on a custom role.
Blocks are typed
Every block has a type, fixed forever once you create it:
| Type | Behavior |
|---|---|
| Always active | Its text is composed into every conversation's system prompt, unconditionally. |
| Conditional | Not injected into the prompt. Instead the assistant gets a tool for the block (named instructions_ plus the block's slug), described by its condition text, and calls it only when that condition matches the conversation. |
There's no path to change a block's type after creation: if a block needs to become the other kind, create a new one instead.
The Général block
Every site gets one mandatory block named Général, created automatically the moment the site itself is created. It's Always active, its name can't be changed, and it can't be deleted: every agent version's block selection is forced to include it. It starts empty; type your general instructions into it the same way you'd have typed into the old single instructions field.
The list
The Instructions page is a table of the site's blocks: name with its internal description beneath it, a type badge, a created by badge (Member or Optimizer, the latter reserved for a future self-improvement engine, not shipped yet), the revision count, and when it was last updated (the date of its newest revision). A block's technical slug isn't shown in the table.
Above the table:
- Search matches, case-insensitively, on a block's name and description only, not its slug, and not its instruction text.
- The type dropdown next to it narrows the list to Always active or Conditional. It combines with the search.
- New instruction opens the create form (editors only).
Three column headers sort: Type, Revisions, and Updated: click one to sort, click again to reverse. The list starts on Updated, newest first. Name and Created by don't sort: search covers names, and Created by only ever holds two values. Type sorts on the underlying value rather than the translated label, so its order is the same whatever language your dashboard is in, not alphabetical in French or German.
Search, filtering, and sorting all happen in your browser over the site's full block list: no page reload, and nothing lands in the URL, so a filtered list isn't a shareable link.
Create or edit a block
From the list, open New instruction, or click an existing block's row (or its ⋯ → Edit) to open it.
Set a name (up to 80 characters); the slug sits on the same row and auto-fills from the name; you can adjust it before the first save, but neither the slug nor the type can change once the block is created. The description below them is optional (up to 200 characters) and internal: shoppers never see it. Pick Always active or Conditional.
If the block is Conditional, optionally write its indicator message: what shoppers read during the pause while this block loads, per language. See Indicator message.
If the block is Conditional, fill in its condition (up to 500 characters): the trigger criterion the assistant reads to decide whether to call it, e.g. "The shopper asks about returns or refunds." This isn't shopper-facing text; write it like a tool description, not prose.
Write the instruction itself (up to 3,000 characters): a direct directive to the assistant, e.g. "Always mention the 30-day return window when a shopper asks about returns." On an existing block, editing content here doesn't overwrite anything: saving appends a new revision (see Revision history), and you can add an optional reason for the change.
Save. Creating a block also creates its first revision; on an existing block, saving updates the name, description, and indicator message immediately and, only if you changed the instruction or condition, appends a new revision.
The instruction and condition fields show a live character count at their bottom right, so you can see how close you are to the cap. Optional fields (description, indicator message, and the change reason) carry an Optional badge beside their label.
Indicator message
A Conditional block loads mid-conversation, which shows up to the shopper as a short pause. The indicator message is what they read during that pause, in their own language, for example "Loading the size guide" while a size-guide block loads. It's optional and only exists on conditional blocks; an always-active block has no pause to name.
- One phrase per language your site has enabled, each up to 80 characters. Switch language tabs to fill them in; a dot on a tab marks a language that already has a phrase.
- Leave a language blank (or leave the whole field empty) and shoppers in that language see the standard "Thinking…" phrase instead. They never see another language's phrase, and never the block's name or slug.
- Generate with AI doesn't write it: AI assistance covers the instruction and condition only. Each language's phrase is yours to type.
The language used is the one the conversation is rendering in: on the public link and the embedded tag, the shopper's browser language matched against your site's enabled languages, falling back to the site's default; in the playground, the Test language you selected.
Where shoppers see it: the hosted public link, the embedded web tag, and the playground in User view. It does not appear in the playground's Technical view or in a saved conversation's transcript under Conversations. Both show the raw tool call instead, on purpose. It's also absent from an agent version's read-only page, which only shows what that version pinned; the block editor is the one place to read and write it. And if two tools happen to run at the same time, the generic "One moment, checking that for you…" phrase wins over your phrase: only a single running step gets a specific one.
The indicator message is not versioned
Unlike a block's instruction and condition, the indicator message lives on the block itself. Saving it appends no revision and mints no agent version, so it takes effect immediately for every agent version that selects the block, including your live champion. That's deliberate (fixing a typo in a five-word label shouldn't cost you a new version of every agent), but it also means the change reaches shoppers with no history of who changed it or when, exactly like editing a block's name or description.
Removing a language from your site's enabled languages deletes that language's indicator message from every block on the site; see Languages.
Generate with AI
Both the create and edit forms have a Generate with AI (create) or Update with AI (edit) button. Create mode asks for a plain-language description of what you want and drafts a fresh instruction (and condition, for a conditional block) from it. Edit mode asks what should change and adjusts your existing text rather than replacing it outright. It doesn't reprint your current instruction, which stays visible in the form behind the dialog. Either way the draft only fills the form fields: nothing is saved until you review it and click Create block / Save yourself. It never touches the indicator message.
Revision history
Editing an existing block's content never overwrites it: it appends a new, numbered revision. The block's edit page shows the full history alongside the form: newest first, each with its revision number, a Member or Optimizer badge, the date, and your reason if you gave one (or "No reason given"). The revision's instruction text and condition sit behind a Show content toggle, collapsed by default, so a block with a dozen long revisions stays readable. Expand the one you want to inspect. Every version that already pinned an earlier revision keeps reading it; see Instructions and versions.
Author a block from the editing surface
You don't have to come to this page to write a block. The Instructions tab of an agent's shared editing surface has the same instruction picker, and it can create a block, or edit one it already selects, in a side panel over the version you're building:
- New instruction opens the same authoring form in a panel. Saving persists the block on the site and adds it to the draft's selection, pinned to its first revision.
- The pencil button on a selected block's row opens that block for editing. Saving appends a revision as usual, and re-pins this draft to the revision you just wrote, so the version you're building carries what you just typed. Blocks the draft doesn't select have no pencil: a revision on one of those would change nothing here.
- Generate with AI works from the panel too, as a dialog on top of it. Closing that dialog returns you to the panel with your fields intact; closing the panel doesn't save or reset the version draft behind it.
Two things to know. The panel shows no revision history and offers no delete: both stay on this page. And a block you create there is saved immediately: abandon the version draft afterwards and the block is still in the site's Instructions list (delete it from here if you don't want it).
Test a block
There's no per-block test button. To try a block against the live model, either:
- Open the Playground and pick the agent and version you want to test. The version has to select the block for it to apply, and a conditional block only fires when the assistant judges its condition matched.
- Or author the block from the editing surface (above) and save that version as a draft, then test that version in the Playground.
To preview a conditional block's indicator message you need the playground's User view; Technical view shows the raw tool name instead.
Delete a block
From the list's ⋯ menu, Delete soft-deletes a block: it disappears from the picker for new versions, but any version that already selects it keeps working exactly as before. The confirmation dialog names any of the site's agents whose live champion currently references the block, so you know before confirming whether shoppers would be affected by a future version change. Deleting itself doesn't touch a champion. Général has no delete option.
Instructions and versions
An agent version selects which of the site's blocks it uses and in what order, pinning the exact revision of each at creation time. Editing a block here (even its live champion's) never changes what that champion serves; the new revision only reaches shoppers once a version is created (or updated to that revision in the picker) and promoted. See Configuration versions for how the picker works.
Three fields are the exception, because they aren't part of a revision: a block's name, its description, and a conditional block's indicator message. Those are read live, so editing one applies everywhere at once, including to versions already in front of shoppers.
Configuration versions
How an agent's configuration is versioned, what each status means, and how to create, promote, or archive a version.
Chat tools
The built-in tools an agent version can call (product cards, clarifying questions, quick replies, web search, and page reading) and how to choose them per version.