Agent
The shopping assistant - AI-powered product discovery, cart management, and generative UI.
The storefront includes an AI shopping assistant powered by Claude via the Vercel AI SDK. It can search products, browse collections, manage the cart, and render rich product cards - all through natural conversation. The assistant is context-aware, adapting its behavior based on what page the user is viewing.
Architecture
The agent runs as a ToolLoopAgent that streams responses back to a floating chat panel:
- The client sends conversation history and a
chatIdto/api/chat - The server resolves page context from the
Refererheader (home, product, collection, search, or cart page) - A Shopify cart is created or retrieved from a cookie before the agent runs
- The agent calls tools to search products, manage the cart, or generate navigation links
- Tool results include json-render specs that the client renders as product cards, cart summaries, and variant pickers
Page context
The agent adapts its instructions based on where the user is browsing. Page context is resolved server-side from the Referer header:
- Product page - the full product is injected into the prompt with all variants, prices, availability, and variant IDs ready for "add to cart"
- Collection page - the collection handle and title are included
- Search page - the active search query is passed through
- Cart page - the agent knows the user is viewing their cart
- Home page - the agent knows the user is landing on the storefront and can help them start browsing
The system prompt also includes the user's locale so the agent responds in the correct language.
Tools
The agent has 11 tools organized into three groups. All tools access the agent context (chat ID, cart ID, locale, page) via AsyncLocalStorage.
Product discovery
| Tool | Purpose |
|---|---|
searchProducts | Keyword search with sorting (best matches, price low/high) - returns up to 10 results |
getProductDetails | Full product info: title, description, price, variants, availability, images |
getProductRecommendations | AI-powered similar products (up to 5) |
listCollections | All store categories |
browseCollection | Products within a collection with sorting |
Cart management
| Tool | Purpose |
|---|---|
addToCart | Add a variant to cart (requires Shopify variant ID) |
getCart | View cart contents, line items, and costs |
updateCartItemQuantity | Change quantity of a line item |
removeFromCart | Remove items by line ID |
addCartNote | Delivery notes, gift messages, special instructions |
Navigation
| Tool | Purpose |
|---|---|
navigateUser | Generate links to product pages, collections, search, cart, checkout, account, orders |
Generative UI
The agent doesn't just return text - it renders rich UI components via json-render. The system prompt includes a catalog of components the model can invoke:
- AgentProductCard - clickable card with image, title, price, compare-at price, and availability
- AgentProductGrid - 2-column responsive grid wrapping multiple product cards
- AgentCartSummary - full cart breakdown with line item thumbnails, subtotal, tax, total, and checkout button
- AgentCartConfirmation - success card shown after adding an item to cart
- AgentVariantPicker - display-only variant selector with option groups and availability status
These components are registered in a json-render registry and rendered client-side from specs embedded in the assistant's streamed messages.
Cart reconciliation
A CartReconciler component watches the agent's tool results for cart mutations. When addToCart, updateCartItemQuantity, removeFromCart, or addCartNote succeed, it extracts the updated cart object and syncs it to the global cart context - updating the cart UI without a page reload and opening the cart overlay for visual feedback.
Chat UI
The agent panel is toggled from a button in the bottom bar. The panel includes:
- Header controls to clear the conversation or minimize the panel
- Message display with collapsible chain-of-thought (tool calls auto-collapse after completion)
- Generative UI rendering via
useJsonRenderMessage()and a component registry - File attachment support via drag-and-drop
- Speech input
- Regenerate and copy message actions
- Chat history and draft input persisted to localStorage (
template-agent-chat:v1) until cleared - Click-outside and Escape to minimize
Configuration
The agent can be disabled entirely by setting the AI_AGENT_DISABLED environment variable, which hides the agent button from the storefront.
Key files
| File | Purpose |
|---|---|
app/api/chat/route.ts | Chat endpoint - page context resolution, cart initialization, streaming |
lib/agent/agent.ts | ToolLoopAgent creation with model, tools, and system prompt |
lib/agent/prompt.ts | Dynamic system prompt with page context and UI catalog rules |
lib/agent/context.ts | AsyncLocalStorage context (chatId, user, cart, page) |
lib/agent/tools/ | 11 tool implementations using Shopify operations |
lib/agent/ui/catalog.ts | json-render catalog schema definitions |
components/agent/registry.tsx | Generative UI component implementations |
components/agent/agent.tsx | Chat panel with messages, input, attachments, chain-of-thought |
components/agent/agent-button.tsx | Toggle button in bottom bar |
components/agent/cart-reconciler.tsx | Syncs agent cart mutations to global cart context |