MentorAgent Docs
Menu

Questa pagina non è ancora tradotta in italiano: qui la trovi in inglese.

How-to guidePackage: Novior.MentorAgent

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.

  • 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.

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:

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; }
}
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.

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 collectionScore that the source uses
CosineSimilarity, DotProductSimilarityAs it is
CosineDistance, the default of PostgreSQL and pgvector1 minus the distance
NegativeDotProductSimilarityIts 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.

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.

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.

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);
}
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.

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.

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.

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.

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.

  • 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 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 documents, 5 by default, on every call of the turn. A higher threshold sends fewer.
  • 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.

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.

  • 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.