Storefront Assistant

Storefront Assistant is an AI chat for logged-in Storefront customers. It answers shopping questions only from the shop catalog and streams each answer to the browser as Server-Sent Events (SSE).

For the business overview, see Storefront Assistant.

Architecture

Storefront Assistant runs in the Yves application. The chat logic, the agents, the tools, and the call to the AI provider run in the Client layer, inside the Yves process. Zed does not call the AI provider. Zed only loads the AI configuration and the conversation history, saves the conversation, and writes the audit log.

For each chat turn, the following happens:

1. The browser sends POST /shopping-assistant/prompt with the message, the conversation reference, and the page context.
2. The controller validates the request and opens an SSE stream.
3. The agent selector picks one agent for the turn. For details, see Agent selection.
4. The agent calls AiFoundationClientInterface::streamPrompt() with its system prompt and tool names.
5. streamPrompt() asks Zed for the AI configuration and the conversation history.
6. The Client calls the AI provider directly and runs the tools of the model in the Yves process.
7. While the model answers, the SSE plugins write the text, the reasoning, and the tool events to the stream.
8. The Client saves the turn in the chat history through Zed.

For details on how streamPrompt() sends the model output, the tool calls, and the conversation history, see Stream AI responses with the AiFoundation module.

The browser keeps only a small state in localStorage under the storefront_assistant_state key: isOpen, isExpanded, conversationReference, userSelectedAgent, and activeAgent. The browser does not keep the messages. It loads them from the server on each page load.

Agents

An agent is a plugin that has its own system prompt, tool list, and Back Office toggle. For the shipped agents, their tools, the registration, and the agent selection rules, see Storefront Assistant agents.

SSE plugins

The following Client plugins write the stream events. They are registered in the Client AiFoundationDependencyProvider:

These plugins implement the AiFoundation streaming plugin interfaces. For the plugin contract, see Stream AI responses with the AiFoundation module.

The SSE plugins send events only for the AI configurations that AiCommerceConfig::getStorefrontAssistantSseAiConfigurationNames() returns. A turn on any other AI configuration streams only start, data-agent, finish, and [DONE].

Endpoints

StorefrontAssistantRouteProviderPlugin adds the following routes:

Requests with a CSRF header must send the X-CSRF-Token header with a token for the storefront_assistant token ID. The widget reads the token from the page.

All endpoints require a logged-in customer. When the Enable Storefront Assistant setting is off, all endpoints return 404.

Prompt request

The body of POST /shopping-assistant/prompt is a JSON object:

{
  "message": "Show me cameras under 500 euros",
  "conversationReference": "c_7f3a9b",
  "selectedAgent": "product_discovery",
  "pageContext": { "pageType": "category", "categoryName": "Cameras", "filters": ["Canon"] },
  "attachments": [{ "mediaType": "image/png", "content": "<base64>", "name": "photo.png" }]
}

Stream protocol

The prompt endpoint follows the AI SDK UI Message Stream Protocol. This lets you replace the shipped widget with any client that understands this protocol.

A successful stream has the following response headers:

Part types

The server follows these rules:

• Each turn has exactly one start part and one finish part.
• Only one text or reasoning block is open at a time. A new block, a tool call, or an error closes the open block first.
• Each block id is unique in the turn, for example text_1, reasoning_2, text_3.
• The tool-input-* and tool-output-* parts of one call have the same toolCallId.
• A research tool, such as catalog_search, sends tool-input-* parts but no tool-output-* part. The widget uses the input parts only for the progress label.

The server does not send these protocol part types: start-step, finish-step, tool-input-delta, source-url, file, and abort.

Example stream

The customer sends “Show me cameras under 500 euros”:

data: {"type":"start","messageId":"msg_6703a1f2b4c5d"}

data: {"type":"data-agent","data":{"name":"product_discovery"}}

data: {"type":"reasoning-start","id":"reasoning_1"}

data: {"type":"reasoning-delta","id":"reasoning_1","delta":"The customer wants cameras with a price limit of 500 EUR."}

data: {"type":"reasoning-end","id":"reasoning_1"}

data: {"type":"tool-input-start","toolCallId":"call_a1b2c3d4","toolName":"catalog_search"}

data: {"type":"tool-input-available","toolCallId":"call_a1b2c3d4","toolName":"catalog_search","input":{"query":"camera","priceMax":50000}}

data: {"type":"tool-input-start","toolCallId":"call_e5f6a7b8","toolName":"display_products"}

data: {"type":"tool-input-available","toolCallId":"call_e5f6a7b8","toolName":"display_products","input":{"idProductAbstracts":[201,204,210]}}

data: {"type":"tool-output-available","toolCallId":"call_e5f6a7b8","output":{"result":"{\"products\":[{\"idProductAbstract\":201,\"name\":\"Canon IXUS 160\",\"sku\":\"201\",\"url\":\"/en/canon-ixus-160-201\",\"priceFormatted\":\"€349.00\",\"rating\":4.5,\"reviewCount\":12}],\"displayedCount\":3,\"refinementChips\":[{\"label\":\"Canon\",\"filterArgument\":\"filters.brand\",\"value\":\"Canon\",\"matchCount\":5}],\"seeAll\":{\"totalResults\":18,\"queryString\":\"q=camera&price%5Bmax%5D=500\"}}"}}

data: {"type":"text-start","id":"text_2"}

data: {"type":"text-delta","id":"text_2","delta":"These three cameras fit your budget. "}

data: {"type":"text-delta","id":"text_2","delta":"Narrow by brand to see fewer models."}

data: {"type":"text-end","id":"text_2"}

data: {"type":"finish"}

data: [DONE]

The values in this example are illustrations. The field names are the real names.

A failed turn, for example without an API token, looks like this:

data: {"type":"start","messageId":"msg_6703a1f2b4c5e"}

data: {"type":"data-agent","data":{"name":"product_discovery"}}

data: {"type":"error","errorText":"The shopping assistant is temporarily unavailable. Please try again."}

data: {"type":"finish"}

data: [DONE]

The errorText value is a glossary translation in the locale of the request. The server writes the vendor error to the log, not to the stream.

Tool results

The output.result value is a JSON-encoded string, not a JSON object. Decode it a second time. The content depends on the tool:

A product card has the following fields: idProductAbstract, name, sku, url, imageUrl, description, price, priceFormatted, originalPrice, originalPriceFormatted, currencyIsoCode, priceMode, rating, reviewCount, labelIds, labels, attributes, variants, variantCount, reason, and isPriceOutlier. Plugins in getStorefrontAssistantProductCollectionExpanderPlugins() can add more fields.

Conversation history endpoints

The history endpoints return plain JSON:

toolInvocations[].result has the same format as output.result in the stream, with two differences:

• The history returns only customer-facing tools.
• The product cards are refreshed with current data, but refinementChips, activeFilters, and seeAll are not included. They exist only in the live stream.

Configuration

Back Office settings

Storefront Assistant reads its settings from the Storefront Assistant tab of the ai_commerce feature in Configuration Management. All values are read on each request, so changes apply without a deployment.

The Client runs in the Yves process and reads only Storefront settings. Every setting that the Client or Yves reads must have storefront: true. The model settings must have storefront: false, because Zed resolves them.

Client configuration

You can override the following methods in the Client AiCommerceConfig:

The attachment limits come from the Shared AiCommerceConfig: getStorefrontAssistantSupportedAttachmentMimeTypes(), getStorefrontAssistantMaxAttachmentSizeBytes(), and getStorefrontAssistantMaxAttachmentCount().

AI configuration

Storefront Assistant needs one AI configuration in config/Shared/config_ai.php for each AI vendor that you offer in the Back Office. The Client sends the name of the AI configuration to Zed with each turn. Zed accepts only the names that the Zed AiFoundationConfig::getClientResolvableAiConfigurationNames() returns. For the configuration examples and rules, see Set up configuration.

Frontend

The Storefront Assistant and the Back Office Assistant use one shared chat frontend: the <spryker-chat> custom element and its features, such as chat history, attachments, suggested prompts, and the agent selector. The module ships the shared chat in vendor/spryker-feature/ai-commerce/src/SprykerFeature/Shared/AiCommerce/Theme/default/Chat/.

The Storefront loads the shared chat as follows:

• SharedThemeTwigLoaderPlugin makes the shared Twig templates available as @AiCommerce/Chat/....
• The @shared/ai-commerce/* alias of the Yves frontend builder resolves the shared TypeScript and SCSS files.
• The storefront-assistant organism embeds @AiCommerce/Chat/core/chat.twig with the Storefront URLs, limits, and texts. It loads the chat lazily into the storefront-assistant chunk.
• The Storefront features are ShopUi molecules in vendor/spryker-feature/ai-commerce/src/SprykerFeature/Yves/AiCommerce/Theme/default/components/molecules/: chat-page-context, chat-tool-products, chat-tool-compare, chat-offer-choices, and chat-display-setup.
• The storefront-assistant-trigger molecule renders a header button that opens and closes the chat.

Project files replace core files with the same path:

The module README describes the blocks, the events, the style tokens, the tool renderer contract, and the other extension points of the shared chat: vendor/spryker-feature/ai-commerce/src/SprykerFeature/Shared/AiCommerce/Theme/default/Chat/README.md.

Page context

The frontend reads the page context from the DOM and sends it with each prompt. This lets the agent know the current product, category, or search query.

The chat-page-context molecule defines the page context as a list of rules in its data.rules. The first rule that matches the page wins:

The active filters are the checked checkboxes and radio buttons in .js-catalog__form.

If your theme changes this markup, the page context and the page-specific suggested prompts do not work. In this case, override the chat-page-context molecule at the project level and change its data.rules. The project list replaces the core list, so list all rules that you need.

Theming

The chat takes all colors, fonts, and sizes from --chat-* CSS custom properties. The storefront-assistant organism maps these properties to the ShopUi theme, so the chat uses the brand color of the shop automatically. The panel width is clamp(400px, 28vw, 480px). On small screens, the panel uses the full width.

To change the chat, set the properties in a project stylesheet for both selectors. The trigger button is outside the chat element, so it needs the second selector:

storefront-assistant spryker-chat,
.chat-trigger {
    --chat-color-accent: #{$setting-color-main};
    --chat-size-panel-width: clamp(400px, 28vw, 480px);
}

When the panel is open, the chat changes the page layout with these attributes on the <html> element:

The body padding does not move elements with position: fixed or position: sticky, such as a sticky header or a cookie banner. If such elements cover the panel, add right: var(--chat-dock-width) to them under :root[data-chat-docked].

Extension points

Install

Install Storefront Assistant