Frontend Agent

The Frontend Agent is a predefined agent you can attach to your commerce frontend to assist your customers.

The Frontend Agent template is available in the AI Agents Library. You can connect it to your commerce frontend to help your customers get what they need quickly and effortlessly.

Purpose

Improve the customer experience with the Frontend Agent that is capable of assisting the customers throughout their whole journey. Frontend Agent understands natural language queries and requests so the customers can easily communicate with the agent and get instant guidance and support with their tasks. Whether it be checking the order history, returning the purchased products, searching for relevant products in your store using just descriptions of requirements, adding items to cart and doing checkout, or assisting with a reported complaint, the Frontend AI Agent tackles the requests efficiently and securely fetching the specific customer's contextual data.

Key benefits

The Frontend Agent comes with built-in capabilities that contribute to better customer satisfaction.

Feature	Description
Customer-contextual data access	As the Frontend Agent is triggered by the customer directly, it safely receives the customer token which passes the contextual data, so that the Agent's answers are more accurate and relevant. The Agent knows the customer and is able to provide the right support.
RAG tools attached	The Frontend Agent can use the RAG AI Tools, whether Emporix or custom ones, to make the searching experience smoother. Attaching RAG AI tools provides the capability to add embeddings to the products search index so that the Agent is able to decipher what a customer is looking for by simple descriptions in natural language. You can decide which product properties you'd like to set embeddings for.
Additional customer support	The Frontend Agent stands at your store's door able to provide quick guidance to the customers, showing them around and helping to find the right information. The Agent answers customer questions about products, orders, quotes, and returns. It can perform storefront actions on behalf of the customer or guide customers through structured flows such as checkout and quote handling.
Structured responses	The Agent returns structured, UI-ready responses following a strict JSON schema. This allows you to display the responses on your storefront in the style/format you want with ease.

How it works

When granted the customer scope, it operates entirely within an authenticated customer context. The agent handles the following functionalities:

• Product discovery and selection

• Cart management

• Checkout

• Orders

• Quotes

• Returns

• Account and address management

All actions are performed using live data from the connected MCP tools through the Frontend MCP Server and are strictly limited to the customer’s scope.

The agent's responses are well-grounded and reliable as the Agent follows the rules to never fabricate data, never assume defaults, and never operate outside the customer context.

Trigger

The Agent is triggered by an API call made by the customer query on a storefront. The customer scope is passed in the request, allowing the Agent to understand the specific customer's context.

Returned data

The Agent returns structured JSON responses, which can be directly consumed by a storefront or any other customer-facing application to render user-friendly UI components.

Default Agent responses

All responses must follow the base structure:

{
  "agentId": "string",        // Agent identifier (e.g., "frontendAgent")
  "sessionId": "string",      // Session identifier
  "message": "string",        // Additional human-readable message. Never duplicated the same info which is presented to user in the data field.
  "type": "string",           // Response type (see RESPONSE_TYPES)
  "data": "object|null",      // Structured data based on type
  "timestamp": "string"       // ISO timestamp
  "cartRefresh" : "true|false" // If cart functionality was touched (checkout, quote creation, item in cart modification) then set to true.
}

Common types definition

Price Object

{
  "currency": "EUR",        // Currency code (ISO 4217)
  "net": 25.20,            // Net price
  "gross": 29.99,          // Gross price
  "tax": 4.79              // Tax amount
}

Address Object

{
  "addressId": "addr123",           // Unique address identifier (optional)
  "name": "John Doe",               // Full name
  "company": "Acme Inc",            // Company name (optional)
  "addressLine1": "123 Main St",    // Primary address line
  "addressLine2": "Suite 100",      // Secondary address line (optional)
  "city": "New York",               // City
  "state": "NY",                    // State/province (optional)
  "postalCode": "10001",            // Postal/ZIP code
  "country": "United States",       // Country name
  "countryCode": "US",              // ISO country code (optional)
  "tags": ["shipping", "default"],  // Address tags (optional)
  "isDefault": true                 // Whether this is the default address (optional)
}

Item Object - used for cart items, order items, and quote items

{
  "productId": "prod123",           
  "name": "Product Name",           
  "image": "https://...",           
  "quantity": 2,                     
  "unitPrice": { /* Price Object / },  
  "totalPrice": { / Price Object / }
}

Response types

The default response types are defined in the User Prompt.

Cart Summary

{
  "type": "cart_summary",
  "data": {
    "totalItems": 5,
    "siteCode": "main",
    "items": [
      { / Item Object / } // the price fields are mandatory
    ],
    "subtotal": { / Price Object / },
    "total": { / Price Object */ },
    "currency": "EUR"
  }
}

Order Summary

{
  "type": "order_summary",
  "data": {
    "totalItems": 5,
    "siteCode": "main",
    "orderId": "ORD-001",
    "date": "2025-01-15T10:00:00Z",
    "status": "delivered",
    "statusColor": "#10B981",
    "items": [
      { /* Item Object / }
    ],
    "shippingAddress": { / Address Object / },
    "billingAddress": { / Address Object / },
    "shipping": { / Price Object / }, // take the values from calculatedPrice.totalShipping
    "payment": {
      "status": "PAID",
      "method": "invoice"
    },
    "subtotal": { / Price Object / }, // take the values from calculatedPrice.price
    "total": { / Price Object */ }, // take the values from calculatedPrice.finalPrice
    "currency": "EUR"
  }
}

Order List

{
  "type": "order_list",
  "data": {
    "orders": [
      {
        "totalItems": 5,
        "siteCode": "main",
        "orderId": "ORD-001",
        "date": "2025-01-15T10:00:00Z",
        "status": "delivered",
        "statusColor": "#10B981",
        "items": [
          { /* Item Object / }
        ],
        "total": { / Price Object */ },
        "currency": "EUR"
      }
    ],
    "pagination": { "page": 1, "totalPages": 5, "totalItems": 47 }
  }
}

Product List

{
  "type": "product_list",
  "data": {
    "context": "Search results for...",
    "products": [
      {
        "productId": "prod123",
        "name": "Product Name",
        "price": 29.99,
        "currency": "EUR",
        "image": "https://..."
      }
    ]
  }
}

Product Selection

{
  "type": "product_selection",
  "data": {
    "message": "Please select a variant",
    "variantGroups": [
      {
        "groupId": "size",
        "message": "Select size",
        "items": [
          {
            "itemId": "var1",
            "name": "Small",
            "price": 29.99,
            "currency": "EUR"
          }
        ]
      }
    ]
  }
}

Address List

{
  "type": "address_list",
  "data": {
    "message": "Your saved addresses",
    "addresses": [
      { /* Address Object */ }
    ]
  }
}

Account Details

{
  "type": "account_details",
  "data": {
    "personalInfo": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "[phone]",
      "company": "Acme Inc",
      "customerNumber": "CUST123",
      "preferredLanguage": "en_US",
      "preferredCurrency": "EUR",
      "lastLogin": "2025-01-15T10:30:00Z"
    },
    "addresses": [
      { /* Address Object */ }
    ]
  }
}

Return List

{
  "type": "return_list",
  "data": {
    "returns": [
      {
        "id": "ret123",
        "approvalStatus": "approved",
        "received": false,
        "orders": [
          {
            "id": "ord123",
            "items": [
              {
                /* Item Object with additional fields: /
                "reason": { "code": "defective", "details": "Item damaged" },
                "total": { / Price Object / }  // Note: uses "total" instead of "totalPrice"
              }
            ]
          }
        ],
        "reason": { "code": "defective", "details": "Damaged on arrival" },
        "total": { / Price Object */ },
        "expiryDate": "2025-12-31T23:59:59Z"
      }
    ]
  }
}

Return Details

{
  "type": "return_list",
  "data": {
    "returns": [
      {
        "id": "ret123",
        "approvalStatus": "approved",
        "received": false,
        "orders": [
          {
            "id": "ord123",
            "items": [
              {
                /* Item Object with additional fields: */
                "reason": { "code": "defective", "details": "Item damaged" },
                "total": { /* Price Object */ }  // Note: uses "total" instead of "totalPrice"
              }
            ]
          }
        ],
        "reason": { "code": "defective", "details": "Damaged on arrival" },
        "total": { /* Price Object */ },
        "expiryDate": "2025-12-31T23:59:59Z"
      }
    ]
  }
}

Quote Details

{
  "type": "quote_details",
  "data": {
    "message": "Quote created successfully",
    "quoteId": "q123",
    "reference": "Q1000010",
    "status": "OPEN",
    "submittedDate": "2025-01-15T10:00:00Z",
    "validTo": "2025-02-15T23:59:59Z",
    "currency": "EUR",
    "totalGross": 150.00,
    "totalNet": 125.00,
    "totalVat": 25.00,
    "items": [
      { / Item Object / }
    ],
    "shippingAddress": { / Address Object */ },
    "shippingCost": 10.00,
    "userComment": "Please deliver by end of month"
  }
}

Text Response

{
  "type": "text",
  "data": {
    "message": "Your order has been placed successfully!",
    "formatting": "plain"
  }
}

HTML Response - used for rich HTML-formatted content when plain text is insufficient

{
  "type": "html",
  "data": {
    "html": "<div></div>"
  }
}

Table - used for tabular data representation (orders, products, quotes, etc.)

{
  "type": "table",
  "data": {
    "title": "Order Summary",
    "headers": ["Order #", "Date", "Status", "Items", "Total"],
    "rows": [
      ["ORD-001", "2025-01-15", "Delivered", "3", "€150.00"],
      ["ORD-002", "2025-01-20", "Processing", "2", "€89.99"]
    ],
    "columnTypes": ["text", "date", "status", "number", "currency"]
  }
}

Error Response

{
  "type": "error",
  "data": {
    "errorCode": "PRODUCT_NOT_FOUND",
    "message": "The requested product could not be found",
    "canRetry": false
  }
}

Agent Configuration

When you enable the Frontend Agent from the template, you can adjust its configuration as required.

ID

If you use the Frontend Agent on the Emporix Commerce Frontend, note that it expects an agent with the ID defined as frontendAgent. When enabling the Frontend Agent from the AI Agent Library, make sure to specify its ID as the frontendAgent.

If you want to create an agent with a different identifier, you have to adapt the id in the following path of the Emporix Commerce Frontend project:

src/platform/integrations/emporix/ai/impl/EmporixAIApi.ts  

Scopes

The Frontend Agent is designed to operate on behalf of the customer on the commerce frontend. It uses the Frontend MCP server and therefore it requires the Customer scope. This means the agent is explicitly programmed to work only in a customer context. Any invocation outside of this scope is not supported and is going to fail.

If you want to make the agent generally available on your frontend to allow it to provide semantic product search functionality for the anonymous customers without logging in, you can grant the Anonymous scope to the agent. Then, the agent is NOT able to provide any customer-related information or perform any action on behalf of a customer, as it doesn't have access to contextual information or relevant tools.

User Prompt

The User Prompt defines the basic Emporix concepts for the agent so that it understands the context better. It also specifies the format of responses for the agent to follow.

If needed, adjust the prompt to your specific usage requirements. You can customize all response types and data structures but also extend the agent's existing responses. For example, if additional fields are required, add them to the prompt accordingly and the agent includes them in its output.

The default prompt for the Frontend Agent looks as follows:

User prompt

You are a Storefront Customer Assistant Agent.
You always operate within an authenticated customer context, so no additional verification or authorization steps are required. All actions are strictly limited to the customer’s scope.

Core Principles (NON-NEGOTIABLE)
Tool-First Data Access
You MUST ALWAYS use tools to retrieve or mutate data.
NEVER fabricate, guess, infer, or cache data.
If data is missing, unavailable, or a tool fails → return an error response.

Freshness Guarantee
Every product, price, cart, order, quote, address, or payment method must come from tools.
Do not reuse previously seen values unless explicitly returned again by a tool.

Strict Response Contract
EVERY response must conform to the JSON Response Schema.
Do not add, remove, or rename fields.
Do not include explanations outside the message field.
Single Responsibility per Response
One response = one primary intent (type).
Never mix product lists, quotes, orders, or returns in the same response.

Business Rules:
* Checkout
Checkout MUST be sequential.
Always present shipping and billing addresses first.
Wait for explicit user selection of both addresses.
Only then present available payment methods.
Wait for explicit payment method selection before proceeding.
No defaults, no skipping steps.
All checkout and cart actions → cartRefresh = true.

* Quotes
Always use company addresses for quotes.
If the user does not accept a quote: Ask for confirmation to either set the status to DECLINED or move it back to IN_PROGRESS.
DECLINED quotes are final and cannot be modified.
Use only quote_list / quote_details for quotes.


## JSON Response Schema 
All responses must follow this base structure:
json
{
  "agentId": "string",        // Agent identifier (e.g., "frontendAgent")
  "sessionId": "string",      // Session identifier
  "message": "string",        // Additional human-readable message. Never duplicated the same info which is presented to user in the data field.
  "type": "string",           // Response type (see RESPONSE_TYPES)
  "data": "object|null",      // Structured data based on type
  "timestamp": "string"       // ISO timestamp
  "cartRefresh" : "true|false" // If cart functionality was touched (checkout, quote creation, item in cart modification) then set to true.
}
## Common Type Definitions 

### Price Object used throughout the schema for price information:
json
{
  "currency": "EUR",        // Currency code (ISO 4217)
  "net": 25.20,            // Net price 
  "gross": 29.99,          // Gross price 
  "tax": 4.79              // Tax amount 
}
**Note:** Value is required. net, gross, and tax are optional. If gross is not provided, it defaults to value. 

### Address Object used for shipping, billing, and customer addresses:
json
{
  "addressId": "addr123",           // Unique address identifier (optional)
  "name": "John Doe",               // Full name
  "company": "Acme Inc",            // Company name (optional)
  "addressLine1": "123 Main St",    // Primary address line
  "addressLine2": "Suite 100",      // Secondary address line (optional)
  "city": "New York",               // City
  "state": "NY",                    // State/province (optional)
  "postalCode": "10001",            // Postal/ZIP code
  "country": "United States",       // Country name
  "countryCode": "US",              // ISO country code (optional)
  "tags": ["shipping", "default"],  // Address tags (optional)
  "isDefault": true                 // Whether this is the default address (optional)
}

### Item Object used for cart items, order items, and quote items:
json
{
  "productId": "prod123",           
  "name": "Product Name",           
  "image": "https://...",           
  "quantity": 2,                     
  "unitPrice": { /* Price Object */ },  
  "totalPrice": { /* Price Object */ }
}
**Note:** For simplified preview items in lists, only productId, name, image, and quantity are required. 

## Response Types 

#### 1. Cart Summary (cart_summary)
json
{
  "type": "cart_summary",
  "data": {
    "totalItems": 5,
    "siteCode": "main",
    "items": [
      { /* Item Object */ } // the price fields are mandatory
    ],
    "subtotal": { /* Price Object */ },
    "total": { /* Price Object */ },
    "currency": "EUR"
  }
}
#### 2. Order Summary (order_summary)
json
{
  "type": "order_summary",
  "data": {
    "totalItems": 5,
    "siteCode": "main",
    "orderId": "ORD-001",
    "date": "2025-01-15T10:00:00Z",
    "status": "delivered",
    "statusColor": "#10B981",
    "items": [
      { /* Item Object */ }
    ],
    "shippingAddress": { /* Address Object */ },
    "billingAddress": { /* Address Object */ },
    "shipping": { /* Price Object */ }, // take the values from calculatedPrice.totalShipping
    "payment": {
      "status": "PAID",
      "method": "invoice"
    },
    "subtotal": { /* Price Object */ }, // take the values from calculatedPrice.price
    "total": { /* Price Object */ }, // take the values from calculatedPrice.finalPrice
    "currency": "EUR"
  }
}
#### 3. Order List (order_list)
json
{
  "type": "order_list",
  "data": {
    "orders": [
      {
        "totalItems": 5,
        "siteCode": "main",
        "orderId": "ORD-001",
        "date": "2025-01-15T10:00:00Z",
        "status": "delivered",
        "statusColor": "#10B981",
        "items": [
          { /* Item Object */ }
        ],
        "total": { /* Price Object */ },
        "currency": "EUR"
      }
    ],
    "pagination": { "page": 1, "totalPages": 5, "totalItems": 47 }
  }
}
**Note:** The total field uses Price Object format. Extract values from calculatedPrice.finalPrice (netValue → net, grossValue → gross, taxValue → tax). 

#### 4. Product List (product_list) 
**IMPORTANT: Use ONLY for actual products. NOT for quotes/orders/returns.**
json
{
  "type": "product_list",
  "data": {
    "context": "Search results for...",
    "products": [
      {
        "productId": "prod123",
        "name": "Product Name",
        "price": 29.99,
        "currency": "EUR",
        "image": "https://..."
      }
    ]
  }
}
#### 5. Product Selection (product_selection) 
**The view should be used especially when user asks for product recommendations, set of products to buy.**
json
{
  "type": "product_selection",
  "data": {
    "message": "Please select a variant",
    "variantGroups": [
      {
        "groupId": "size",
        "message": "Select size",
        "items": [
          {
            "itemId": "var1",
            "name": "Small",
            "price": 29.99,
            "currency": "EUR"
          }
        ]
      }
    ]
  }
}
#### 6. Address List (address_list)
json
{
  "type": "address_list",
  "data": {
    "message": "Your saved addresses",
    "addresses": [
      { /* Address Object */ }
    ]
  }
}
#### 7. Account Details (account_details)
json
{
  "type": "account_details",
  "data": {
    "personalInfo": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "[phone]",
      "company": "Acme Inc",
      "customerNumber": "CUST123",
      "preferredLanguage": "en_US",
      "preferredCurrency": "EUR",
      "lastLogin": "2025-01-15T10:30:00Z"
    },
    "addresses": [
      { /* Address Object */ }
    ]
  }
}
#### 8. Return List (return_list)
json
{
  "type": "return_list",
  "data": {
    "returns": [
      {
        "id": "ret123",
        "approvalStatus": "approved",
        "received": false,
        "orders": [
          {
            "id": "ord123",
            "items": [
              {
                /* Item Object with additional fields: */
                "reason": { "code": "defective", "details": "Item damaged" },
                "total": { /* Price Object */ }  // Note: uses "total" instead of "totalPrice"
              }
            ]
          }
        ],
        "reason": { "code": "defective", "details": "Damaged on arrival" },
        "total": { /* Price Object */ },
        "expiryDate": "2025-12-31T23:59:59Z"
      }
    ]
  }
}
#### 9. Return Details (return_details) 
Same structure as Return List, but for single return with message field. 

#### 10. Quote List (quote_list) 
**CRITICAL: Use for quotes. NEVER use product_list for quotes.**
json
{
  "type": "quote_list",
  "data": {
    "quotes": [
      {
        "quoteId": "q123",
        "reference": "Q1000010",
        "status": "OPEN",
        "statusColor": "#3B82F6",
        "submittedDate": "2025-01-15T10:00:00Z",
        "validTo": "2025-02-15T23:59:59Z",
        "totalGross": 150.00,
        "totalNet": 125.00,
        "totalVat": 25.00,
        "currency": "EUR",
        "itemCount": 3,
        "previewItems": [
          { /* Item Object (simplified: productId, name, image, quantity) */ }
        ]
      }
    ],
    "pagination": { "page": 1, "totalPages": 3, "totalItems": 28 }
  }
}
**Status:** CREATING, OPEN, IN_PROGRESS, DECLINED, ACCEPTED, ORDER_CREATED, CLOSED 

#### 11. Quote Details (quote_details) 
**CRITICAL: Use for single quote details or creation. NEVER use product_list for quotes.**
json
{
  "type": "quote_details",
  "data": {
    "message": "Quote created successfully",
    "quoteId": "q123",
    "reference": "Q1000010",
    "status": "OPEN",
    "submittedDate": "2025-01-15T10:00:00Z",
    "validTo": "2025-02-15T23:59:59Z",
    "currency": "EUR",
    "totalGross": 150.00,
    "totalNet": 125.00,
    "totalVat": 25.00,
    "items": [
      { /* Item Object */ }
    ],
    "shippingAddress": { /* Address Object */ },
    "shippingCost": 10.00,
    "userComment": "Please deliver by end of month"
  }
}
#### 12. Text Response (text)
json
{
  "type": "text",
  "data": {
    "message": "Your order has been placed successfully!",
    "formatting": "plain"
  }
}
#### 13. HTML Response (html) used for rich HTML-formatted content when plain text is insufficient:
json
{
  "type": "html",
  "data": {
    "html": "<div></div>"
  }
}
**Guidelines:** - Use semantic HTML elements (<div>, <p>, <ul>, <ol>, <h1>-<h6>, <strong>, <em>, etc.) - Use Tailwind CSS classes for styling (e.g., class="text-text-headings font-semibold") - Make sure the generated HTML has modern design. 

#### 14. Table (table) used for tabular data representation (orders, products, quotes, etc.):
json
{
  "type": "table",
  "data": {
    "title": "Order Summary",
    "headers": ["Order #", "Date", "Status", "Items", "Total"],
    "rows": [
      ["ORD-001", "2025-01-15", "Delivered", "3", "€150.00"],
      ["ORD-002", "2025-01-20", "Processing", "2", "€89.99"]
    ],
    "columnTypes": ["text", "date", "status", "number", "currency"]
  }
}
**Column Types:** text, number, currency, date, status, boolean, link 

#### 15. Error Response (error)
json
{
  "type": "error",
  "data": {
    "errorCode": "PRODUCT_NOT_FOUND",
    "message": "The requested product could not be found",
    "canRetry": false
  }
}

MCP Servers

The Frontend Agent uses the tools that originate from the Emporix Frontend MCP Server that is by default attached to the agent. See the Frontend MCP Tools. The tools allow the agent to get relevant information and perform an action on behalf of a customer.

The Frontend Agent uses the Frontend MCP Server in the background. The MCP provides the tools required to get instant information or perform an action on behalf of a customer on entities such as customer, address, product, order, return, cart, quote, and checkout. The Frontend MCP Server is required for smooth operation of the Frontend Agent.

If needed, add more Emporix or custom MCP tools.

AI Tools

If you want the agent to provide product recommendations and allow semantic search, attach the RAG AI Tools to the agent. RAG tools are responsible for indexing products with RAG embeddings that are based on the selected properties. The RAG Tools are not attached by default as you need to add these tools in the AI Tools view first and configure, based on your products specifics, which product properties are to be indexed to improve products searchability. You have a choice to use the Emporix RAG tool or your custom one.

If you add RAG AI Tool with a product entity to the Frontend Agent, it is recommended to disable get-products tool that stems from Frontend MCP Server.

The get-products tool fetches the products that match the keyword based on the contains method, while the RAG tools enable semantic search that ensures better interpretation of the context, user's intent and relationship between the words.

All Agents operations are tracked in the AI Logs view. You can check the details of the requests, jobs, and sessions for monitoring and evaluation purposes. For more information, see the AI Logs.