Core concepts
The mental model behind AISA: agents, configuration versions, the live version, conversations, conversation sources, and how ids are shaped.
This page defines the handful of terms the rest of the documentation assumes. Read it once before diving into Agents, Sites, or the API reference.
Agent
An agent is one configured AI Shopping Assistant in your organization. An agent has a type that selects its base persona, either Shopping assistant (the built-in shopping persona) or Custom (no built-in persona; everything comes from the version's own instructions), and belongs to one site. Your organization can have several agents, one per storefront role you need.
Configuration version
An agent's behavior lives in configuration versions, not on the agent itself. Versions read V1, V2, and so on, or the name you give them. Each save on a version records a new state of it and keeps the previous ones: a saved state never changes (its instructions, engine, connectors, chat tools, and capabilities are fixed), so you get a full history and can test a change before it's live. A version locks once it has been live: later changes go into a new version. See Configuration versions.
Live and offline
A version is Live when shoppers are served it: its agent is the one that answers on the site, and it answers with that version. Everything else reads Offline. One agent answers per site, with one version. A new agent starts with a V1 that has empty instructions. You can try it in the Playground at once, but it answers no shopper, and reads Offline, until a member puts it live. That includes the agent onboarding creates. Go live is the one gesture that changes what shoppers are served, with no downtime and no redeploy; Take offline stops the answering agent. See Put an agent live or take it offline.
Conversation
A conversation is one chat thread. It's pinned to the version that produced it, so a conversation started against V3 always shows V3's answers when you review it later, even after V4 goes live. Every conversation is tagged with a conversation source (below) and scoped to one organization.
Conversation source
The conversation source records where a conversation happened. The dashboard shows it as Source (a column, a filter, a line in a conversation's details). The REST API and the MCP server call it channel on a conversation and in the conversation search filter, and the MCP get_report tool lists the sources a report counted as channels. The value is one of three:
playground(shown as Playground): a team member testing an agent from the dashboard Playground.hosted(shown as AI Storefront): a shopper (or anyone with the link) using the site's AI Storefront, the/s/<site-key>page we host for it.web(shown as Web): a shopper using the assistant embedded on your storefront via the web tag.
Opaque ids
Every object the API returns carries an id like agt_01kvnwmagvf27rc9cze5rm9e1r or conv_01kvn…: a type prefix, an underscore, then an encoded value.
Identifiers are opaque
Treat every id as an opaque string. Store it as-is and pass it back unchanged.
Don't parse it, don't assume a fixed length or format, and don't derive
anything from it. The site_ / conv_ prefix is there to help you read it;
it's a human affordance, not part of the contract, and the format can change
without notice.
Introduction
What the iAdvize AI Shopping Assistant is, and how this documentation is organized.
Set up your first assistant
Onboarding is two steps, your organization and then your storefront address. It then reads your store, preconfigures an assistant you review, and ends in the Playground where you put it live.