Agents

An agent is one configured AI Shopping Assistant in your organization. You can have several. Each agent keeps its configuration in versions, so you can change how it behaves without losing what came before, and test a change before it goes live.

Open Agents in the dashboard sidebar. If the current site already has at least one agent, this takes you straight into its workspace (no detour through a list): your only agent, the agent that answers on your site, or, failing that, its most recently created agent. A + icon next to the sidebar item lets you create another agent from anywhere, without opening a list first. It shows up for anyone holding Agents: Edit.

To see every agent on the site instead of being sent to one, or when the site has none yet, go to /dashboard/sites/{siteId}/agents. That page also adapts to how many agents the site has: a create prompt with none, a straight redirect into the workspace with exactly one (the same shortcut the sidebar takes), and the full table below with two or more. To look the same data up from outside the dashboard, see the API reference.

How agents workCopy Anchor Link

• An organization has many agents. Each agent has a type that selects its base persona: Shopping assistant (the built-in shopping persona) or Custom (no built-in persona at all: everything the agent does comes from its version's own instructions).
• An agent's configuration lives in versions. Each version has its own instructions (extra guidance layered on top of the type's base persona) plus which connectors, chat tools, and capabilities it can use. The type also decides a new version's default chat tools: all four for Shopping assistant, none for Custom; capabilities always default off, for every type. See Configuration versions.
• A new agent starts with a V1 that has empty instructions. You can try it in the Playground at once and keep saving on V1, but it answers no shopper until you put it live. This holds for every new agent, whether New agent, onboarding, Create site or the REST API created it.

Create an agentCopy Anchor Link

The agent detail pageCopy Anchor Link

An agent's detail page has three tabs: Identity, Capabilities and Instructions. The header above them is the same on every page of the agent (see The header below).

The three tabs are one shared editing surface, not three separate pages: landing on any of them means editing the agent's configuration directly, with no separate "start editing" step. Switching between them never loses what you've typed, since all three share one form. See Configuration versions for what each tab groups and how saving works.

Beside the form, a card links to the Playground to test the agent. The editor has no live preview of unsaved changes yet: the Playground tests a saved version, selected by name. See Configuration versions.

There's no Versions tab. The versions page, with every version and the change history, opens from All versions in the header's name menu. An old link to the agent's evaluation address (/dashboard/sites/{siteId}/agents/{id}/evaluation) opens the editor or, for a member without Agents: Edit, the agent's page.

Opening an agent (from the agents list, from a conversation, or right after creating one) lands you on Identity. Without the Agents: Edit permission you can't open the editing surface: you land on the versions page, the page shows no tabs at all, and each version in the name menu opens its read-only page. If you reach Identity, Capabilities, or Instructions anyway, through an old link or a typed address, the page keeps the agent's header and says "You don't have access to this section. Ask an administrator for access." instead of loading the editor.

There's no Playground tab and no Activity tab here. To test a version against the live model, use its Playground action from the versions page's ⋯ menu or from a version's own read-only page. Both open the standalone Playground with that exact version pinned. Which agent answers on the site and its AI Storefront changes with Go live. See Put an agent live or take it offline.

The headerCopy Anchor Link

From left to right: a back arrow to the agents list, the agent's name as the page title, and a Live or Offline chip. On the right: the actions for the page you're on. The header stays at the top of the page while you scroll, so the actions stay in reach on a long tab.

The name is a menu. Click it for:

• Rename agent: turns the title into a text field. Press Enter (or the check mark) to save, Escape to cancel. The name is an internal label for your team; shoppers never see it (see Public identity).
• Rename this version: opens a dialog to name the version on screen. Leave it empty to show the number again.
• Copy ID: copies the agent's ID, shown under the label so you can check it first. You need it for the API.
• Versions: up to five versions, the live one first, then the most recent. Each reads as its number (V1, V2…) or its name, with a dot for live or offline, and the one the page is showing is marked On screen. Click one to open it in the editor, on its latest saved state. With unsaved changes, the editor asks before it replaces them (see Reload and switching versions ask first). All versions, always there, opens the versions page.
• Delete agent…, set apart at the bottom. See Delete an agent.

Without the Agents: Edit permission the menu offers only Copy ID and the versions.

The chip shows the status of the version on screen, not of the agent as a whole: Live when shoppers are served that version, Offline otherwise. On Identity, Capabilities and Instructions it describes the version you're editing. On a version's read-only page it describes that version. The versions page shows no chip.

The actions depend on the page:

• On Identity, Capabilities and Instructions: Unsaved changes (with an amber dot) while you have edits that aren't saved, then Save, which opens Save on V2 and Save as a new version (see Save), then the live controls described in Put an agent live or take it offline.
• On a version's read-only page: Playground, and, with Agents: Edit, Start a new version from it, then the live controls.
• On the versions page: none.

The agent's type doesn't show in the header: it can't change after creation.

Switching between agentsCopy Anchor Link

When the site has two or more agents, opening any one of them shows a selector column beside the tabbed workspace: every agent on the site, by name, plus a New agent action in its own footer. Pick another agent to switch straight into its workspace: no trip back through the agents list. This column isn't shown on a single-agent site (there's nothing to switch to) or on the agents list/table page itself.

Public identityCopy Anchor Link

By default, a shopper sees a generic assistant icon and the label "Assistant" (translated into whatever language the chat is running in), never the agent's internal name, which is an admin-only label (often a technical identifier, not something meant for a shopper).

To give an agent its own face and name, open its Identity tab and use the avatar and display name fields:

• Avatar: upload a PNG, JPEG, or WebP image, up to 2 MB. Shown as a circular avatar. A refused upload says why: the wrong file type, a file over 2 MB, no permission to change it, or an upload that failed and can be retried. With no avatar set, the field is a drop area titled Upload an avatar: click it or drop a file on it. With an avatar set, the field shows the image with Replace (pick another file, or drop one on the image) and Remove. The file uploads as soon as you pick it (you don't wait for it on save). Remove falls back to the generic icon and brings the drop area back; the uploaded file itself is kept, not deleted, since an earlier configuration version may still reference it. On a version's read-only page the field shows the image alone.
• Display name: a single name up to 40 characters per language the site has enabled, required in every one of them. With only one language, it's a plain field. With two or more, a compact language list before the field shows the code of the language on screen (EN); open it to switch language. It lists every language by code and name, your site's default language first, marked Main, and shown when the form opens. The editor fills every empty language with a base text ("Assistant" in English and French, "Assistent" in German) as an unsaved change, and refuses to save while a language is empty. See Text in several languages.

With two or more languages enabled, a Translate into the other languages button sits under the display name once the language shown in the list has text. One click translates that name into every other enabled language and replaces what they held, base text included. A toast offers Undo for 8 seconds. Nothing is saved until you use Save in the page header. A translation over 40 characters is shortened once by the model; if it is still over, the field is marked and Save is refused with a toast ("Over the 40 character limit. Shorten it to save.") until you shorten it. The same button sits under the welcome message, with a 200-character limit.

The avatar is optional; the display name is required in each language. Both behave like every other field on the Identity/Capabilities/Instructions editing surface: they live on a configuration version, not on the agent directly, so nothing is saved until you use Save in the page header, and nothing reaches shoppers until that version goes live.

The Identity tab starts from the identity of the version you're editing. A version that isn't live can carry a different name and avatar than the live one, the same guarantee every other version field has: nothing a shopper sees changes until that version goes live.

Editing these fields requires the Agents: Edit permission, same as the rest of this page. A version created before identity was versioned shows a note on its read-only page that its identity was copied in by a one-time migration rather than configured by a merchant for that version.

Removing a language from the site's enabled languages also deletes that language's display name from every agent on the site, alongside the existing welcome-message cleanup and that language's starter-question text, behind the same confirmation. Starter questions that AISA generated from your pages are part of that library: they start switched off (unless the site switches generated questions on), and the version's Show starter questions switch shows none of them until you switch them on.

Put an agent live or take it offlineCopy Anchor Link

One agent at a time answers on your site: it's the agent shoppers talk to through the web tag and the site's AI Storefront, and it answers with one version, its Live version. Every other agent, and every other version, reads Offline. A new site has no agent answering: its onboarding agent starts offline, and onboarding ends on its Go live confirmation.

The agents list shows which agent answers: an Answers on your site badge, and Live in its Status column, where every other agent reads Offline.

Go liveCopy Anchor Link

Go live is the one gesture that changes what shoppers are served. It puts a version live and makes its agent the one that answers on the site. You find it:

• in the editor header, next to Save, while the version you're editing isn't live;
• in the header of a version's read-only page;
• in a version's ⋯ menu on the versions page;
• on the agent's overview page (/dashboard/sites/{siteId}/agents/{id}/overview), for an agent that doesn't answer. There it puts live the agent's last live version, or its most recent one if it was never live, and the confirmation names it.
• in the Playground, on the Not live yet bar, when you arrive there at the end of onboarding.

An agent that was never live shows Not live yet next to Go live in the editor header, on a version's read-only page and on its overview.

Go live sends the version's latest saved state and never saves. In the editor it's blocked while you have unsaved changes, with "Save your changes first. Going live sends the last saved version." Save first, then go live.

A confirmation names what goes live and what it replaces:

• No agent answers yet: the agent starts answering shoppers on the site with that version.
• Another agent answers: that agent stops answering on the site, and shoppers talk to this one from now on. The agent it replaces reads Offline. Its versions stay in its history.
• This agent already answers, with another version: the new version replaces the live one, which stays in the history.

Every confirmation says whether the site's tag was seen in the last 7 days: Tag activity was seen on site in the last 7 days., or No tag activity detected on site in the last 7 days. Shoppers see the assistant once the tag is installed. with an Install the tag link to Site settings → Installation. It counts the hourly homepage check finding the tag and activity the tag recorded on your pages. No activity doesn't mean the tag is missing (a quiet week reads the same), and it never blocks Go live.

Every confirmation also adds that, once live, the version is kept as it is: it locks, and later changes go into a new version. Going live with the version that's already live changes nothing.

Under that, the confirmation shows what you know about the version, without blocking anything:

• Tried in the Playground, or Not tried in the Playground yet: whether someone has chatted with any saved state of the version in the Playground.
• Evaluated: only when an earlier evaluation measured a pass rate for this saved state. The dashboard does not offer to launch an evaluation from here.

The version goes live under the name it already has. The dialog has no name field: to change it, use Rename this version or name the version from the versions page.

A version opened on an earlier saved state, from the change history, shows the confirmation without these lines.

Go live is refused, with the reason on screen, when the version isn't ready:

• the site has no enabled language: enable one in the site's languages;
• a connector the version uses was deleted, or an instruction block it uses was deleted: start a new version without it.

Going live takes Agents: Edit. When it changes which agent answers on the site, it also takes Sites: Edit, the same permission as the site settings. Going live with another version of the agent that already answers needs only Agents: Edit.

The Live buttonCopy Anchor Link

While the agent answers on the site, a green Live button sits in the header (it reads V3 live when another version than the live one is on screen). Its menu says where and with which version the agent answers, and since when ("Answers on Demo Storefront and its AI Storefront with V3 since…"), then holds:

• View on site: opens the site's address in a new tab.
• Take offline…: needs both Agents: Edit and Sites: Edit.

Take offlineCopy Anchor Link

Take offline… stops the agent answering. The confirmation says what stops: shoppers on the site stop getting answers, and when the site has live engagement widgets, how many stop showing. Confirm with Take offline.

Afterwards no agent answers on the site:

• the web tag shows no widget, and the engagement widgets pages say so;
• the AI Storefront returns a not-found page.

No version changes: the version that was live stays in the history and reads Offline. To bring the agent back, Go live again, with that version or any other.

History and APICopy Anchor Link

Each gesture is recorded in Admin activity as Agent went live or Agent taken offline. Renaming a version is recorded as Agent version renamed.

The same gestures exist in the REST API: Put a version live, Take the answering agent offline and Rename a version. The MCP server reads statuses but can't change them.

Delete an agentCopy Anchor Link

Delete an agent from either of two places:

• In the agent's workspace: click the agent's name in the header, then Delete agent…. Once deleted, you're sent back to the agents list.
• In the agents list, at /dashboard/sites/{siteId}/agents: the agent's ⋯ menu.

Both ask you to confirm first, and both need the Agents: Edit permission. It's a soft delete: the agent disappears from every list, but its versions and conversations are kept: the transcripts you've collected aren't destroyed. The deletion can't be undone from the dashboard.

The agent that answers on your site can't be deleted on its own, since the tag and the AI Storefront would have nobody to serve. From either place, its delete dialog asks for the Agent that takes over first. It offers every other agent of the site whose version Go live would put live (its last live version, or its most recent one) is ready to go live. Replace and delete puts that agent live with that version, then deletes the other one. This needs both Agents: Edit and Sites: Edit. When no other agent can take over, or your role lacks Sites: Edit, the dialog explains why and only offers Cancel.

The site's only agent can't be deleted while it answers, whatever your permissions: no other agent could take over. Its dialog says "This agent answers on your site and is the only one. Take it offline or create another agent first, then delete this one." and offers Create an agent next to Cancel. Once you've taken it offline, it no longer answers and deletes like any other agent. Once another agent has a version ready to go live, you can pick it as the agent that takes over.

The server refuses it too: deleting the answering agent through DELETE /api/v1/sites/{siteId}/agents/{id} returns a 409 with the code agent_answers_on_site, and nothing is deleted. Its detail says whether the agent is the site's only one. To delete it through the API, put another agent live first, or take this one offline.