Vanuit het perspectief van een CTO laat dit project zien hoe je vectorzoekopdracht, traditionele filtering, prompt governance en lichte orkestratie kunt combineren tot een productie-veilige e-commerce agent. Het resultaat draait op Supabase, LangChain (n8n), OpenAI en LangFuse, met een React-voorkant op Vercel.

Hieronder vind je de architectuur en het redeneervermogen erachter.

Waarom we niet “gewoon een chatbot hebben toegevoegd”

Gereedschapsshoppers zijn niet op zoek naar inspiratie — ze lossen een probleem op. Hun zoekopdrachten omvatten doorgaans:

• Merkvoorkeuren (“Makita M-serie?”)

• Specifieke varianten (“M12 vs M18?”)

• Randvoorwaarden (budget, categorie, beschikbaarheid)

• Precisie op SKU-niveau

Generieke LLM-chat schiet hier tekort. Het hallucineert SKU's, mist categoriegrenzen en ontbreekt aan observeerbaarheid. We hadden een agent nodig die zich meer gedraagt als een getypte API-client dan een tekstgenerator — met gecontroleerde opmaak, deterministische ophalen en prompt governance.

Dit stelde de kernvereisten:

1. Hybride ophalen: gestructureerde filtering + pgvector semantische zoekopdracht

2. Deterministische uitvoerstructuur: altijd SKU-eerst, altijd markdown

3. Observeerbaarheid: traces, versieverd prompts, LLM-als-een-rechter scoring

4. Composteerbare orkestratie: geen monolithische backend, alleen tools + workflows

5. Vervangbare componenten: verwisselbare LLM, modulaire randfuncties, eenvoudige FE-integratie.

Het Architectonische Overzicht

We hebben de stack opgebouwd rond vier componenten:

1. Ervaringslaag:

   • React-chat widget op Vercel

   • Verstuurt berichten + sessie-ID naar een n8n webhook

   • Rendert gestructureerde markdown antwoorden
     
     

2. Orkestratielaag (n8n):

   • Haalt de nieuwste systeemprompt van LangFuse op

   • Draait een OpenAI 5.1 mini model als agent

   • Biedt twee door Supabase ondersteunde tools:

     • search-products

     • search-information

   • Zet de modeluitvoer om in een gestructureerde JSON-reactie

   • Logboeken naar Google Sheets voor lichte QA
     
     

3. Datalaag (Supabase):

   • Postgres voor gestructureerde productgegevens

   • pgvector voor semantische embeds

   • Randfuncties die zoekpunten aan de agent blootstellen

   • Fungeert als het centrale, getypte dataplatvorm
     
     

4. Content governance (LangFuse):

   • Slaat versieverte systeemprompts op

   • Vangt traces en toolgebruik

   • Draait LLM-als-een-rechter evaluaties voor regressietesten

   • Biedt analyses voor prompt iteratie

Deze architectuur houdt elk onderdeel geïsoleerd, vervangbaar en inspecteerbaar.

15.000 SKU's up-to-date houden: Magento → Supabase → pgvector

In plaats van de volledige catalogus opnieuw te indexeren, vertrouwen we op delta-invoer uit Magento:

1. Magento exporteert dagelijkse veranderinglogboeken (CRUD-operaties) naar een sFTP-locatie.

2. Een geplande Supabase randfunctie haalt en verwerkt de logboeken.

3. Elk gewijzigd product wordt genormaliseerd in:

   • Kernvelden (SKU, prijs, merk, categorie, voorraad)

   • Beschrijvende tekst voor embeds

4. We berekenen OpenAI embeds en updaten:

   • Postgres (gestructureerde gegevens)

   • pgvector (semantische laag)

Dit geeft de agent twee zoekprimitieven:

• Precisie via SQL-filters

• Flexibiliteit via semantische overeenkomst

Het is lichtgewicht, voorspelbaar en vermijdt koppeling aan de runtime-prestaties van Magento.

De agent betrouwbaar maken: een multi-step retrieval strategie

De belangrijkste beslissing was om de LLM niet te zien als een “chatmodel”, maar als een controller die deterministische zoekverzoeken produceert.

Alles wat de agent doet wordt gedefinieerd in de systeemprompt — toon, structuur, beperkingen en methodologie en wordt beheerst via LangFuse.

Clarify-First

Voor elke zoekopdracht moet de agent 1-3 gerichte vragen stellen als de query dubbelzinnig is (merk, categorie, prijs, aantal resultaten). Dit voorkomt retrieval drift en vermindert aanzienlijk irrelevante matches.

Intern Query Plan

De LLM moet intern een getypt JSON-queryplan construeren (maar niet weergeven) dat definieert:

• Intentie (zoeken, vergelijken, bladeren, order_note)

• Modus (close vs. wide)

• Beperkingen (merk, category_ids, min/max prijs, aantal resultaten)

• Toolconfiguratie (zoektype, toegestane categorieën, limiet, vorm)

Dit dwingt het model om expliciet te redeneren voordat het een tool-oproep maakt.

Close → Wide zoekpatroon

We handhaven een tweestaps zoekopdracht:

• Close modus

  • Beperk tot categorie-ID's (afgeleid van een begin-SKU of query)

  • Pas merk + prijsfilters toe

  • Gebruik hybride zoekopdracht als standaard

• Wide modus (fallback)

  • Automatisch geactiveerd indien close onvoldoende resultaten oplevert

  • Verwijdert categoriebeperkingen

  • Maakt gebruik van semantische/hybride ophalen over de volledige catalogus

Dit weerspiegelt hoe menselijke verkoopexperts afhankelijk van beschikbaar inventaris vernauwen → verbreden.

Post-Filtering & Diversiteit

Na ophalen moet de agent:

• Verwijder irrelevante of cross-category items

• Elimineer accessoires (strikte regel)

• Produceer maximaal drie opties

• Voorzie merk of variant diversiteit waar mogelijk

Tenslotte wordt het antwoord geformateerd in stabiele markdown met SKU-eerste bullets.

Dit is het verschil tussen “chatbot antwoorden” en ecommerce-grade productaanbevelingen.

Prompt governance & observeerbaarheid met LangFuse

Het project werkt alleen omdat we observeerbaarheid in de kern hebben gebouwd.

Versieverte prompts

LangFuse slaat de systeemprompt (borgh-chat-prompt) op als een versieverte artefact. n8n haalt bij elke aanvraag de nieuwste versie op. Dit stelt ons in staat:

• Gedrag bij te werken zonder implementatie

• Direct terug te draaien

• Gereguleerde A/B of gefaseerde uitrols uitvoeren

Traces & tool zichtbaarheid

Elke interactie logt:

• Gebruikersinvoer

• Systeempromptversie

• Tool-oproepen (search-products, search-information)

• Eindoutput

• Vertrouwensscores

Dit maakt de agent volledig inspecteerbaar — een niet-onderhandelbare vereiste voor commercieel gebruik.

LLM-als-een-rechter

We voeren geautomatiseerde evaluaties uit die controleren:

• Relevantie van aanbevolen producten

• Structurele naleving (markdown, SKU-eerste, max 3 opties)

• Toonconsistentie met de Borgh-persona

• Correctheid van “clarify-first” logica

Deze scores stellen regressietesten in staat voor elke prompt of retrievalwijziging, vergelijkbaar met traditionele API-gedragstests.

Lichte QA in Google Sheets

We vullen LangFuse aan met een Google Sheet-logboek voor menselijke QA, waardoor de beoordeling door stakeholders eenvoudig wordt zonder interne systemen bloot te stellen.

Wat komt daarna

Met retrieval, governance en UX fundamenten in place, zijn de volgende stappen eenvoudig, breid de agentopties uit naar:

• De mogelijkheid van de agent om kortingsdeals te maken voor laagste prijzen

• Klanten helpen om direct bij de agent te bestellen met Magento backend

• Klantondersteuning om te helpen met basis ondersteuningsacties zoals facturering, verzending en factureringsinformatie

Tenslotte, hier is een fijne print van de architectuur:

[ Shopper ]
   |
   v
[ Website (React, Vercel) ]
   |
POST message
   |
   v
[ n8n Orchestrator ]
   - Fetch prompt from LangFuse
   - LangChain AI Agent (OpenAI 5.1 mini)
   - Tools:
       * search-products (Supabase)
       * search-information (Supabase)
   - Parse output
   - Log to Sheets
   |
   v
[ Front-end renders structured markdown ]

Side connections:
[ LangFuse ] <-> prompts, traces, evaluations
[ Supabase ] -> Postgres + pgvector + edge functions
[ Magento ] -> sFTP -> Supabase ingestion job