This tutorial is written by Samuel Molling.
A customer support agent looks simple from the outside: a chat box where someone asks a question and gets an answer. However, behind that interface, the job is less simple. The answer might be in product documentation, in a support ticket another agent resolved months ago, in the customer's own account data, or nowhere the agent is allowed to act on its own.
At the center of this lab is a retrieval-augmented generation (RAG) pipeline built on MongoDB Atlas. A question is embedded and searched against document chunks with Atlas Vector Search, while Atlas Search retrieves lexical matches from whole articles. The ranked lists are combined with Reciprocal Rank Fusion, the strongest candidates are reranked with a cross-encoder, and the best passages are passed to an LLM as context for the answer.
That pipeline works well when the input is a self-contained search query. Customer support is different.
A customer rarely asks one perfectly self-contained question. They ask something, clarify it, refer back to a previous answer, ask about their own account, and sometimes request something the agent should not handle at all.
Consider this conversation:
- Does your product support SAML SSO?
- Is it available on the Pro plan?
- And how much is that?
The last question is almost useless as a retrieval query. There is no product, feature, or plan name in it. Its meaning exists because of the conversation before it.
And retrieval is only one part of the problem. Across a support session, one answer might come from documentation, another from a previously resolved ticket, another from operational customer data, and sometimes the correct next step is not an answer at all. It is a human.
This article builds the layers a support agent needs around that retrieval pipeline: query rewriting, conversation memory, multiple corpora, customer entitlements, operational tools, confidence, and escalation.
Example of the console answering as the Enterprise customer. The inspection panel shows the condensed question, the classification, the confidence band, and the five passages that survived fusion and reranking.
What changes when the query becomes a conversation
The unit of work moves from answering one query with one passage to resolving a whole conversation. That sounds like a UX change, but it is a data modeling change, a security change, and a control flow change.
Consider a real fourth turn: “and how much is that?” Five words. No product, no plan, no verb worth embedding. Send it to a vector index as written, and it retrieves noise, because the vector is computed from a sentence that means nothing on its own. The failure surfaces as bad retrieval, and the engineer goes and tunes numCandidates.
Now consider what the customer actually needs across a session. The answer to turn one lives in documentation. The answer to turn two lives in a resolved ticket from eight months ago, because a human already solved this exact thing and wrote it down. The answer to turn three is the shipping status of order ORD-1042, which lives in an operational collection and is not a retrieval problem at all. The answer to turn four is that this customer wants to cancel, and no passage in any corpus authorizes the agent to handle that.
Four turns, four different data sources, one of which is a person. The retrieval pipeline handles one of them.
The full per-turn flow in this implementation:
One turn of the agent, end-to-end. Condensation runs first and can skip retrieval entirely. Escalation is evaluated before generation, not after it.
Stages 2 and 3 run against the same Atlas cluster that holds the transcript. That matters more than it may sound, and I will come back to it.
Condensation: rewrite, and do not answer
Before a turn can be retrieved against, it has to be made self-contained. One LLM call in JSON mode rewrites the turn and classifies it at the same time, because both need identical context and a second round trip would double per-turn latency for no new information.
{
standaloneQuestion: "How much does SAML SSO cost?",
intent: "billing_question",
needsRetrieval: true,
needsTools: [],
sentiment: "neutral",
mentionedOrderId: null
}
The interesting part of the prompt is not the instruction. It is the prohibition.
An unconstrained rewriter is an efficient machine for inventing facts. Given "and how much is that?" after a thread about SSO, it happily produces:
How much does SAML SSO cost on the Pro plan for a 50-seat team billed annually?
Three constraints the customer never said. Plan, seat count, billing period. Each one prunes the candidate set inside the index. The passage that would have answered the question is now unreachable, and nothing in the logs says the query was fabricated. What you see is a reasonable-looking question that returned bad results.
Over-condensation fails silently and reads as a retrieval bug. That is why the system prompt spends more words on what not to do than on the task:
- Do NOT answer the question. You are not the support agent.
- Do NOT add any constraint, number, product name, plan name, version,
quantity, or qualifier that the customer did not actually say.
- Do NOT resolve ambiguity by guessing. If "it" is genuinely unclear, keep
it vague rather than picking a referent.
- DO resolve pronouns and elisions that the earlier turns make unambiguous.
needsRetrieval is the other half of the call, and it covers the entire stage. When a customer types "thanks, that worked", the classifier returns false and the turn skips embedding, two vector searches, a rerank, and five passages in the prompt. Running the full pipeline on every turn is most of the per-turn cost of a naive agent, and a meaningful share of turns in a real support thread are acknowledgments.
JSON mode guarantees syntactically valid JSON. It does not guarantee a valid shape. Every field gets clamped to a closed set before anything downstream reads it:
const intent = INTENTS.includes(obj.intent) ? obj.intent : "other";
An unrecognized intent that slips through would bypass the escalation policy without ever being tested against it. Clamping is not a defensive style. It is the thing that keeps a classifier hallucination from becoming a policy bypass.
Memory in three layers
Conversation state is the part of this system where the obvious data model is wrong in three directions at once.
The obvious model puts messages in an array on the conversation document. It preserves locality, one findOne returns everything, and the shape mirrors the application. It degrades as follows.
Every append rewrites the entire document. Turn 40 rewrites 39 turns of text to add one line, so write amplification grows linearly with conversation length. The working set is sized by the longest conversation instead of the median one, because any read of that conversation pulls every turn into cache, and one customer who never closes the widget inflates the memory profile of the whole collection. And there is a hard wall at 16MB. It is far away. A persistent enough user will find it, and when they do, the failure is an unhandled write error on an ordinary message.
Messages live in their own collection:
messages: {
_id, conversationId, seq, role, content, meta: {}, createdAt
}
With { conversationId: 1, seq: -1 }, the "last K turns" read is an index scan and appends stay constant-time regardless of length.
On top of the transcript sit two more layers, both on the conversation document:
conversations: {
_id, customerId, status,
summary, // rolling prose digest
facts, // extracted identifiers
turnCount, failedTurns, lastIntent,
createdAt, updatedAt, expiresAt?
}
The context window sent to the model is summary + last K verbatim turns + facts. That budget is fixed. Replaying the whole transcript instead means cost and latency grow with conversation length, which is exactly backward, because the longest conversations are the ones already going badly.
The summary regenerates every 6 turns, not every turn. Summarizing on every turn doubles the LLM calls to restate information that changes slowly, since the digest of turns 1 through 20 is nearly identical to that of turns 1 through 21. The verbatim window covers whatever the summary has not absorbed yet.
The facts array exists because the summarizer is a paraphraser by construction. Ask a model to compress a conversation, and it will smooth "ORD-1042" into "the customer's recent order" somewhere around turn fifteen. The summarizer prompt demands verbatim preservation of every identifier, error code, product name, and stated constraint, and I still would not bet a customer interaction on it. The structured layer is where the order ID survives, because nothing there is trying to make the text read better.
TTL that expires sessions but not customers
One index deserves its own explanation:
{ key: { expiresAt: 1 }, name: "conversations_ttl_anonymous", expireAfterSeconds: 0 }
A TTL index only expires documents that have the indexed field. Documents without expiresAt are ignored forever. And expiresAt is written in exactly one place, when an anonymous visitor starts a session.
So the rule this expresses is that an anonymous session is a cache and a signed-in customer's conversation is not.
A uniform TTL across all conversations is the version that looks tidier and is data loss in slow motion. A customer's support history is operational data with a retention policy, a compliance story, and a "what did you tell me in March" question attached to it. Deleting it on a rolling 30-day window destroys that record silently, one document at a time, with no error and no backup. You find out when someone asks for the March conversation.
Two corpora: documentation and resolved tickets
Documentation describes the product as designed. Tickets describe it as experienced. Those are different corpora, and the second one is not optional, because the phrasing gap between them is where support actually happens.
An error is documented like this:
AUTH_302 is returned when the SAML assertion presented by the identity provider carries an Audience URI that does not match the Entity ID configured for the workspace.
A customer reports it like this:
_I get bounced back to the login page after signing in with Okta
_
Those two texts share almost no vocabulary. A resolved ticket written by the agent who fixed it sits in the middle, phrased in symptoms and closed with the resolution, and it is what actually matches the customer's words.
So the pipeline runs three rankers over two corpora and fuses them:
weights: {
kbChunks: 1.0,
kbArticles: 0.7,
tickets: 0.5,
}
Fusion is Reciprocal Rank Fusion with per-ranker weights. RRF fuses by rank and never by raw score, because BM25 is unbounded and cosine similarity lives in [0,1], and normalizing them against each other means inventing a conversion nobody can defend.
score(doc) = Σ over rankers weight_r × 1 / (k + rank_r(doc)) // k = 60
MongoDB 8.1 ships $rankFusion as a native stage. The lab implements RRF by hand so the arithmetic is visible; production on 8.1+ should prefer the stage.
The ticket ranker carries two adjustments that documentation does not.
Recency decay. A resolution from eighteen months ago may describe a console screen that no longer exists. The ticket's contribution halves every 180 days:
export function recencyDecay(resolvedAt, now = new Date()) {
if (!resolvedAt) return 0.5; // unknown age: assume one half-life
const ageDays = (now.getTime() - new Date(resolvedAt).getTime()) / 86_400_000;
if (!Number.isFinite(ageDays) || ageDays <= 0) return 1;
return Math.pow(0.5, ageDays / tuning.ticketHalfLifeDays);
}
An old ticket can still win when nothing else matches. A fresh document outranks it whenever one exists.
A quality bar, enforced in the index. Only status: "resolved" tickets with quality >= 0.7 are eligible:
filter: {
status: { $eq: "resolved" },
quality: { $gte: tuning.ticketMinQuality },
...(customer.locale ? { locale: { $eq: customer.locale } } : {}),
A ticket corpus that includes unresolved threads or wrong answers is a machine for reproducing past mistakes at scale, and it does it in the confident register of a closed case. Both conditions are filter fields on the vector index rather than a downstream $match, for the reason in the next section.
Embed the rewrite, rerank the original
One subtlety that took me a while to see clearly.
The condensed question is what gets embedded. That is the whole point of condensation, since the vector has to come from a self-contained sentence.
The reranker gets the original turn.
const rerankQuery = originalMessage?.trim() || condensedQuestion;
const ranked = await rerank(rerankQuery, docs, tuning.topPassages)
The rewrite is a lossy transformation optimized for embedding similarity. It drops tone, urgency, and the customer's own phrasing to produce a clean retrievable sentence. That is the right input for an approximate nearest-neighbor index and the wrong input for judging relevance. The reranker is a cross-encoder that reads query and passage together, so it should see what the customer actually wrote, including the words the rewrite threw away.
Feeding the rewrite to both stages is the default that nobody questions, and it quietly costs precision on exactly the turns where the customer was most specific.
Entitlement belongs in retrieval
This is an authorization boundary, not a prompt instruction.
A Free-plan customer must never be answered out of an Enterprise-only runbook. That is an authorization requirement, and it has a correct implementation and two popular incorrect ones.
The correct implementation is a filter field evaluated inside the vector index:
export function entitlementFilter(customer = {}) {
const filter = {
audience: { $in: audienceFor(customer.plan) },
status: { $eq: "published" },
};
if (customer.locale) filter.locale = { $eq: customer.locale };
return filter;
Passed to $vectorSearch as a filter, this means the Enterprise passage is never scored. Not scored and then hidden. Never scored, so it never enters the candidate set, never reaches the reranker, and cannot appear in the prompt.
The same question asked as the Free customer. Seventeen chunks were scored instead of twenty-two, the audit-log article is absent, and the best remaining passage is a tangential ticket at 0.563 -- weak, not strong.
The first incorrect implementation is a prompt instruction. "Only use passages the customer is entitled to see." That is not a control. It is a request, addressed to a component whose entire job is to be agreeable, evaluated after the restricted text is already in the context window. Once it is in the prompt, it is one clever question away from being in the answer.
The second incorrect implementation is a $match after $vectorSearch, which is better and still wrong. limit is applied by the index. Filtering afterward silently shrinks the result set instead of changing it. Ten Enterprise hits and the Free customer gets an empty page, which is correct on paper and broken in the product.
The BM25 ranker needs the same guarantee, and $search has no filter field. The restriction goes into the compound query itself, still evaluated by the index:
compound: {
should: [ /* title, content, tags */ ],
filter: [
{ in: { path: "audience", value: audienceFor(customer.plan) } },
{ equals: { path: "status", value: "published" } },
],
minimumShouldMatch: 1,
}
That in operator carries a trap worth naming, because it cost me a working ranker and said nothing about it.
in and equals do not match a field indexed as an analyzed string. They return 0 hits, with no error. Map the filtered fields as token instead:
tags: { type: "string", analyzer: "lucene.keyword" }, // scored, stays a string
audience: { type: "token" }, // filtered, never scored
locale: { type: "token" },
status: { type: "token" },
With audience mapped as a keyword-analyzed string, the compound filter silently discarded every document, and the BM25 ranker returned nothing on every query. Vector search still worked, results still looked reasonable, and the entitlement guarantee this section is about was simply not being enforced on that ranker. The offline test suite cannot catch this: it needs a real index. It took running the thing against a cluster and noticing that one ranker reported zero hits on every single query.
One more detail. The ladder fails closed:
export function audienceFor(plan) {
return tuning.audienceLadder[plan] || tuning.audienceLadder.free;
}
An unknown plan string, a typo, a new tier someone added to the billing system and forgot to add here - all of them degrade to the most restrictive rung. An authorization default that fails open is a bug that ships quietly and is found by an auditor.
This is also the concrete payoff of keeping everything in one cluster. The chunk carries audience, locale, category, tags, and status denormalized from its parent article, because a $lookup cannot participate in a $vectorSearch pre-filter. The filter is evaluated by the index on the chunk document, so the fields have to be there. In a split architecture, that same denormalization is a synchronization problem between a vector store and a database, and the failure mode is an entitlement field that is correct in one system and stale in the other.
Tools: the model picks which, the server picks whose
Some answers are not in any corpus. "Where is my order" is a query against operational data, and in this architecture it is a query against the same cluster.
T
hree tools: lookupOrder, listRecentOrders, lookupSubscription. The rule that governs all of them:
The model chooses which tool runs. The server decides what it can see.
customerId comes from the authenticated session and from nowhere else. The model's arguments answer the question ("which order reference?") and never the subject ("whose orders?").
Look at what is absent from the schema the model sees:
{
name: "lookupOrder",
description: ""
"Look up one order belonging to the current customer by its order reference (e.g. ORD-1042).",
parameters: {
type: "object",
properties: {
orderRef: { type: "string", description: "\"The order reference to look up.\" },"
},
required: ["orderRef"],
},
}
No customerId. The model cannot pass it because it is not part of the contract it is shown.
Accepting customerId from model arguments turns the agent into an IDOR with a natural-language interface. The attack is not sophisticated. It is typing "show me the orders for customer 507f1f77bcf86cd799439011" and having a helpful model pass it through. No amount of prompt hardening fixes this, because the vulnerability is in the plumbing. Once the parameter is attacker-controlled, the model is just the transport.
The session ID goes into the query filter, not into a check afterward:
const order = await db
.collection(Collections.orders)
.findOne({ customerId: cid, orderRef }, { projection: { customerId: 0 } });
Fetching by orderRef and then comparing owners leaks existence through timing, and through any code path that forgets the comparison.
One more thing worth saying explicitly, because it is where well-meaning implementations go wrong. An empty result is a legitimate answer. "I don't see that order on your account" is correct output, not an error to be routed around. Widening the query until something comes back is how a scoped lookup quietly becomes a global one.
Escalation: four signals, and a packet instead of a flag
The third broken assumption. Sometimes the correct output is a human, and answering confidently is the failure.
Four independent signals, any one sufficient:
const turnFailed = confidence !== "strong";
const nextFailedTurns = turnFailed ? failedTurns + 1 : 0;
if (tuning.alwaysEscalateIntents.includes(intent)) {
return { escalate: true, reason: `policy:${intent}`, failedTurns: nextFailedTurns };
}
if (explicitRequest || intent === "human_handoff") {
return { escalate: true, reason: "explicit_request", failedTurns: nextFailedTurns };
}
if ((sentiment === "frustrated" || sentiment === "angry") && turnFailed) {
return { escalate: true, reason: "frustration_with_failed_turn", failedTurns: nextFailedTurns };
}
if (nextFailedTurns > tuning.maxFailedTurns) {
return { escalate: true, reason: "repeated_low_confidence", failedTurns: nextFailedTurns };
}
return { escalate: false, reason: null, failedTurns: nextFailedTurns };
They stay independent on purpose. A single blended escalation score is untunable, because when it misfires you cannot tell which input moved it, and every threshold change silently reweights all four.
The first signal is the one people leave out. cancellation, refund_request, billing_dispute, data_deletion, legal escalate on arrival, whatever retrieval found. Confidence is irrelevant, because finding a perfect passage about the refund policy does not give the agent authority to issue a refund. These are authority boundaries, not knowledge gaps, and a confident answer there is worse than no answer.
The third signal is deliberately a conjunction. Frustration alone does not escalate, since an annoyed customer who is being answered well is being helped. Frustration on a turn that also failed means the agent is making things worse, and one more attempt is one more reason to cancel the subscription.
The fourth counts consecutive failures, and one strong answer resets it. A customer who got a good answer and then asks about something new is not two-thirds of the way to a handoff.
Confidence comes from the reranker rather than from vector distance or BM25 in isolation. In the seeded corpus, a top rerank score at or above 0.6 is strong, 0.45 to 0.6 is weak, and below that is none. A passage that answers the question lands around 0.79 to 0.88, a tangential one around 0.56, a wrong retrieval on an un-condensed turn around 0.44, and an out-of-corpus question around 0.33. These are calibration values for this corpus, not universal thresholds.
The handoff is more than a status
status: "escalated" tells the human nothing. They open the conversation, read fourteen turns, and repeat every question the bot already asked. That is precisely the experience behind "I had to explain everything twice."
The packet is what the agent knows, serialized:
{
reason: "repeated_low_confidence",
intent: "troubleshooting",
askedFor: "Why does SAML sign-in fail with Okta?",
sentiment: "frustrated",
customer: { name, email, plan, seats, subscriptionStatus, renewsAt },
conversation: { turnCount, failedTurns, summary, facts },
attempted: {
confidence: "none",
topRerankScore: 0.21,
passages: [{ kind, title, breadcrumb, rerankScore }],
tools: [{ tool, ok, found }],
},
}
A cancellation escalates on arrival. Retrieval is skipped, confidence is none, and the panel carries the handoff packet rather than a flag.
attempted is the part that earns its place. With rerank scores attached, the human can tell a knowledge gap (nothing relevant existed) from a retrieval miss (something relevant existed and ranked badly). Those need completely different fixes, and the distinction is invisible without the numbers.
Deflection is not resolution
Deflection rate is the number that looks good on a slide. Conversations that ended without a human, divided by total conversations.
A customer who gives up in frustration and closes the tab counts as a deflection. So does one who was told something wrong and believed it. Optimizing for deflection rewards an agent that is hard to escalate out of, which is the opposite of the goal.
Resolution rate is the honest number, and it cannot be inferred from the transcript, because "ok thanks" is what people type both when it worked and when they have given up. It has to be collected, which is why there is a feedback endpoint and why the admin endpoint reports both numbers side by side. The gap between them is the interesting part.
The other thing the per-message metadata buys is the docs backlog. Every turn stores its confidence band and condensed question:
meta: {
intent: condensed.intent,
confidence: retrieval.confidence,
condensedQuestion: condensed.standaloneQuestion,
topRerankScore: retrieval.topScore,
escalated: decision.escalate,
passageCount: retrieval.passages.length,
model,
}
One aggregation over the weak and none turns, grouped by intent, is a ranked list of what the documentation does not cover, in the customer's own phrasing:
[
{
$match: {
role: "assistant",
"meta.confidence": { $in: ["weak", "none"] },
},
},
{
$group: {
_id: "$meta.intent",
count: { $sum: 1 },
avgTopScore: { $avg: "$meta.topRerankScore" },
escalated: { $sum: { $cond: ["$meta.escalated", 1, 0] } },
examples: { $addToSet: "$meta.condensedQuestion" },
},
},
{
$project: {
_id: 0,
intent: "$_id",
count: 1,
escalated: 1,
avgTopScore: { $round: ["$avgTopScore", 3] },
examples: { $slice: ["$examples", 5] },
},
},
{ $sort: { count: -1 } },]
Backed by { "meta.confidence": 1, "meta.intent": 1 }. This is the editorial backlog derived instead of guessed, and it is a better source of article titles than any planning meeting, because the phrasing comes from the people who could not find the answer.
That aggregation is also the second payoff of one cluster. The agent's confidence signal and the analytics query are the same documents in the same database. No export job, no warehouse sync, no window where the two disagree.
What this lab does not solve
The lab is deliberately not production-ready, and the gaps worth naming:
customerId arrives in the request body. The tool boundary treats it as the authoritative session identity, which is the right shape, but in production that value comes from a verified session. Retrieved passages and ticket text go into the prompt as-is, so prompt injection through a hostile document is unaddressed and needs its own treatment. Transcripts are stored in the clear, and real support data needs field-level encryption, redaction, and a retention policy per jurisdiction. There is no evaluation harness, which is what you would actually need before touching any threshold in the tuning object.
That last one is the honest limitation. The confidence bands are measured against the seeded corpus; every other number here is a defensible starting point rather than a measured optimum. The weights, the half-life, the tolerance of two failed turns. They are all in one file for exactly that reason:
export const tuning = {
rrfK: 60,
weights: {
kbChunks: 1.0,
kbArticles: 0.7,
tickets: 0.5,
},
vectorNumCandidates: 200,
vectorLimit: 40,
keywordLimit: 30,
ticketLimit: 20,
rerankShortlist: 20,
topPassages: 5,
ticketHalfLifeDays: 180,
ticketMinQuality: 0.7,
confidence: {
strong: 0.6,
weak: 0.45,
},
maxFailedTurns: 2,
alwaysEscalateIntents: [
"billing_dispute",
"cancellation",
"refund_request",
"data_deletion",
"legal",
"human_handoff",
],
verbatimTurns: 6,
summarizeEveryTurns: 6,
anonymousSessionTtlDays: 30,
maxChunkSize: 1500,
audienceLadder: {
free: ["all"],
pro: ["all", "pro"],
enterprise: ["all", "pro", "enterprise"],
},
};
When these live scattered across five modules, nobody can answer "why did the agent escalate that conversation?" without reading all five.
Conclusion
The retrieval pipeline is only the center of the system. Atlas Search, Atlas Vector Search, fusion, and reranking can retrieve relevant context, but a support conversation adds a different set of problems around that pipeline.
What a conversation adds is a set of problems that live entirely outside retrieval. A turn that has to be rewritten before it can be embedded, and a rewriter that will invent constraints if you let it. State that has to be budgeted rather than accumulated. A second corpus that is more useful and less trustworthy than the first. An authorization boundary that only holds if it is enforced by the index. And a class of request where the correct behavior is to stop.
Every one of those is a data modeling decision before it is a prompt engineering decision. The transcript layout determines whether memory scales. The filter field determines whether entitlement is a guarantee or a suggestion. The per-message metadata determines whether the docs backlog is a query or a meeting. In Atlas, all of it is the same cluster, the same aggregation language, and the same access control as the operational data the agent is reasoning about.
A support agent is not a chatbot with retrieval attached. It is a system that has to know what it does not know, and know when the answer is a person.
The full lab is on GitHub at SamuelMolling/mongodb-labs/tree/main/support-chatbot, with a make smoke suite that runs offline without an Atlas cluster or API keys. The chunker, entitlement ladder, and escalation policy are pure functions, so those parts of the application can be tested independently of the external services around them.
