# Search your documents

> Let the agent answer from your own documents: a source of your own or any vector store, the relevance threshold, citations, failures, and what it costs.

- URL: https://docs.mentoragent.net/configure/search-your-documents
- Verified with: MentorAgent 1.4.0
- Last updated: 2026-11-18
- Packages: Novior.MentorAgent

Use this page when the agent should answer from your own documents, such as manuals, price lists or support articles, and not only from your actions. Before each reply, MentorAgent searches your documents with the user's message and gives the best ones to the model, which cites them. This is called retrieval-augmented generation (RAG). MentorAgent does not store or index documents. It asks a source: a class that you write, or a vector store that you already have.

## When to choose it

- **Choose it** when the answers are in text: how a procedure works, what a contract says, which price applies.
- **Use an action instead** when the answer is a value in your data, such as the status of a case or the stock of a product. An action reads it from your services, with the user's roles: see [Roles, confirmation and governance](https://docs.mentoragent.net/concepts/governance).
- **The search runs on every message**, before the model is called, commands included. Each message costs one search, and one embedding of the message for a vector search: see [What it costs](https://docs.mentoragent.net/configure/search-your-documents#what-it-costs).

## Use a vector store

With a `Microsoft.Extensions.VectorData` collection (for example PostgreSQL with pgvector, Qdrant, Azure AI Search or an in-memory collection), you do not need to write a source. Describe the record, then register the collection with `AddMentorVectorStoreRag`:

```csharp title="Doc.cs"
public class Doc
{
    [VectorStoreKey] public Guid Id { get; set; }
    [VectorStoreData] public string Text { get; set; } = "";
    [VectorStoreData] public string? Title { get; set; }
    [VectorStoreData] public string? Url { get; set; }
    [VectorStoreData] public string? Tenant { get; set; }

    [VectorStoreVector(1536,
        DistanceFunction = DistanceFunction.CosineDistance)]
    public ReadOnlyMemory<float> Vector { get; set; }
}
```

```csharp title="Program.cs"
builder.Services.AddMentorVectorStoreRag(
    sp => sp.GetRequiredService<VectorStore>()
        .GetCollection<Guid, Doc>("docs"),
    new MentorVectorStoreRagOptions<Doc>
    {
        Content = d => d.Text,       // required
        Title = d => d.Title,
        SourceUrl = d => d.Url,
        // With a tenant resolver: the tenant's documents only
        Filter = request => d => d.Tenant == request.TenantId,
    });

builder.Services.AddMentorAgent(options =>
{
    options.UseRag = true;
    // options.EmbeddingGenerator = ...;
});
```

- **`Content` is required.** It is the text that the model reads. A record without text is left out.
- **`Title`, `SourceUrl` and `Metadata`** give the title and the link of the citation, and facts that the model reads under the title, such as "valid from: 2026-01-01".
- **`Filter` says which records a request may see**, built from the request: its user and its tenant. Without it, the whole collection is searched.
- **One source per application.** `AddMentorVectorStoreRag` throws when another `IMentorRagSource` is already registered.

### Scores and the threshold

MentorAgent keeps a document only when its score reaches the threshold, [`RagMinScore`](https://docs.mentoragent.net/reference/options#ragminscore). The vector store source reads every score as a similarity, higher is nearer, whatever the collection's distance function:

| Distance function of the collection | Score that the source uses |
|---|---|
| `CosineSimilarity`, `DotProductSimilarity` | As it is |
| `CosineDistance`, the default of PostgreSQL and pgvector | 1 minus the distance |
| `NegativeDotProductSimilarity` | Its negation |

The function comes from `DistanceFunction` in the options, or from the record's `[VectorStoreVector]` attribute. The application stops at startup when neither of them names a function, or when the function is a Euclidean, Manhattan or Hamming distance. These distances have no scale on which a threshold could be set. Without `RagMinScore`, the source's threshold is 0.5.

### PostgreSQL with pgvector

Use `CommunityToolkit.VectorData.PgVector`: its `PostgresCollection<TKey, TRecord>` is the collection to pass. Create the table before the first search, with the connector or with your migrations. Do not use the preview of `Microsoft.SemanticKernel.Connectors.PgVector` while it is built on an older `Microsoft.Extensions.VectorData`: every search then fails with `MissingMethodException`.

## Write your own source

For a search engine that is not a vector store collection, implement `IMentorRagSource`. MentorAgent calls `SearchAsync` with a `MentorRagRequest`: the message, how many documents to return, the user, the page, the tenant, and the last turns of the conversation.

```csharp title="ManualsSource.cs"
public class ManualsSource(IManualSearch search) : IMentorRagSource
{
    // Cosine similarity, from 0 to 1: keep what scores 0.6 or more
    public float? DefaultMinScore => 0.6f;

    public async Task<IReadOnlyList<MentorRagResult>> SearchAsync(
        MentorRagRequest request, CancellationToken ct = default)
    {
        // Internal manuals only for signed-in staff
        var staff = request.User?.IsInRole("Staff") == true;
        var hits = await search.SearchAsync(
            request.Query, request.MaxResults, staff, ct);

        return hits.Select(h => new MentorRagResult(
            Content: h.Text, SourceUrl: h.Url, Title: h.Title, Score: h.Score)
        {
            Metadata = new Dictionary<string, string>
            {
                ["valid from"] = h.ValidFrom.ToString("yyyy-MM-dd"),
            },
        }).ToList();
    }

    // The older overload stays in the interface: the same search, no user
    public Task<IReadOnlyList<MentorRagResult>> SearchAsync(
        string query, int maxResults, CancellationToken ct = default)
        => SearchAsync(
            new MentorRagRequest { Query = query, MaxResults = maxResults }, ct);
}
```

```csharp title="Program.cs"
builder.Services.AddScoped<IMentorRagSource, ManualsSource>();
builder.Services.AddMentorAgent(options =>
{
    options.UseRag = true;
    options.RagResultCount = 5;      // documents per message
    options.ShowRagSources = true;   // citation chips in the widget
    options.RagNoResultsNotice = true;
});
```

- **Declare a threshold that fits your scores.** A cosine similarity is between 0 and 1. Without `DefaultMinScore`, the default of `RagMinScore` is 2. That value suits keyword scores, but it discards every document of a vector search. A warning says so once.
- **Filter on the user.** `request.User` is the signed-in user. Return only the documents that the user may read: MentorAgent does not filter them.
- **Return an empty list when nothing matches.** A source that returns `null` fails the search.
- **Register one source.** With several registrations of `IMentorRagSource`, the last one wins.

## Citations in the widget

With [`ShowRagSources`](https://docs.mentoragent.net/reference/options#showragsources), the widget shows a chip under the reply for each document that the reply cites, with its title and its link. MentorAgent numbers the documents and asks the model, in the widget's language, to cite them as `[1]`, `[2]`. A reply that cites nothing shows no chips. The metadata of a document travels to the client with the chips: put nothing in it that the user should not see.

## When nothing is found

By default, a message that finds no document reaches the model without documents, and the model may answer from what it knows. With [`RagNoResultsNotice`](https://docs.mentoragent.net/reference/options#ragnoresultsnotice), the model is told that the search found nothing: a question that the documents would cover is answered "not found in the documents", and a greeting or an action is answered as usual. It is off by default.

## When the search fails

A source that throws, or that answers with no list, leaves the turn without documents, and the reply goes on. A warning names the source. With [`EnableObservability`](https://docs.mentoragent.net/reference/options#enableobservability), MentorAgent counts the failure on `mentoragent.rag_failures`. The count carries the source and the type of the exception, but never its message. Each search also has a `mentor.rag.search` span. See [Observability](https://docs.mentoragent.net/configure/production#observability).

## When the conversation changes

A source can keep something for a conversation, such as the documents that it already showed. MentorAgent calls `OnConversationChangedAsync` on the source when the conversation changes, with one of three reasons:

- `Reset`: a new conversation starts.
- `Restored`: a saved conversation is restored.
- `Replaced`: a saved conversation was restored, but the service no longer knew it, so a new conversation replaced it.

The default does nothing. Keep the method quick: it has the time of [`SafetyCheckTimeout`](https://docs.mentoragent.net/reference/options#safetychecktimeout), and the conversation changes anyway.

## What it costs

- **One search per message**, before the reply, on every message.
- **One embedding of the message**, shared with tool filtering, routing and memory when they use the same [`EmbeddingGenerator`](https://docs.mentoragent.net/reference/options#embeddinggenerator) instance. A source whose documents were embedded with another model passes that model's generator, and gets that model's vector.
- **The documents in the prompt**: up to [`RagResultCount`](https://docs.mentoragent.net/reference/options#ragresultcount) documents, 5 by default, on every call of the turn. A higher threshold sends fewer.

## Limits

- **Only the coordinator searches.** Specialists and team members do not see the documents. If one of them needs your documents, give it an action that searches them.
- **MentorAgent does not index.** Loading, splitting and embedding your documents is your application's job, or your vector store's.
- **On `/mentor/chat` every request is a conversation of its own**, so the last turns that a source receives are always empty there.

## Common errors

### Every document is discarded

The threshold is not on your source's scale. A vector source without `DefaultMinScore` gets the default of `RagMinScore`, 2, and keeps nothing. A warning gives the highest score that it saw. Set `DefaultMinScore` on your source, or `RagMinScore` on its scale.

### The application stops at startup with the vector store source

The distance function is missing, or it is a Euclidean, Manhattan or Hamming distance. Name it in `[VectorStoreVector(DistanceFunction = …)]` or in the options' `DistanceFunction`.

### Every search fails with MissingMethodException

The vector store connector is built on an older `Microsoft.Extensions.VectorData`. With pgvector, use `CommunityToolkit.VectorData.PgVector`.

---

- Previous: [Roles from your sign-in](https://docs.mentoragent.net/configure/roles-from-sign-in.md)
- Next: [Serve several tenants](https://docs.mentoragent.net/configure/several-tenants.md)
