Skip to content

How retrieval works

What happens between a visitor's question and the agent's answer — search, grounding, and the workspace boundary that keeps tenants apart.

The agent does not "know" your business. For every question, it searches your knowledge base, puts the best passages in front of a language model, and asks it to answer using only those passages. That loop is what this page describes.

The four steps

  1. 1
    The question arrives — from the widget, a channel, or the playground.
  2. 2
    Search. The question is matched against your chunks two ways at once: by

    meaning (a vector search, which finds "how do I get my money back" in a page titled Refund policy) and by wording (a keyword search, which reliably finds an exact product code). The two result lists are fused into one ranking, and FAQ pairs are boosted within it.

  3. 3
    Assemble. The top-ranked chunks — up to the chatbot's **max context

    chunks setting, and only those scoring above its similarity threshold** — become the context. Your system prompt, tone, and the recent conversation are added.

  4. 4
    Answer. The model writes a reply grounded in that context and streams it

    back word by word.

Both tuning knobs in step 3 are on Chatbot settings.

Note:

Retrieval is scoped to one chatbot inside one workspace. A search never reaches another workspace's chunks, so one tenant's content can never answer another tenant's question — and two chatbots in the same workspace do not share sources either.

When nothing matches

If no chunk clears the threshold, the agent does not improvise. It returns a deterministic fallback — your fallback message, or the default:

I couldn't find that in the knowledge base. Please contact our support team
for help.

No model call is made in that case, so a fallback is fast and cheap. Why this is the desired behaviour, and how to reduce how often it happens, is covered on Grounding and "I don't know".

Repeat questions

Before searching, the agent checks a short-lived cache of recent near-identical questions for the same chatbot. A hit returns the stored answer without a search or a model call — faster, and cheaper in credits.

Two rules keep that safe:

  • The cache is invalidated whenever the chatbot's knowledge changes, so an edit

    is not shadowed by a stale answer.

  • Only answers given with no prior conversation turns are cached. An answer

    shaped by an earlier part of someone's conversation is never reused for anyone else.

Sources

Retrieved sources are attached to the message as metadata, not written into the reply as [1]-style citations. You can see them in the playground's Debug panel; whether visitors see a source list is an appearance setting. See Appearance.

Where to go next

Last updated