Agent Tools & Security

@commercengine/ai is designed around explicit capabilities and a narrow commerce safety boundary. The agent gets structured tools instead of DOM access, and each tool exposes only the data needed for that operation.

WebMCP status

WebMCP is an evolving browser capability. Commerce Engine prefers document.modelContext and retains compatibility where browser implementations differ. In unsupported browsers:

const registration = await registerCommerceWebMcp(config);
// null

That is an ordinary capability outcome. The storefront continues to function without agent tools. Development environments should always enable diagnostics so unsupported capability can be distinguished from registration code that never mounted.

Default tool inventory

Catalog

Tool	Read-only	Purpose
`search_products`	yes	search the Commerce Engine catalog
`get_product`	yes	retrieve authoritative product details
`browse_store`	yes	browse categories and products
`get_variant`	yes	inspect a specific product variant

Session and cart

These are included when the storefront exposes a browser session client. Registration can happen before that session is bootstrapped; calls return a retryable not-ready failure until the session is usable.

Tool	Read-only	Purpose
`get_session_state`	yes	report anonymous/logged-in state and available UI capabilities without exposing identity
`get_cart`	yes	return a safe cart projection
`add_to_cart`	no	add one or more product/variant quantities
`set_cart_item_quantity`	no	set the paid quantity on an existing line
`remove_from_cart`	no	explicitly remove a removable cart line

Tool	Requires	Purpose
`open_product`	`navigation`	open the resolved product URL
`manage_orders`	`navigation.ordersUrl`	open the application’s order-history route
`open_cart`	checkout bridge	open existing cart UI
`open_checkout`	checkout bridge	hand control to the shopper’s checkout UI
`open_login`	checkout bridge exposing `openLogin`	open login UI; does not accept credentials
`search_shop_policies_and_faqs`	`shopContent`	search a merchant-provided policy/FAQ source

No autonomous purchase completion

Commerce Engine deliberately does not provide tools for:

entering passwords or OTPs
selecting saved payment instruments
typing card/bank details
entering addresses on behalf of the user
placing an order
confirming payment

An agent may prepare the cart and open checkout. The shopper completes the transaction in the normal checkout experience.

Safe cart projection

get_cart and mutation results return an allow-listed representation. That boundary matters because the canonical Commerce Engine cart can evolve over time; new API fields must not silently become agent-visible. The agent-facing projection includes commerce fields such as:

cart ID
line ID
product/variant identifiers
names/SKUs necessary to identify the line
paid quantity, free quantity, total quantity
pricing/currency/totals
availability and order-quantity constraints
whether a line is removable

It excludes tokens, customer identity, addresses, payment state, and arbitrary metadata unless a future package version explicitly adds a reviewed field.

Cart mutation rules

`add_to_cart`

Adds to the existing paid quantity. It can accept a small batch of items in one invocation. For an existing cart, additions are applied sequentially. If a later line fails, the tool reports the lines already applied rather than pretending the whole request was atomic.

`set_cart_item_quantity`

Sets an absolute paid quantity for one existing line.

positive values must satisfy minOrderQuantity, maxOrderQuantity, and incrementalQuantity
0 means removal only when the line is removable
malformed values such as null, false, empty strings, or fractional numbers are rejected rather than coerced into a removal signal

Promotional/free quantities

A free promotion line or free units attached to a paid line cannot be treated as shopper-selected quantity.

quantity       paid units controlled by cart tools
freeQuantity   promotion-granted units
 totalQuantity  quantity + freeQuantity
removable      false for a completely promotional line

The model matches Hosted Checkout behavior so an agent cannot remove a line the shopper could not remove manually.

Cancellation and confirmed mutations

Tool execution may receive an AbortSignal. The package checks cancellation around asynchronous work, but the Commerce Engine SDK does not currently abort an already-started network request. Therefore cancellation is not rollback. If the server has already applied a mutation and returned the resulting cart, the tool returns that confirmed state even if cancellation arrived around the same time. This prevents an agent from retrying an already-applied add and duplicating quantity.

Anonymous sessions

Anonymous shoppers have real Commerce Engine sessions. Cart tools do not require sign-in. The same browser session can evolve from anonymous to authenticated, preserving the guest cart. This is not a cross-device cart-merge guarantee. get_session_state reports status, not identity:

{
  ok: true,
  data: {
    anonymous: true,
    loggedIn: false,
    loginAvailable: true
  }
}

Route trust

Public route shapes should be shared with @commercengine/seo:

const { site, routes } = commerceSeo;

await registerCommerceWebMcp({
  storefront,
  siteUrl: site.url,
  routes,
});

Forward resolvers turn CE entities into public URLs. Inverse resolvers map CMS-owned public slugs back to CE product/category identifiers before catalog tools query Commerce Engine. Navigation is same-origin unless an origin is explicitly allowed:

navigation: {
  navigate,
  allowedExternalOrigins: ["https://support.acme.example"]
}

Do not derive this allow-list from catalog or CMS content.

Untrusted merchant content

Catalog text and policy/FAQ results are data, not instructions. Commerce Engine marks appropriate tool results as untrusted content and keeps tool descriptions/schema package-authored. This prevents a malicious product description from redefining what a tool does.

Input constraints

Tool schemas use narrow types, bounded free-form strings, and additionalProperties: false where appropriate. Runtime validation is still defensive; safety does not depend on the calling model obeying JSON Schema perfectly.

Diagnostics

Configure diagnostics during integration:

await registerCommerceWebMcp({
  storefront,
  diagnostics: (event) => {
    console.info("[commerce-ai]", event.phase, event.code, event.message ?? "");
  },
});

Useful diagnostic phases include capability detection, registration, rollback, and unregistering. A particularly useful distinction:

diagnostic says unsupported → mount code ran; browser lacks WebMCP
diagnostic says registered → package reached modelContext.registerTool
no diagnostic at all → your registration block likely never executed

The starter repository enables development diagnostics in all supported framework integrations for this reason.

Test the tool set without WebMCP

createCommerceAiTools() is DOM-free:

import { createCommerceAiTools } from "@commercengine/ai";

const tools = createCommerceAiTools({
  storefront,
  siteUrl: site.url,
  routes,
});

expect(tools.map((tool) => tool.name)).toContain("search_products");

Use this for unit tests, introspection, and custom module composition.

Extend the module set

Commerce AI tools are built from plain modules.

const tools = createCommerceAiTools({
  storefront,
  extraModules: [myStoreLocatorModule],
});

Use extraModules to append merchant-specific tools. Use modules only when you intentionally want to replace the default module list. A duplicate tool name is a composition error and should fail early rather than allow two implementations to compete.

Policy/FAQ bridge

Merchant editorial content is intentionally an extension point rather than a CMS-specific dependency:

shopContent: {
  searchPoliciesAndFaqs: async (query, signal) => {
    return cms.searchHelpContent(query, { signal });
  },
}

Return compact, authoritative results rather than dumping entire CMS documents into the agent context.

Recommended review checklist

Before enabling agent tools in production:

tools are registered only once per live browser document/runtime
registration is aborted on component/runtime teardown
diagnostics are visible in development
public routes resolve to the same URLs as SEO
external navigation allow-list is explicit
no custom tool exposes tokens, addresses, raw customer objects, or payment data
cart tools return the resulting cart after mutations
checkout completion remains human-controlled
custom CMS output is treated as untrusted content

AI package

Setup and common integration patterns.

Agent Skills

Teach coding agents the same contracts.

WebMCP status

Default tool inventory

Catalog

Session and cart

Navigation / UI bridges

No autonomous purchase completion

Safe cart projection

Cart mutation rules

`add_to_cart`

`set_cart_item_quantity`

Promotional/free quantities

Cancellation and confirmed mutations

Anonymous sessions

Route trust

External navigation

Untrusted merchant content

Input constraints

Diagnostics

Test the tool set without WebMCP

Extend the module set

Policy/FAQ bridge

Recommended review checklist

AI package

Agent Skills

​WebMCP status

​Default tool inventory

​Catalog

​Session and cart

​Navigation / UI bridges

​No autonomous purchase completion

​Safe cart projection

​Cart mutation rules

​add_to_cart

​set_cart_item_quantity

​Promotional/free quantities

​Cancellation and confirmed mutations

​Anonymous sessions

​Route trust

​External navigation

​Untrusted merchant content

​Input constraints

​Diagnostics

​Test the tool set without WebMCP

​Extend the module set

​Policy/FAQ bridge

​Recommended review checklist

AI package

Agent Skills

WebMCP status

Default tool inventory

Catalog

Session and cart

Navigation / UI bridges

No autonomous purchase completion

Safe cart projection

Cart mutation rules

`add_to_cart`

`set_cart_item_quantity`

Promotional/free quantities

Cancellation and confirmed mutations

Anonymous sessions

Route trust

External navigation

Untrusted merchant content

Input constraints

Diagnostics

Test the tool set without WebMCP

Extend the module set

Policy/FAQ bridge

Recommended review checklist