How to Build an AI Shopping Agent for Ecommerce

You can now start an ecommerce shopping agent with the agent loop, skills, tool contracts, safety gates, and interface patterns already laid out. Claude Commerce Agents gives you that frame. Your real job is to connect it to trustworthy catalog data, bind every action to the right shopper, keep inventory current, and stop the model before payment or any irreversible change.

That production work matters because the upside is measurable. Anthropic says retailers running shopping agents on Claude have seen carts up to 35% larger and shoppers 60% more likely to complete a purchase. Those are not promises for every store. They are a reason to treat the agent as a conversion product, not a chat widget.

The Blueprint Gives You the Frame, Not the Store

Claude Commerce Agents is an Apache-2.0 reference implementation for two roles. The shopping agent sits in front of customers. It can search, compare, plan a multi-item purchase, fill a cart, answer policy and order questions, and remember preferences. The merchant agent sits behind the store. It can analyze performance, watch inventory, propose pricing moves, and draft campaigns.

For a customer-facing shopping agent, the design is deliberately simple: one model runs a loop, common rules live in its system prompt, less common procedures live in five skills, and tools call the commerce systems you already operate. Think of it as a trained store associate standing at one counter. The associate keeps the whole conversation, but must use the stockroom terminal for inventory, the customer system for identity, and the register for the cart.

The same definition can run through the Messages API, Claude Agent SDK, or Claude Managed Agents. That portability is useful, but it does not make the examples production-ready. Anthropic says the demos contain no authentication. The repository does not place an order, charge a card, or supply your fraud, eligibility, inventory, and compliance rules.

The Business Math Starts After the Demo

The blueprint changes the cost of getting to a credible first build. On Anthropic's launch page, Wix reports a prompt-taking prototype in 15 minutes, Fetch says both reference agents ran locally in well under an hour, and Zomato says the included practices can save teams weeks of trial and error. Those are partner reports, not delivery guarantees. They still make the budget shift clear: less engineering time goes into inventing the agent frame, and more goes into catalog quality, permissions, evaluation, and the last mile to checkout.

Model spend can also be small compared with the integration work. Claude Sonnet 5 is priced at $2 per million fresh input tokens, $0.20 per million cache-hit tokens, and $10 per million output tokens. In an illustrative turn with 20,000 input tokens and 800 output tokens, the model cost is $0.048 when every input token is fresh. If 18,000 input tokens are cache hits and 2,000 are fresh, the same arithmetic is $0.0156. That excludes search, hosting, observability, support, and every commerce API around the model.

Anthropic says its strongest commerce deployments reach 90% to 99% cache-hit rates. This is why the production budget is not "buy an LLM." It is "make each completed shopping task accurate, fast, attributable, and safe."

How to Build the Production Path

The right build order follows the money and the risk. Start with the buying job, then connect data and identity, then grant actions, then optimize speed. A polished conversation on stale stock is still a broken store.

1. Pick One Buying Job and One Success Metric

Do not begin with "answer anything about our catalog." Pick a job such as helping a customer choose the right mattress size, assembling a three-product camping kit under a budget, or finding an in-stock replacement for an unavailable item.

Define success as a completed task, not a pleasant reply. Useful measures include a grounded product selection, an accepted recommendation, an add to cart, checkout handoff, containment without a support ticket, and return rate for assisted orders. Keep cart size and purchase completion beside latency and model cost. The cheapest answer is expensive when it recommends the wrong variant.

2. Put Your Existing Search and Ranking Behind the Catalog Tool

The model should not become your search engine. Anthropic's pattern is for search_products to return already-ranked results. Claude then decides which returned items satisfy the shopper's constraints and how many to show.

Map your catalog into three shapes: plain products, product families, and purchasable variants. A shirt family can carry size and color options, while each variant owns its current price and stock. Search can return the family, but a cart write must name the exact variant. That distinction prevents a fluent agent from adding "blue shirt" without knowing whether medium blue is available.

Return only fields the model needs to reason. Product ID, title, price, availability, option values, important attributes, and the source timestamp usually matter. Repeating image URLs and long marketing copy across every result burns context without improving the decision.

If you already have a search or recommendation service, keep its business logic there. If you do not, fix retrieval before tuning the prompt. A catalog tool cannot rescue incomplete attributes, duplicate SKUs, or ranking that ignores the shopper's constraints.

3. Bind Identity Before the Model Sees a Tool

Authentication belongs to your host application. It signs in the shopper, resolves a customer or guest principal, and starts a session. Backend methods read that identity from server-side session state. The model receives neither the customer ID as a tool argument nor the credential used to call your store.

Treat guests as real principals with fewer permissions. If a guest asks for order history or saved addresses, the backend should return a sign-in requirement. Start a new authenticated session after sign-in instead of mutating an anonymous identity halfway through a conversation.

This separation is easy to miss in a demo and expensive to retrofit. It is the difference between "the agent called the order tool" and "this authenticated shopper was allowed to read this order."

4. Make Inventory Authoritative at the Moment of Action

Search results help the agent reason, but the backend owns truth. Recheck stock, eligibility, price, purchase limits, fulfillment cutoffs, and promotion rules inside the cart operation. Do it atomically, so inventory cannot disappear between a read and a write without a clear response.

When a requested variant is unavailable, return the unavailable ID and valid sibling variants. Let the agent explain the tradeoff and ask the shopper to choose. Do not quietly swap products. For marketplaces, account pricing, travel dates, or store-specific pickup, pass the relevant context into the backend that computes the answer.

5. Treat Every Tool as a Permissioned API Surface

The reference implementation builds the visible tool list from deployment configuration. Turn off systems you do not have. Allow-list the remaining names. Refuse any call outside that list in code.

Then add provenance gates. A cart write should accept only a product ID returned by your server in that session or already present in that cart. This blocks invented IDs, IDs pasted from another account, and instructions planted in product content. The same principle applies to renders: the agent can choose a returned ID, but the server fills the product card from its own record.

Treat listings, reviews, policies, seller messages, and remembered facts as untrusted data. Anthropic's runtime sanitizes and fences third-party text before Claude reads it. Prompt rules help, but permissions, quantity caps, protected fields, and write serialization must live in code.

If your deployment needs more runtime or gateway control, the managed agent tools guide explains the infrastructure choices around tool-bearing agents.

6. End the Agent's Authority at Checkout

Claude Commerce Agents draws a hard line: the model can build and render the cart, but it cannot place the order or charge a card. The host supplies the checkout destination after the model call, so the URL itself never enters model context.

Choose one handoff:

1. Open checkout inside your own application.
2. Open the commerce platform's hosted checkout URL.
3. For a marketplace, show one checkout link per seller.

That boundary is good product design, not a missing trick. It lets the shopper review quantity, address, shipping, discounts, and total price on the system that already owns payment and compliance.

Add a separate human-support handoff for ambiguity the agent should not absorb. Define which intents trigger it, which queue receives it, what conversation summary travels with it, and what the human can approve. "Talk to a person" is a workflow with identity and service-level rules, not a fallback sentence.

7. Render Commerce UI Through Typed Tools

Product grids, comparison tables, plans, carts, and order cards should be typed presentation tools. Claude calls a component with structured arguments, your server validates and enriches them, and the client renders the result.

This makes the visible interface part of the conversation record. When a shopper says "the second one," the ordered product list remains in the messages. It also avoids asking the model to invent fragile custom markup. If you need the surrounding conversational shell, the chatbot build guide covers the broader interface decisions.

8. Budget Latency Across the Whole Task

Measure time to completed task as model turns plus tool time. Fewer turns, faster tools, and faster token delivery all matter.

Load likely page context before the first model call. Run independent catalog or policy reads in parallel. Dispatch each tool as soon as its arguments finish streaming. Stream product cards as their fields arrive, and show a plain progress line while a slow lookup runs.

Anthropic says a rendered commerce response often spans 500 to 700 output tokens, enough for five or more seconds of a blank spinner without progressive rendering. It also reports eager dispatch taking observed multi-second tool gaps down to a few hundred milliseconds. Do this engineering before downgrading the model. A less capable model can need more turns and cost more per completed task.

9. Turn Product Requirements Into Evals

An eval is a repeatable case that checks what the agent does from a known state. Construct the messages, catalog records, cart, user facts, and failures that matter, then grade the final state and rendered response.

Cover five groups: core shopping requests, context-dependent turns, safety and brand cases, interface behavior, and messages that cross two capabilities. Write a negative counterpart for every positive case. If the agent should recommend an in-stock variant, also test the case where every valid variant is unavailable. Test hostile text inside a listing, another user's order ID, timeouts, empty searches, repeated cart additions, and a price change between search and cart.

Anthropic recommends 50 to 100 cases per user flow as a starting point. Build them with product, legal, customer care, and merchandising teams, then turn real incidents into permanent regression cases. Gate canary releases on grounded accuracy, task completion, safety pass rate, p50 and p99 latency, cache-hit rate, and cost per completed task.

Seven Ecommerce Use Cases, Ranked by Who Benefits Most

The biggest gains go to stores where shoppers have real constraints and the catalog contains meaningful tradeoffs. A generic FAQ bot is the weakest use of this architecture.

1. High-Consideration Product Advisor

Who: A mattress, appliance, outdoor gear, or electronics store with products that require comparison.

Workflow: The shopper states a goal, budget, dimensions, and preferences. The agent queries ranked catalog results, fetches details for the strongest candidates, presents a structured comparison, confirms the exact variant, and prepares the cart.

Why it pays: It moves decision support into the buying session. This is the use case closest to Anthropic's reported larger-cart and purchase-completion results because the agent can resolve uncertainty before the shopper leaves.

2. Goal-Based Bundle Builder

Who: A store selling products that work together, such as camping gear, home-office equipment, skincare routines, or a first kitchen setup.

Workflow: The agent breaks one goal into several product needs, runs independent searches in parallel, checks the combined budget, explains compromises, and adds approved variants to one cart.

Why it pays: The agent can grow basket size by completing a job rather than promoting one more item. It also saves the shopper from opening several category pages and reconciling compatibility alone.

3. Variant and Fit Guide

Who: Apparel, cosmetics, furniture, and configurable-product merchants with high return risk.

Workflow: The shopper supplies fit, shade, space, or compatibility constraints. The agent reads family options, checks the exact variant's stock, presents only valid combinations, and refuses to add an unresolved family record.

Why it pays: The value is fewer wrong choices, not more chat. A valid variant at checkout can reduce avoidable cancellations and returns while keeping the shopper moving.

4. Discovery Plus Post-Purchase Care

Who: Stores whose support queue repeatedly handles order status, returns, warranties, and policy questions.

Workflow: The same conversation moves from product discovery to a signed-in order lookup or policy search. The agent reads the customer's own records, renders the status, and transfers exceptions to a human with context.

Why it pays: One surface can support both conversion and containment. The shopper does not have to repeat the product, order, and policy context to a separate bot.

5. Account-Aware B2B Buying Assistant

Who: Distributors and subscription businesses with contract pricing, eligibility rules, or approved assortments.

Workflow: The host binds the buyer's account and role to the session. Backend tools return only that account's price, allowed products, and fulfillment options. The agent assembles a quote or purchase-order handoff instead of pretending consumer checkout fits.

Why it pays: It compresses a rules-heavy buying process while preserving entitlements. The model explains choices, but the account system remains the authority.

6. Marketplace Cart Coordinator

Who: A marketplace where several sellers may satisfy one request.

Workflow: Seller becomes a search dimension. The agent compares offers, groups cart lines by seller, and the host renders a separate checkout link for each seller when required.

Why it pays: It turns a fragmented purchase into one planning conversation without hiding the commercial reality that payment and fulfillment belong to different merchants.

7. Merchant Inventory and Promotion Copilot

Who: Merchandising teams that juggle sales, stock, pricing, and campaigns across many SKUs.

Workflow: The merchant agent reads performance and inventory alerts, proposes a restock or promotion, stages the change, and waits for approval through a real operator surface before anything applies.

Why it pays: It can shorten analysis and preparation work while preserving the maker-checker controls the business already uses. The human keeps authority over price, budget, and live listings.

Three Products Worth Building

1. A Vertical Shopping-Agent Launch Kit

Build a production package for one high-consideration category, such as outdoor equipment, furniture, or beauty, and sell it to merchants that have outgrown a generic chat widget.

The price ladder already exists. Brambles lists shopping-assistant plans from $29 to $499 per month across 10,000 to 500,000 sessions. Rye charges $149 per month for agentic commerce infrastructure, then $0.02 per product fetch and $0.05 per placed order. Those numbers show both merchant subscription spend and metered infrastructure spend.

The smallest sellable version supports one commerce platform and one category. It maps families and variants, binds guest and signed-in sessions, implements search and product details, builds a cart, hands off to hosted checkout, streams two or three typed UI components, and ships with a category-specific eval pack and human transfer route.

The catch is price pressure. Platforms and cheap app-store assistants can cover generic product Q&A. Your defensible layer has to be category logic, reliable catalog mapping, conversion attribution, and cases built from that vertical's real failures.

This is the strongest opportunity. It sits closest to merchant revenue, and the blueprint removes enough generic scaffolding that a small team can spend its time on the category-specific work buyers will actually pay for.

2. Catalog Readiness and Variant QA for Agents

Build a service that tests whether a catalog can safely answer agent queries before a shopping agent reaches customers.

There is already meaningful infrastructure around this problem. Channel3 says its product layer covers 100 million products across 25,000 retailers and responds in under a second. Rye charges $0.02 per product fetch. Google prices AI Commerce Search at $2.50 per 1,000 queries. Structured, current retrieval is already a budget line.

An MVP imports one feed, builds family-to-variant relationships, checks required attributes, compares price and stock timestamps, runs a library of real shopping constraints, and reports missing or contradictory answers by SKU. Add a replay test that confirms the same query never produces an unavailable variant at cart time without an explicit recovery path.

The catch is platform gravity. Shopify and other commerce platforms own authoritative catalog feeds and can absorb basic validation. The product needs cross-platform normalization, issue prioritization tied to lost shopping tasks, and proof that fixes reduce bad recommendations.

3. A Commerce-Specific Eval and Release Gate

Build the test layer that decides whether a prompt, model, tool, or catalog change is safe to ship.

Agent evaluation already has budget. Langfuse says more than 50,000 companies use its platform and prices production tiers at $29 and $199 per month, with Enterprise starting at $2,499. Anthropic recommends 50 to 100 eval cases for each commerce flow. The gap is not another trace viewer. It is a maintained library of commerce states, poisoned catalog fixtures, cart invariants, and release policies.

The MVP imports transcripts, turns incidents into snapshot cases, and ships deterministic graders for product provenance, price grounding, variant selection, quantity caps, checkout boundaries, identity leaks, timeout recovery, and handoff quality. It should compare models and prompts by task completion, p99 latency, and cost per completed task.

The catch is a crowded horizontal market. The moat must come from commerce-specific fixtures, grader accuracy, platform connectors, and benchmark data. Generic observability alone will be copied or bundled.

What Claude Commerce Agents Does Not Solve

The honest take is that this blueprint solves agent structure better than store integration. It gives you a serious starting point, not a hosted shopping product.

• It does not authenticate shoppers or authorize staff. Your host and gateway own that.
• It does not repair poor catalog data, ranking, or inventory latency. Your commerce systems remain responsible.
• It does not place orders, hold payment credentials, charge cards, or decide fraud policy.
• It does not choose your human escalation rules, service queues, or approval roles.
• It does not make Anthropic's reported conversion gains transferable to every catalog. You need your own controlled measurement.
• It does not remove the need for privacy decisions around memory. Stored preferences need accepted data types, retention, access, correction, and deletion.

Do not build this for a tiny catalog where filters already resolve every purchase in one click. Do not launch it when prices and stock are stale. Do not grant write access because the prompt sounds careful. The agent earns its place when conversation resolves a genuinely complex buying job and your systems can supply current, permissioned facts.

The Monday Move

Pick one revenue-bearing flow next week. Take 50 real examples from site search, sales chat, and support transcripts. Wire only catalog search and product details first, with every other tool returning unavailable. Measure whether the agent selects grounded, in-stock variants and whether shoppers accept the recommendation. Add cart and checkout only after the read path passes its cases. That sequence turns Claude Commerce Agents from an impressive demo into a controlled commerce release.

How does the AI shopping assistant work?

One Claude agent keeps the conversation and calls typed tools for catalog search, product details, the cart, policies, orders, memory, and presentation. Your backend authenticates the shopper, applies pricing and inventory rules, and returns structured facts. The model reasons over those facts but does not become the source of truth.

How do I connect my product catalog?

Implement the blueprint's storefront backend against your existing search and product services. Return already-ranked families from search, exact purchasable variants from product details, and current price and availability from your authoritative systems. Keep credentials and shopper identity on the server.

How do user permissions work in Sidekick?

For your own shopping or merchant agent, copy the underlying principle, not Sidekick's product implementation. Resolve the user and role before the agent turn, expose only allowed tools, keep credentials server-side, enforce authorization again in each backend method, and require a real host approval for sensitive merchant writes.

Can I self build it using Claude or something like that?

Yes. The open-source repository includes runnable examples and a Claude Code plugin that can scaffold against your backend. The self-build work that remains is substantial: authentication, catalog mapping, live inventory, cart and checkout integration, permissions, human handoff, monitoring, and evals.

If you want one of these built around your catalog and operating rules, see AI agent development.