---
title: Agent
description: The shopping assistant - AI-powered product discovery, cart management, and generative UI.
type: guide
prerequisites:
  - /docs/getting-started
---

# Agent



The storefront includes an opt-in AI shopping assistant built with [AI SDK](https://ai-sdk.dev). It helps shoppers discover products, browse collections, answer store-policy questions, manage their cart, and navigate the storefront through conversation.

The assistant is disabled by default. When disabled, the chat control is hidden and `POST /api/chat` returns `404`.

## Enable the assistant

Set `agent.isEnabled` to `true` in `lib/config.ts`, then deploy with access to the Vercel AI Gateway. The included assistant uses OpenAI GPT-5.6 Luna by default.

The chat endpoint is public and each message can incur model usage. Bot protection is configured separately and is also disabled by default. Before production traffic, review [Shop Configuration](/docs/reference/shop-config) and add rate limits or spending controls that match your risk tolerance.

Set `UCP_AGENT_PROFILE_URL` only if your store requires an agent profile for Shopify's hosted [Storefront MCP](https://shopify.dev/docs/apps/build/storefront-mcp). See [Environment Variables](/docs/reference/env-vars) for the full variable reference.

## Shopper experience

Out of the box, shoppers can:

* Search the catalog, including required options such as color or size
* Browse collections and request related or complementary products
* View current product details, prices, variants, images, and availability
* Add products, change quantities, remove lines, and add a cart note
* Ask about shipping, returns, payments, warranty, sizing, care, and other store policies
* Open product, collection, search, cart, checkout, account, and order destinations

Product, availability, and policy answers come from Shopify data rather than the model's memory. Searches with a required option can return fewer results, or none, instead of showing near matches.

Cart changes made in chat update the same cart used by the rest of the storefront. Product cards, variant choices, and cart summaries can appear directly in the conversation.

The current conversation and draft are stored only in the shopper's browser. They survive navigation and reloads, but not clearing site data or moving to another device. Clearing the chat removes that browser-local history.

## What’s next

You can change the model, response instructions, available actions, and rendered shopping experiences. Keep product facts grounded in Shopify, preserve one shared cart, and validate any new action before exposing it to shoppers.

For production, consider durable chat history if shoppers need conversations across devices. Add rate limits and spending caps independently of bot detection.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)