> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval Test

> See exactly what your agent would retrieve for a question — and what it costs — before spending a chat turn.

The **Retrieval Test** runs your agent's *live* retrieval against a question you type and shows you everything it found — no reply is generated and nothing is sent to the chat model. You're inspecting the retrieval step in isolation. It sits at the bottom of the [Knowledge](/sidebar-menu/knowledge) (Retrieval) page.

Use it to answer "why did my agent give that answer?" or "is my knowledge base actually being found?" without burning a real conversation turn debugging it. There are two ways to run it:

* **Test all methods** — runs every retriever side by side (keyword, semantic, the static lane, external stores, the knowledge graph, tables, documents) so you can see what each one finds on its own. It skips the LLM reranker, so the only cost is a couple of query embeddings — a small fraction of a credit.
* **Run full pipeline (billed)** — reproduces exactly what a real owner interaction retrieves, reranker included, and charges your account in credits.

<Note>
  **Run full pipeline** runs the **same** retrieval code your agent uses in production — across all data scopes, with the reranker firing exactly as it would in a real interaction. **Test all methods** runs the same retrievers but stops before the reranker, so it stays near-free. Subscriber files only retrieve for a subscriber caller, so they don't appear in either view.
</Note>

## Running a test

Type a statement or question, then click one of the two buttons.

### Test all methods — the free probe

**Test all methods** fires every retriever independently and lays their results out side by side, so you can see exactly which store found what. It returns:

* **A per-method summary** — timings for the keyword, vector and static (Model2Vec) lanes, whether each is configured, and the query's lexicality score (used by adaptive routing).
* **Per-scope breakdown** — for **Internal data** and **Public data** separately: the **Keyword**, **Vector (semantic)** and **Static (Model2Vec)** hits, each with its score and preview, then the **Fused (RRF)** list that combines them — with a badge on each fused hit showing which retrievers agreed.
* **External vector stores** — hits from any [external knowledge sources](/sidebar-menu/data-internal#external-knowledge-sources) you've connected.
* **Knowledge graph — entity matches** — the seed entities your query resolves to (reached via `knowledge_graph_query`), which expand to related triples.
* **Structured tables** — table hits answerable with `query_table`, with row counts and columns.
* **Documents** — decomposed documents openable with `list_documents` / `get_document`.

The static lane runs even when it's turned off, so you can evaluate it before enabling it. Because this probe skips the reranker, it's the cheap way to ask "is anything finding this at all, and which retriever?".

### Run full pipeline — the billed rerun

**Run full pipeline (billed)** reproduces a real interaction's retrieval phase, reranker and all. It returns four things:

#### 1. Retrieval trace

A stage-by-stage account of the search:

* **Search stages** — each source that was queried, how many candidates each returned, and a *skip reason* when a stage didn't run (e.g. "vector search not configured", "no public files uploaded").
* **RRF fusion** — how keyword and vector (semantic) results were merged per scope.
* **Rerank** — how many hits went in and came out per scope (kept top half per scope).
* **Selected for context** — the final chunks that would be injected into the agent's prompt, with title, scope, score and preview.

#### 2. The injected context block

The exact "retrieved context" text that would be added to the agent's system prompt for this question. A toggle reveals the full system prompt (platform directives + your agent config + the retrieved context).

#### 3. Cost incurred

Every model call the retrieval made — almost always just the reranker — itemised by tokens per bucket, the rate applied, and the resulting cost in USD and credits.

#### 4. Billing

The run is **charged to your account** in credits, exactly as a real interaction's retrieval phase would be. The summary shows the credits charged and your remaining balance. (Keyword search is local and free; the reranker is a real, billable model call — so the figure reflects true production cost.)

***

## Reading the results

**"Nothing was retrieved."** If the trace shows every stage returning zero candidates, your agent has no data to answer from. Check the skip reasons — common causes: no files uploaded to Internal/Public Data, or vector search not configured (which only affects semantic matching; keyword search still works).

**"The right document exists but wasn't selected."** Look at the scores in *Selected for context*. If your target chunk appears in a search stage but not in the final selection, it was out-scored. Raising retrieval depth/limit (on the [Knowledge](/sidebar-menu/knowledge) page for graph queries, or chunking config on [Internal Data](/sidebar-menu/data-internal)) or rephrasing the source document can help.

**"It found the keyword match but missed the semantic one."** If keyword search returned hits but vector returned zero with a skip reason, semantic search isn't running — embeddings aren't configured. Keyword search will still match exact terms, but paraphrased questions won't find paraphrased content until vector search is on.

***

## Examples

**Simple — confirm a document is findable.** You uploaded a refund policy and want to be sure the agent will find it. Type "what is your refund window?" and click **Test all methods** (free). If a chunk from the refund policy shows up under Internal data's fused results with a healthy score, you're good — the agent will have that text in front of it when a real user asks.

**Medium — diagnose a wrong answer.** A user reported the agent gave an outdated price. Type the user's exact question and click **Run full pipeline**. The trace shows you which chunk was selected — and if it's from an old document you forgot to delete, you've found the cause in one test instead of guessing.

**Complex — tune retrieval before going live.** You're preparing a knowledge-heavy agent. Run a representative set of hard questions through **Test all methods** first to see which retriever surfaces each answer (or misses it), then **Run full pipeline** on the tricky ones to watch the *Selected for context* scores and the rerank in/out counts. Where the right chunk is being out-ranked, adjust chunking or the [Knowledge](/sidebar-menu/knowledge) strategy, re-run, and compare — all without a single chat turn or a confused subscriber.

***

## Owner-only

Retrieval Test is available to the agent owner only — it's a build-time diagnostic, not a subscriber feature. It's the **Retrieval Test** section at the bottom of the **Retrieval** (Knowledge) page: reach it directly at `/dashboard/<agent>/retrieval`, or via the **Test retrieval & knowledge base** button on the **Public Data** page.