Skip to content
Agent SDK`s
/
Using the Norce Commerce...
Last updated

Using the Norce Commerce Agent SDK

This guide explains how to use the Norce Commerce Agent SDK to add a conversational shopping assistant to an existing webshop frontend.

The SDK is a reference implementation built on the same principles as Norce Commerce APIs and the Norce Commerce MCP Server: OAuth2-based authentication, explicit context control, and a stable tool surface for agents.

Repository (MIT): https://github.com/NorceTech/commerce-agent-sdk

When to use the Agent SDK

Use the Agent SDK when you are:

  • Building a conversational shopping experience that:

    • helps users find and refine products iteratively,
    • proposes a small curated set of recommended items,
    • and (optionally) manages a basket/cart through commerce tools.

  • Integrating an LLM into a storefront and you want:

    • a production-shaped baseline (agent loop, session handling, streaming),
    • a widget UI designed to embed into an existing webshop,
    • a Postman collection to explore the Agent BFF APIs quickly.

If you are building a traditional frontend or system integration (non-agent), you should typically use the regular Norce Commerce APIs directly.

What’s included

The SDK contains:

  • Agent BFF (Backend-for-Frontend) A Node.js backend that runs the agent loop and communicates with Norce Commerce via MCP tools.
  • Agent Widget UI A frontend widget intended to be embedded into an existing webshop UI.
  • Documentation Setup and usage instructions under docs/.
  • Postman collection For calling the Agent BFF endpoints during development.

Architecture overview

At a high level:

Webshop frontend → embeds Agent Widget UI → calls Agent BFF (/v1/chat and /v1/chat/stream) → Agent BFF orchestrates LLM + MCP tool calls → MCP tools call Norce Commerce Services (Product/Shopping) through the Norce Commerce MCP Server.

Authentication and headers

The Agent SDK reuses the same OAuth2 mechanism as other Norce Commerce APIs.

1) Create an OAuth2 account and token

  • Create an OAuth2 integration user in Norce Admin with access to:

    • the relevant Application(s),
    • the relevant resources (for example Norce API).

  • Obtain an access token using the standard OAuth2 flow described in “Accessing APIs with OAuth2 accounts”.

2) Calling the MCP Server

When the Agent BFF calls the Norce Commerce MCP Server, each request must include:

  • Authorization: Bearer <access_token>
  • application-id: <application-id>

This is the same application-id concept used across Norce Commerce APIs and is validated by the MCP Server.

The Agent SDK assumes the Agent BFF is responsible for obtaining and refreshing OAuth2 access tokens (token caching is strongly recommended to avoid excessive token issuance).

Concepts: sessions, context, tools, and UI payloads

Sessions

The Agent BFF maintains a server-side session keyed by an identifier provided by the client (your webshop). A session typically stores:

  • conversation history (for iterative refinement),
  • working memory (last results, shortlist, variant choices),
  • optional tool trace metadata (for debugging).

In early development you can run session storage in-memory. Production deployments typically move session state to an external store (e.g., Redis), but that is not required to get started.

Context

The context describes where and for whom the request is made (culture, currency, price lists, sales area, customer/company). It plays the same role as when calling Norce Commerce services directly, and the MCP Server expects it as an input parameter for tool calls.

Example context:

{
  "cultureCode": "sv-SE",
  "currencyCode": "SEK",
  "priceListIds": [1, 5],
  "salesAreaId": 10,
  "customerId": 12345,
  "companyId": 123
}

The Agent SDK does not “guess” market or price lists. Your storefront (or its BFF) should supply the correct context.

Tools

The Agent BFF uses MCP tools such as:

  • product.search – search and list products
  • product.get – fetch detailed product data
  • (optionally) cart tools for basket management

The MCP Server exposes these tools as a structured tool surface on top of Norce Commerce Services.

UI payloads

The Agent BFF returns structured output intended for UI rendering, typically including:

  • assistant text response
  • product cards (small curated list)
  • optional variant choices / compare blocks / cart summaries
  • optional debug tool trace (for development)

Quickstart

For the canonical setup steps, see the repo guide:

  • docs/getting-started.md (in the repository)

Typical flow:

  1. Clone the repository
  2. Install dependencies (BFF + widget)
  3. Configure environment variables for OAuth2 + endpoints
  4. Start the Agent BFF locally
  5. Test /v1/chat using the included Postman collection
  6. Start the widget and embed it into your webshop frontend

Agent BFF API reference

POST /v1/chat

Purpose: Submit a user message and get a full (non-streamed) structured response.

Typical request:

{
  "applicationId": "1234",
  "sessionId": "unique-session-id",
  "message": "Show me bear slippers in size 30-31",
  "context": {
    "cultureCode": "sv-SE",
    "currencyCode": "SEK",
    "priceListIds": [1],
    "salesAreaId": 10
  }
}

Typical response (shape example):

{
  "applicationId": "1234",  
  "sessionId": "unique-session-id",
  "text": "Here are a few options that match. Want kids or adult sizes?",
  "cards": [
    {
      "productId": "118936",
      "title": "Bear Slippers",
      "variantName": "Brown, 30-31 EU",
      "thumbnailImageKey": "0fc8c262-c5e5-45a1-8508-13a393f7ee36",
      "availability": { "status": "in_stock", "onHandValue": 4 }
    }
  ]
}

Exact fields depend on your SDK version and which MCP tools are enabled.

POST /v1/chat/stream

Purpose: Submit a user message and receive Server-Sent Events (SSE) while the agent works, followed by a final structured response payload.

Events typically include:

  • status/progress messages (for UI feedback)
  • optional tool activity summaries
  • a final “response” event containing the same payload shape as /v1/chat

Best practice: keep /v1/chat and the final /v1/chat/stream payload consistent so the widget can render both code paths the same way.

Embedding the Widget UI

The widget is designed to be embedded into an existing webshop UI. Common integration patterns:

  • mount it into a container element on product listing pages

  • mount it into a drawer/modal

  • provide the widget with:

    • the Agent BFF base URL
    • a sessionId strategy
    • a context provider (culture/currency/price lists/sales area)

Localization

The widget supports localization through language resource files and runtime selection:

  • derive UI language from cultureCode (e.g. sv-SE → sv)
  • optionally override with a uiLanguage parameter (sv/en)
  • fallback to English for unsupported languages

Troubleshooting

401 Unauthorized from MCP calls

  • Verify your OAuth2 token is valid and not expired.

  • Verify you set:

    • Authorization: Bearer …
    • application-id: …

  • Verify your OAuth2 integration user has access to the targeted Application.

Some catalogs use simple full-text search under the hood. Prefer:

  • simple queries (“slippers”, “bear slippers”)
  • then refine results in the agent loop using filters and product attributes

Streaming works in Inspector but not in your client

If you implement your own MCP client or streaming wrapper, ensure you are using MCP Streamable HTTP and correctly handling 202 + stream payload behavior.

Next steps

  • Read docs/getting-started.md in the repository
  • Try the Postman collection against /v1/chat
  • Embed the widget in a development storefront
  • Extend the agent with more MCP tools (cart operations, richer product flows)
Previous page