Core concepts
The mental model behind AISA: agents, configuration versions, champions, conversations, channels, 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. Each version is immutable once created (its instructions, engine, connectors, chat tools, and capabilities are fixed), so changing how an agent behaves means creating a new version, never editing one in place. This gives you a full history and lets you test a change before it's live.
A version has a status: draft (playground-only), candidate (lined up for future A/B testing), champion (live), or archived (history, reached by being replaced or archived directly). See Configuration versions for the full lifecycle.
Champion
The champion is the one version currently live: the configuration that actually answers shoppers. An agent has at most one champion at a time. A new agent starts with a v1 champion that has empty instructions, so it's usable immediately; promoting a different version to champion is what makes a change go live, with no downtime and no redeploy.
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 the champion moves on to v4. Every conversation is tagged with a channel (below) and scoped to one organization.
Channel
The channel records where a conversation happened:
playground: a team member testing an agent from the dashboard Playground.hosted: a shopper (or anyone with the link) using the site's public link, the standalone/s/<public-key>page.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.