AI Builder session
In the app: AI → Advanced → Builder → open a session
Needs the 'Edit AI Config' permission.
A Builder session is where you change an AI configuration by talking to the Builder. It has three tabs: "Chat" to describe what you want, "Try it" to test the draft as a customer, and "Draft Preview" to read and edit what the Builder wrote. "Save changes" and "Go live…" at the top right put the draft to use.
Session header
- "Back" returns to the list of Builder sessions.
- The session name: click it to rename the session. Enter saves, Escape cancels. The name can be up to 200 characters and identifies this Builder session.
- "Editing: …" names the configuration set the session works on and links to it. It is missing while the session is for a set that does not exist yet.
- The tabs "Chat", "Try it" and "Draft Preview". "Try it" and "Draft Preview" are disabled until there is a draft; hover to see why. "Try it" is also disabled while a draft is being written and while the draft is older than your latest messages.
A session is private to its current owner. Usually that is the person who started it. A session created by Squid Agent can be transferred to the teammate approving its proposal.
Chat
Describe how your support works: policies, tone, when to hand over to a person, how returns go. The Builder asks follow-up questions and writes a draft when it has enough. A message can be up to 20,000 characters.
- The config set bar above the conversation shows which configuration set the session edits and lets you switch to another one or choose "+ New config set…", which starts an empty set or a copy of an existing one. If the draft has changes that are not saved, "Unsaved changes" asks you to save or discard them first. The chip next to it shows the mode, with the store or the number of stores.
- While the draft is written the chat shows "Generating your configuration" and the message box is locked. This runs in the background: you can leave and come back. When it finishes, the "Try it" tab opens.
- If writing the draft fails, the conversation shows the reason and "Try generating again". Your previous draft stays until a new one finishes.
- "This message didn't get a reply" with "Retry this message" appears when a message was sent but not answered.
- The changes bar above the message box appears when the draft differs from what is saved. It counts added and removed lines and edited offers, with "Discard" and "Save". "Discard" asks "Discard changes?" and puts the draft back to the configuration set as it is saved; the conversation stays.
Two helpers sit above the conversation.
Insights are figures from real tickets answered with the configuration set the session edits. They cover the last 30 days, every store that uses the set and every earlier version of its prompts. The block is not shown for a new set, for a set no store uses yet, or when there is nothing to report. It can show up to three lines, each only when it has data:
- "AI handling rate": the share handled without escalation or an instruction to ignore the conversation, among conversations with a recorded AI reply, escalation or instruction to ignore. The counts shown also include all conversations the AI touched, which can be more than the percentage uses. Escalation takes precedence over ignoring, and ignoring takes precedence over a reply. "Left unanswered" counts instructions to ignore, not every conversation without a reply. "Top escalation reason" shows the most frequent reason and how often it occurred. A conversation counts once in the handling figures, however many replies it got.
- "Negatively rated AI messages": how many AI replies got an explicit thumbs-down.
- "QA reviews flagged negative": how many QA reviews scored at or below your organization's negative threshold, with the overall average score out of 5.
"Discuss with AI" puts a question about that figure in the message box. Nothing is sent until you send it, and the figures change nothing by themselves.
"Scenario coverage" checks whether the draft says what to do in common support situations. "Check what's missing" starts it; it runs in the background and you can leave the page.
- What is compared: the text of the draft's main prompt and of its specialists' prompts, against a fixed list of standard situations (returns, cancellations and so on). When stores use the set as their store-wide set, the return reasons of one of them are added to the list: the store whose AI settings were created first. The return reasons of the other stores that use the set are not added.
- What is not read: variables, tool settings and offers. A situation that is only answered in a variable can therefore be reported as missing.
- Each situation is marked covered, partly covered or missing, with a short reason. This is an AI judgement and can be wrong.
- For a situation that is not covered, "Answer →" shows a question; describe what the AI should do and "Send to builder" puts your answer in the message box. Nothing is sent yet: read it and send the message yourself to give it to the Builder.
- "Outdated — re-check" appears when the prompt text changed after the last check. "Re-check" runs it again.
The check needs a draft with prompt text. It is advice only: it never blocks saving or going live.
A draft can become out of date: when you keep talking after it was written, the page says the draft is behind the conversation, and saving, going live and testing are blocked until the Builder has applied your latest messages.
Reference material and your website
You can give the Builder material to work from. It is used for this session only.
- "Add reference text": paste text, such as a return policy, with a title.
- "Upload file": PDF, Word (.docx), plain text and CSV files, and PNG, JPEG, GIF or WebP images, up to 10 MB each. The text read from a file is cut off at 50,000 characters. A session holds at most 10 items. A file shows "processing" while it is read; you can send a message once it is done.
- Remove an item with the cross on its chip.
"Read your website" (for a multi-store session: "Read a website") reads published pages of a site: returns, shipping, FAQ and policy pages. Enter the address and click "Read my website" ("Read website" in a multi-store session, and "Read again" once a read has run). The pages found are listed; tick the ones the Builder may use and click "Use these pages and continue". You can add a missing page by pasting its address. "Hide this" puts the panel away; the pages you selected are still used. While no pages have been read, that button reads "Skip".
How the reading works:
- A public website address starting with http or https is accepted, in a single-store and in a multi-store session; it does not have to be the store's own site. The site must be on the standard web ports (80 or 443): an address with another port is refused. Addresses that point to a private or internal network are refused.
- Starting from the address, Squid follows links to pages that look like policy and help pages. When the session's store has addresses saved under "Store URLs" in AI Advanced settings, those pages are read too. When a topic such as returns or shipping was not found, it also looks in the site's sitemap.
- At most 12 pages can be in use in a session. A page gives at most 15,000 characters of text and a read gives at most 60,000 characters in total; a page that was cut short counts as partly read. Pages larger than 2 MB are not read. A read stops after about 30 seconds and keeps what it found.
- The read runs in the background. Reading again replaces the pages of the previous read.
- Only the readable text of a page is kept, and you can correct it before the Builder uses it. A page with no readable text is not used. A page that could only be partly read is not used until you review its text and choose "Accept this partial text".
- The pages are reference material for this session's Builder. They are not published to customers and are not searched by the live agent; what reaches customers is what the Builder writes into the draft.
While a draft is being generated, the pages cannot be edited. If you change the selected pages after a draft was written, "Save changes" is refused until the Builder has generated the draft again from the new selection.
A panel above the conversation also says which integrations are connected for the store, for example Shopify or ParcelPanel. The Builder does not propose a tool that needs an integration the store has not connected. In a multi-store session no store is checked, so every tool can be proposed; missing integrations are named per store when you go live.
Try it
"Try it" lets you write to the draft as a customer before you save it. The left side is the test conversation; the right side, "What your agent is", describes the draft in plain language: the topics it handles, the facts it uses, what it can do and whether it hands over to a person. "Open the raw prompts" jumps to "Draft Preview".
- The store bar, "Test against store": a test runs as one store, using that store's connected integrations, which the bar lists. A single-store session is locked to its store. In a multi-store session you pick a store for the test only; it does not assign the configuration set to that store.
- Channel buttons "Chat", "Email" and "WhatsApp" choose the channel the reply is written for. Switching after the first message starts the conversation over.
- Suggested questions come from what you told the Builder. When the Builder has none, five standard questions are shown.
- "Test as customer": an optional email address. With it, the agent is told who is writing, the way it is on a real ticket. It gets the customer's name and email address when the address belongs to a customer of your organization, and otherwise the address only. It gets the orders found in this store's Shopify for that address. It gets the customer's earlier conversations with this store only for a known customer, and only when customer history is included for the store's AI, which it is by default.
- "Start over" clears the test conversation.
Tests are safe: no reply is sent and no ticket is made. A fixed list of lookups runs for real against the store's own data: orders, tracking, refund status, the return address, products, return portal details, the order's age, handoff reasons and Google Sheets lookups. Actions such as refunds, vouchers, offers, cancellations, tags and supplier tickets are made up: they are shown as done in the test but nothing happens in the store. Tools outside the fixed list of lookups and the conversation decisions below receive stand-in results too. The built-in sample order uses made-up data, even when a lookup normally reads the store. Closing, snoozing, scheduling a follow-up, ignoring and handing over are also rehearsed: the test can report the decision or a refusal, but does not apply it to a real ticket. Test data is deleted automatically within 24 hours under the default retention settings.
A test does not copy two things of the live agent. It always acts as if the store sends replies itself, so tools that make changes are offered, as made-up runs, also for a store that saves drafts. And it always handles a return itself: the step where the live agent first sends a customer to the return portal is not tested.
Each message uses one of the organization's test runs, the same allowance as "Try it" on the Assistant page and the Playground. Once the allowance of the billing period is used up, each further test run counts as one AI message of your plan. A run that reaches the AI provider still uses a run if it produces no reply. A failure before it reaches the provider is refunded.
Policy answer checks
Below the summary, "Policy answer checks" compares one answer from the test conversation with website pages you read in and selected under "Read your website". It answers one question: does this answer contradict the source?
- Sources: the selected pages that were read in full, partly read pages you accepted, and pages from an older import marked "Completeness unknown". Tick up to three per check, together at most 40,000 characters. With no usable page, the panel asks you to import and review a source first.
- "Completed answer": the test answer to check. The test must have been run on the draft as it is now. After a change to the draft, run the test again and click "Refresh answers and sources". "Check this answer" starts the comparison.
- The result is "Supported by selected source", "Failed — contradiction found" or "Inconclusive — review needed", with a reason, the answer and the quoted source text. Only a contradiction that is shown with evidence counts as failed. Missing evidence, or a check that could not finish, is inconclusive.
- "Saved draft facts · assistant context" lists the draft's variables. They are what the assistant knows, not proof that an answer is right.
The comparison is made by AI and can be wrong; it judges that one answer only, not the whole configuration. A session keeps at most 20 checks; after the twentieth, a new check is refused until you work in a new session. Regenerating the draft in the same session does not reset this limit. A check made on an earlier version of the draft or of the sources is marked "Earlier version" and no longer counts.
Checks are optional: saving and going live do not require a check to have run, and an inconclusive result blocks nothing. A failed check that still applies does block. "Save changes" is refused until the failed check no longer applies, or an administrator overrides the failed checks with a written reason of at least 10 characters. A failed check stops applying as soon as the draft, the reference material or the store it was checked against changes; no new check is needed for that, so changing the draft alone removes the block without proving the problem is fixed. Only someone with the built-in Owner or Admin role can override, and the override is recorded with the reason.
Draft Preview
"Draft Preview" shows what the Builder wrote. "What the Builder made" at the top is a plain-language summary: the main assistant, the specialists, the tools that are switched on.
"Advanced — show the raw prompt, keywords and tool permissions" opens the editable draft:
- "Orchestrator Prompt": the main prompt of the agent and the tools it may use, as a list separated by commas;
- "Categorizer Prompt", when the draft has one;
- "Specialists": each with its name, a reference name, what it covers, when the main agent should call it, trigger keywords, allowed tools and prompt. "Add Specialist" adds one and the bin deletes one;
- "Variables": reusable facts with a title, a variable name and a value. A title is what the Assistant page shows under "Knowledge". "Add Variable" adds one;
- "Tool Permissions": per tool, its name and whether it is switched on. "Add Tool" adds a row.
"Edit" and "Changes" switch between the editable draft and a comparison with the configuration set as it is saved.
"Save draft" stores your manual edits in the session. It does not write to the configuration set and does not change what customers get. If someone else, or the Builder, changed the draft in the meantime, the save is refused and you are asked to reload.
A warning lists tools in the draft that need an integration the store has not connected; those tools cannot be put to use.
Save changes
"Save changes" writes the draft into the configuration set. It opens a dialog first:
- For a new set the dialog asks for a "Config set name" and is titled "Create config set?".
- "What you are saving" summarises the draft in plain language. "See exactly what changes (advanced)" lists the tools the agent may use, grouped into those that take action and those that only read data, and the line-by-line changes.
- "Check against store": the store whose integrations the draft is checked against. Saving does not change which stores use the set. A single-store set is locked to its store.
- "What goes live when" states the consequences. Read it before confirming.
What saving does:
- The prompts are saved and made active in the configuration set. Every store that already uses this set gets the changes from its next message. If the set uses version control, the changes go into its draft and reach customers with the next release instead.
- Specialists the draft adds are switched on. A specialist somebody switched off stays off.
- Tool settings apply at once to the set.
- Variable changes on a set that stores already use are saved as drafts unless you tick "Apply these variable changes to live traffic". Removing a variable cannot be held back as a draft: it takes effect at once, and the dialog asks you to confirm it. A removed variable that a prompt still refers to must be resolved first.
So saving is not a private draft step when the set is already in use: it changes what those stores' customers get. Saving into a set no store uses changes nothing for customers. After saving, a message says how many stores got the changes. Saving happens in two steps, writing the draft into the set and then making it active; if the second step fails, a message says the changes were written to the config set but are not live yet.
Saving is refused, with an explanation, when the configuration set was changed by someone else after the draft was written, when a variable changed in the meantime, when the draft is behind the conversation, when the website pages selected under "Read your website" changed after the draft was written, or when a policy answer check failed and was not overridden (see "Try it"). Ask the Builder to generate the draft again and save then. A variable conflict found after the prompts were written can leave those prompts saved while refusing the variable changes. If the draft uses tools whose integration is missing, the dialog offers "Remove these tools and commit anyway".
The button is disabled, with the reason shown, while there is no draft, while one is being written, and when everything is already saved.
Go live
"Go live…" makes a store answer from this configuration set and switches its AI agent on. Unsaved changes are saved first, through the "Save changes" dialog.
For a single-store session, "Review and go live" shows what is switched on. "Go live for store" is locked to the session's store. "Replies signed" holds the name the agent signs with: it shows the store's current name, or a suggested one when the store has none, and the name in the field is saved to the store when you go live. Going live points the store at this set, for the channel the session was opened for or for all channels, and switches the AI on. A store whose AI was off starts by preparing drafts: replies wait in your inbox for approval, and each draft uses an AI message from your plan whether or not you send it. A store that already sends replies automatically keeps doing so and answers from the new configuration set at once. This step does not ask for a passed test of the new configuration on that store, unlike turning on auto-send in AI Advanced settings. A store that has no mailbox a reply can leave from, for example because its sending domain is not verified, can still be switched on, and the dialog warns about it. Its AI email replies then stay as drafts and cannot be sent by hand either, until sending is set up under Settings → Email. If the store's AI is already on with another set, a warning says that moving it changes what its customers get.
"Go live…" is disabled once the set is already live for its store; from then on "Save changes" updates it.
For a multi-store session, a dialog lists your stores. Tick the stores this configuration set should answer for; each one switches to it and its AI is switched on. Each store shows what it uses now. Stores without a name for customers get the "Agent name" you type; stores that have one keep it. The dialog lists integrations a store is missing: such a store still goes live, and the tools that need the missing integration stay off for it. "Go live for … stores" confirms; a store that could not be switched on is reported with the reason and can be retried.
After going live, "Edit the stores using this config set" opens the configuration set's page, where stores are assigned and removed.
Drafts written by Squid Agent
A session that Squid Agent opened for you is marked "Read-only". You can read the conversation, test the draft and look at the preview, but not change it here: it goes live through its approval card in Squid Agent. "Open the Squid Agent thread" goes to that conversation.
"Continue in Builder" makes an editable copy of the draft that is yours. The approval card of the original closes, so the copy goes live only from the Builder. If Squid Agent read customer messages while writing the draft, you must tick a box confirming you checked the wording before you continue.