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.
On this page
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
Section titled “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.
- 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.
Use a vector store
Section titled “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:
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; }
}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 = ...;
});Contentis required. It is the text that the model reads. A record without text is left out.Title,SourceUrlandMetadatagive the title and the link of the citation, and facts that the model reads under the title, such as "valid from: 2026-01-01".Filtersays 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.
AddMentorVectorStoreRagthrows when anotherIMentorRagSourceis already registered.
Scores and the threshold
Section titled “Scores and the threshold”MentorAgent keeps a document only when its score reaches the threshold, 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
Section titled “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
Section titled “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.
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);
}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 ofRagMinScoreis 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.Useris 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
nullfails the search. - Register one source. With several registrations of
IMentorRagSource, the last one wins.
Citations in the widget
Section titled “Citations in the widget”With 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
Section titled “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, 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
Section titled “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, 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.
When the conversation changes
Section titled “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, and the conversation changes anyway.
What it costs
Section titled “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
EmbeddingGeneratorinstance. 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
RagResultCountdocuments, 5 by default, on every call of the turn. A higher threshold sends fewer.
Limits
Section titled “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/chatevery request is a conversation of its own, so the last turns that a source receives are always empty there.
Common errors
Section titled “Common errors”Every document is discarded
Section titled “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
Section titled “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
Section titled “Every search fails with MissingMethodException”The vector store connector is built on an older Microsoft.Extensions.VectorData. With pgvector, use CommunityToolkit.VectorData.PgVector.
See also
Section titled “See also”- Configuration options — Every MentorOptions property with its type, default and effect, grouped by area, plus the options of the WebAssembly client and the YAML loader.
- Serve several tenants — Serve several companies from one instance: tell MentorAgent the tenant of each request, and keep memory, limits, conversations, metrics and documents apart.
- Cost and latency — What decides the tokens and the response time of each turn, the options that reduce them and what each costs in model calls, and how to measure your app.
- Production checklist — Settings to review before production: governance, safety check, rate limits, cost and routing, history, several instances, observability and outgoing data.
