Novior.MentorAgent.Blazor 1.3.0

Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Novior.MentorAgent.Blazor --version 1.3.0
                    
NuGet\Install-Package Novior.MentorAgent.Blazor -Version 1.3.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Novior.MentorAgent.Blazor" Version="1.3.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Novior.MentorAgent.Blazor" Version="1.3.0" />
                    
Directory.Packages.props
<PackageReference Include="Novior.MentorAgent.Blazor" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Novior.MentorAgent.Blazor --version 1.3.0
                    
#r "nuget: Novior.MentorAgent.Blazor, 1.3.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Novior.MentorAgent.Blazor@1.3.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Novior.MentorAgent.Blazor&version=1.3.0
                    
Install as a Cake Addin
#tool nuget:?package=Novior.MentorAgent.Blazor&version=1.3.0
                    
Install as a Cake Tool

Novior.MentorAgent.Blazor

New package IDs. From 1.0.0 the packages, their namespaces and their assemblies are Novior.MentorAgent.*; up to 1.0.0-rc.15 they were MentorAgent.*. See Migrating from the MentorAgent.* packages in the Novior.MentorAgent README.

Blazor WebAssembly client for MentorAgent. Install this in your Blazor WASM / Blazor Auto client project.

Connects to a Novior.MentorAgent.Server hub via SignalR and provides the same <ChatWidget /> experience as Blazor Server — same features, same API, no code changes needed when switching between render modes.

All AI processing happens server-side — configured in your server project with AddMentorAgent(). The client sends messages, registers page context and UI actions, and receives streaming events.


Table of Contents


What MentorAgent can do

All features below are available. Configure them server-side in AddMentorAgent().

Feature Description
🤖 Multi-agent orchestration Coordinator + specialized agents via Handoff Workflow
👥 Group Chat teams Multiple agents collaborate before acting
🛠️ Tool discovery C# methods become AI tools via [Description] or [MentorAction]
🎯 UI Actions AI invokes page-level actions (highlight rows, open modals, pre-fill forms) as individually named tools with typed parameters and async support
📖 Agent Skills Domain knowledge loaded on demand (load_skill) — progressive disclosure
🧠 Contextual memory Remembers user preferences across sessions
🗺️ Page navigation AI navigates to pages decorated with [MentorPage]
📚 RAG Inject relevant documents into every AI response, read through an IMentorRagSource you implement on the server
🔌 MCP Client Consume external MCP servers as additional tools
🖥️ MCP Server Expose [MentorAction] methods to Claude Desktop, VS Code, Cursor
🌐 A2A Consumer Connect to remote A2A agents in the Handoff workflow
📡 A2A Server Expose as a federatable A2A agent
🎨 Customizable widget Themes, colors, position, avatar, bot name
🌍 Multi-language 10 languages for AI responses and widget UI
🎤 Voice input/output Browser Speech Recognition + Speech Synthesis — speaks while the answer streams, stops when the user takes the floor, optional hands-free loop
🧭 Onboarding tour First-run guide generated on the server from its own pages and tools
🃏 Generative UI cards A server-side tool returns a card and the widget renders it — fields, accent, buttons
🖼️ Multimodal image input Attach images to a message — upload, clipboard paste, drag & drop or URL
🌐 Hosted tools The model provider runs web search, a code-interpreter sandbox and file search — configured server-side, results arrive in the stream
🔒 Safety check AI-based prompt injection detection
⏱️ Rate limiting Per-user message limit
✅ Confirmation dialogs Destructive actions ask for approval (HITL) — including MCP tools, in either the MentorAgent or the Agent Framework native flow
🔐 Role-based actions Actions restricted by ASP.NET Core identity roles
💸 Token & cost optimization Slim cache-friendly prompt, semantic tool filtering, history compaction, RAG/memory gating

Package Family

Package Install when
Novior.MentorAgent Blazor Server app
Novior.MentorAgent.Server Server project (Web API / Blazor Auto server)
Novior.MentorAgent.Blazor ← you are here Blazor WASM / Blazor Auto client project
Novior.MentorAgent.Abstractions Never directly — it arrives with any of the above
Novior.MentorAgent.Declarative Optional — Level-2 specialists in YAML, added on the server project

Getting started

Installation

# Client project
dotnet add package Novior.MentorAgent.Blazor

# Server project — MentorAgent is included automatically as a transitive dependency
dotnet add package Novior.MentorAgent.Server

Server project setup

All AI behaviour is configured on the server (the transitive Novior.MentorAgent core): agents, RAG, memory, skills, MCP/A2A and the token/cost optimizations below. The client only renders the widget.

// Server/Program.cs
builder.Services.AddMentorAgent(options =>
{
    options.AppName        = "My App";
    options.AppDescription = "An order management application";
    options.ChatClient     = chatClient;
    options.ScanAssemblies = [typeof(Program).Assembly];

    // All features configured here: agents, RAG, MCP, A2A, memory, skills...
    options.UseMemoryContext = true;
    options.UseRag           = true;
    options.McpServerEnabled = true;
    options.A2AServerEnabled = true;
    options.EnableSkills     = true;
    options.RateLimitPerUser = 20;
});
builder.Services.AddMentorAgentServer();

app.MapMentorAgentServer();   // /mentor-hub, /mentor/chat + /mentor/approve, /mentor/cancel, /mentor/session, /mentor/tour, /mentor/admin/metrics
app.MapMentorAgentMcp();      // optional
app.MapMentorAgentA2A();      // optional

AddRazorComponents() and AddMentorAgentServer() can come in either order: Blazor's circuits keep their user, and the hub, /mentor/chat and A2A get theirs from the request.

Token & cost optimization + reliable memory (server project)

These options cut the tokens sent per request and make memory reliable — all on the server. Full details: MentorAgent core README → Token & cost optimization.

builder.Services.AddMentorAgent(options =>
{
    // ...ChatClient, ScanAssemblies as above...

    // Embedding model — powers semantic tool filtering AND semantic memory relevance.
    options.EmbeddingGenerator = new AzureOpenAIClient(endpoint, credential)
        .GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator();

    // Send only the tools semantically relevant to the message (requires EmbeddingGenerator).
    options.EnableToolFiltering = true;
    options.ToolFilterMinScore  = 0.35f;

    // Compact long conversation history before each call.
    options.EnableCompaction         = true;
    options.CompactionTokenThreshold = 4000;

    // Memory: reliable post-turn fact capture (default true) + inject only relevant memories.
    options.UseMemoryContext         = true;
    options.MemoryAutoCapture        = true;   // default — reliable writer on Path A
    options.MemoryRelevanceFiltering = true;   // requires EmbeddingGenerator
});
Robustness, observability & cost dashboard (server project)

Also configured on the server — see the MentorAgent core README for full details.

builder.Services.AddMentorAgent(options =>
{
    // Middleware hooks
    options.OnException = ex => ex.Message.Contains("rate", StringComparison.OrdinalIgnoreCase)
        ? "The service is busy, please retry shortly." : null;
    options.ConfigureChatClientPipeline = b => b.UseLogging();

    // Observability (add an OpenTelemetry exporter to the app as usual)
    options.EnableObservability = true;

    // Dashboard cost pricing (supply your own; none built in)
    options.ModelPricing = new Dictionary<string, ModelPrice>(StringComparer.OrdinalIgnoreCase)
    {
        ["gpt-4o"] = new ModelPrice(2.50m, 10.00m), ["gpt-4o-mini"] = new ModelPrice(0.15m, 0.60m),
    };
});

The admin dashboard ships as a Blazor component. Drop it on a protected page (you own the authorization). On Blazor Server / Auto it reads IMentorMetrics in-process; on standalone WASM, fetch GET /mentor/admin/metrics from the server and pass the snapshot:

@* Blazor Server / Auto — in-process (the component reads IMentorMetrics itself) *@
@attribute [Authorize(Roles = "Admin")]
@using Novior.MentorAgent.Abstractions.Components
<MentorDashboard Currency="$" />
@* Standalone WASM — fetch the snapshot from the server and pass it in *@
@attribute [Authorize(Roles = "Admin")]
@using System.Net.Http.Json
@using Novior.MentorAgent.Abstractions.Components
@using Novior.MentorAgent.Abstractions.Models
@inject HttpClient Http

<MentorDashboard Snapshot="_snapshot" OnRefresh="LoadAsync" Currency="$" />

@code {
    private MentorMetricsSnapshot? _snapshot;
    protected override Task OnInitializedAsync() => LoadAsync();

    // HttpClient must target the server; the endpoint is gated by options.DashboardRole.
    private async Task LoadAsync() =>
        _snapshot = await Http.GetFromJsonAsync<MentorMetricsSnapshot>("mentor/admin/metrics");
}

Also configured/available on the server (see the core README for full examples):

  • Rich responses — with options.EnableRichResponses (server, default on) the assistant formats structured data as Markdown; this widget renders the tables, lists and links automatically — no client wiring, XSS-safe, tables scroll horizontally on narrow screens.
  • Model routing (options.StrongChatClient + options.RoutingStrategy: Semantic/Classifier/Cascade/Custom) — cheap↔strong per turn.
  • Structured outputs — inject IMentorStructured (GenerateAsync<T>) for typed results / auto-filled forms.
  • Evaluation — inject MentorEvaluator (wraps the Agent Framework's native agent.EvaluateAsync) in tests to gate CI on token/quality regressions; plug FoundryEvals/MEAI evaluators for quality & safety.

Client project setup

// Client/Program.cs
using Novior.MentorAgent.Abstractions.Models;   // MentorLanguage, MentorTheme, ChatPosition
using Novior.MentorAgent.Blazor.Extensions;

// Stop and confirmations go through an HttpClient. The standalone WebAssembly template registers one;
// the client project of a Blazor Web App does not.
builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services.AddMentorAgentBlazor(options =>
{
    options.HubUrl       = "/mentor-hub";    // URL of Novior.MentorAgent.Server hub
    options.BotName      = "My Assistant";
    options.Language     = MentorLanguage.English;
    options.Theme        = MentorTheme.Default;
    options.PrimaryColor = "#2563eb";
});

⚠️ HubUrl — relative vs absolute.

  • Same origin (Blazor Auto hosted, or WASM served by the same ASP.NET Core host): use a relative path — options.HubUrl = "/mentor-hub". It is resolved against the page's base address, as the browser resolves it: /mentor-hub at the origin's root, mentor-hub under the app's base path.
  • Different origin (standalone WASM on :5001 connecting to a server on :5169): use the server's absolute URL — options.HubUrl = "http://localhost:5169/mentor-hub" — and configure CORS on the server (see the Novior.MentorAgent.Server README → CORS). Without server-side CORS the SignalR handshake is silently blocked by the browser.
// Standalone WASM example — different origin
builder.Services.AddMentorAgentBlazor(options =>
{
    options.HubUrl = "http://localhost:5169/mentor-hub";   // absolute — server on a different port
    options.BotName = "My Assistant";
});

Authenticating the connection — AccessTokenProvider

If your users sign in, set this. The server resolves the caller from the SignalR HubCallerContext.User, and a browser cannot send an Authorization header on a WebSocket or Server-Sent Events connection — so the token travels the way SignalR expects, and AccessTokenProvider is where you supply it. It is the WASM equivalent of the JavaScript client's accessTokenFactory.

var tokenStore = new TokenStore();                    // your own: holds the signed-in user's token
builder.Services.AddSingleton(tokenStore);           // same instance for your login page

builder.Services.AddMentorAgentBlazor(options =>
{
    options.HubUrl = "https://api.example.com/mentor-hub";
    options.AccessTokenProvider = () => Task.FromResult(tokenStore.Token);   // null while signed out
});

⚠️ Without it every user is anonymous to the server, and every RequiredRoles action is blocked. What else follows depends on the server's AnonymousIdentity. With the default PerSession, each hub connection is its own anonymous user: nothing is shared between people, but memory and the RateLimitPerUser allowance start over on every reconnect. With Shared, every user is the single key "anonymous": one rate limit for everybody and one memory bucket. With MemoryAutoCapture on (the default), one person's name and preferences then reach another person's prompt.

The server must accept the token from the query string. A browser cannot send an Authorization header on a WebSocket or Server-Sent Events connection, so SignalR sends the token as ?access_token=…. With JWT bearer on the server, forward it in OnMessageReceived, or the hub still sees an anonymous caller:

// Server Program.cs
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options => options.Events = new JwtBearerEvents
    {
        OnMessageReceived = ctx =>
        {
            var token = ctx.Request.Query["access_token"];
            if (!string.IsNullOrEmpty(token) && ctx.HttpContext.Request.Path.StartsWithSegments("/mentor-hub"))
                ctx.Token = token;
            return Task.CompletedTask;
        }
    });

For the hub, the provider is read on connect and on every reconnect, not per message. (The Stop and confirmation requests read it again each time they are sent.) The widget opens the hub connection lazily, when the user sends the first message, and keeps it for the life of the page. A sign-in before that first message is picked up automatically. A user who signs in after it stays on the old, anonymous connection: MentorHubClient has no way to restart it, so reload the page after sign-in (Navigation.NavigateTo(Navigation.Uri, forceLoad: true)) and restore the persisted token during startup. A reconnect is a new connection on the server, so it also starts a new conversation.

For anything else the connection needs — a custom header, a transport restriction, cookies — ConfigureConnection runs on the same HttpConnectionOptions immediately afterwards:

options.ConfigureConnection = o => o.Headers["X-Tenant"] = tenantId;

Stop and confirmations — plain HTTP to the hub's server

■ Stop (POST /mentor/cancel) and the answer to a confirmation (POST /mentor/approve) cannot go through the hub (see How it works), so the widget sends them as HTTP requests. They follow the hub settings above:

  • Where they go. When HubUrl is an absolute http(s) URL, both are posted to the hub's origin (https://api.example.com/mentor/approve for HubUrl = "https://api.example.com/mentor-hub"). With a relative HubUrl (same-origin hosting) they stay relative and resolve against the host's HttpClient.BaseAddress.
  • What they carry. When AccessTokenProvider is set, each request sends Authorization: Bearer <token> with the token it returns — the same credential the hub uses. Both endpoints accept a Stop or an answer only from the user who opened the hub connection (401 for an anonymous caller, 403 for another user), so this is what lets a signed-in user's Stop and confirmations through.

Two things are still yours:

  • Register an HttpClient. The widget sends these requests through the HttpClient in your client's DI container, and AddMentorAgentBlazor() does not register one. The standalone WebAssembly template registers one. The client project of a Blazor Web App does not, and without it the WebAssembly runtime does not start (CannotResolveService … HttpClient): add the line of the setup snippet above to its Program.cs. With an absolute HubUrl the BaseAddress does not matter for these two calls.
  • CORS, cross-origin. The server's CORS policy must allow the client's origin for these POSTs as well as for the hub, including the Authorization header when you send a token. On the server, UseCors comes before UseAuthentication and UseAuthorization, and those before Map…: with a protected hub, any other order blocks the client on another origin (see the Novior.MentorAgent.Server README → CORS).

A failure is only logged (the widget has already closed the prompt), so check the browser console if Stop or a confirmation seems to be ignored.

Add the widget

In MainLayout.razor or any page:

@using Novior.MentorAgent.Abstractions.Components

<ChatWidget />

Important — a standalone Blazor WASM app requires manual CSS/JS links in index.html.

Unlike Blazor Server (where the widget injects CSS automatically via <HeadContent>), a standalone Blazor WASM app uses a static index.html that is served before the .NET runtime starts. Add these two lines to your wwwroot/index.html:

<head>
    ...
    <link href="_content/Novior.MentorAgent.Abstractions/css/MentorAgent.css?v=1.3.0" rel="stylesheet" />
</head>
<body>
    ...
    <script src="_content/Novior.MentorAgent.Abstractions/js/MentorAgent.js?v=1.3.0"></script>
</body>

Without this, the widget will render unstyled until after WASM initializes (flash of unstyled content).

⚠️ Set the ?v= to the package version and change it on every upgrade. On Blazor Server the widget writes these tags itself and versions them for you, with the package version and its commit; here they are yours, nothing fingerprints them, and a returning visitor's browser will reuse the copy it already has. A stale MentorAgent.js fails silently and selectively — the widget still works, but the calls that did not exist in the older file are swallowed by their try/catch, so the onboarding tour never appears and voice falls back to reading the whole answer at the end. If a feature seems missing after an upgrade, check the served file before anything else: it should contain flagGet and beginSpeech.

On Blazor Server, <ChatWidget /> injects its own CSS and JS automatically — no changes to _Host.cshtml or App.razor needed. A Blazor Web App (Auto or WebAssembly) has no index.html: prerendered — the default — the widget writes the two tags itself, as on Blazor Server; with prerender: false add them to the <head> of App.razor.


Widget customization

Theme and appearance

options.Theme        = MentorTheme.Minimal;   // Default | Dark | Minimal | Custom | Auto
options.PrimaryColor = "#7c3aed";             // any hex color
options.Position     = ChatPosition.BottomRight; // BottomRight | BottomLeft | TopRight | TopLeft | SideRight | SideLeft
options.AvatarUrl    = "/my-avatar.png";
options.BotName      = "ShopFlow Assistant";

Welcome message and input

options.WelcomeMessage    = "Hello! How can I help you today?";
options.InputPlaceholder  = "Ask anything...";
options.EnableSuggestions = true;   // show suggestion chips in the welcome panel

Language (10 supported)

options.Language = MentorLanguage.Italian;
// English | Italian | French | German | Spanish | Portuguese | Dutch | Polish | Japanese | Chinese

This sets the widget's UI strings, read again on every use. The language the assistant answers in is the server's options.Language in AddMentorAgent(), and the prompt enforces it whatever language the user writes in. A widget given its own language, <ChatWidget Language="MentorLanguage.Italian" />, sends it with every turn, and the server answers in it (see A language per page in the MentorAgent README). Otherwise set both:

using Novior.MentorAgent.Abstractions.Models;   // MentorLanguage, in both Program.cs files

// Server Program.cs
builder.Services.AddMentorAgent(options => { /* ... */ options.Language = MentorLanguage.Italian; });

// Client Program.cs
builder.Services.AddMentorAgentBlazor(options => { options.Language = MentorLanguage.Italian; });

Voice

options.EnableVoiceInput  = true;   // microphone button (browser Speech Recognition)
options.EnableVoiceOutput = true;   // text-to-speech for AI responses

options.VoiceStreaming    = true;   // default — speak sentence by sentence while the answer streams
options.VoiceBargeIn      = true;   // default — taking the floor stops playback
options.VoiceHandsFree    = false;  // opt-in — keep the conversation going by voice alone
options.VoiceRate         = 1.0;    // 0.5–2.0

Unlike image input and the hosted-tools badge below, these are not a mirror of server settings. Voice is entirely browser behaviour: your server sees only the transcript, as an ordinary message, and these options are the real thing rather than a copy of something the server enforces. The audio is the browser's business: some browsers, Chrome among them, send it to their maker's speech service for recognition (MDN, Using the Web Speech API).

VoiceStreaming is what makes voice output usable on anything longer than a sentence. Without it the assistant stays silent for the whole response and then recites it. Text is buffered to a sentence boundary and queued as its own utterance, so speech keeps pace with the stream — and the boundary detection knows that 8.459 is one number and that a fenced code block must be dropped whole rather than read out.

VoiceBargeIn stops playback when the user presses the microphone, sends a message, presses ■ Stop or starts a new conversation. It is press-to-interrupt, not acoustic: a browser cannot listen through its own playback without echo cancellation.

VoiceHandsFree sends on silence and reopens the microphone after the spoken answer ends. It needs both voice options on — with nothing to listen to there is nothing to wait for, and the loop would transcribe the assistant. If you set only one, it is ignored.

Onboarding tour

options.EnableOnboardingTour = true;   // shown once, on this user's first open of the widget
options.TourUrl = "/mentor/tour";      // default — only change it if you remapped the server endpoints

The steps are generated on the server — only it knows the registered [MentorPage] pages and the assistant's tools — and fetched from GET /mentor/tour, which MapMentorAgentServer() maps whatever the server's own EnableOnboardingTour says. The flag on this client alone decides whether to show the tour; the server needs only the [MentorPage] pages, and with none it answers [].

That split follows the same rule as the hosted-tools badge: the server is the single source of truth, and a client that reproduces server state locally eventually displays something the server no longer agrees with.

Each step can carry a ready-made question the user sends with one tap — which is the point, since the usual failure of an in-app assistant is not that people cannot find it but that they do not know what to ask. A ? button in the header replays the tour later.

If the fetch fails the widget opens normally and logs a warning: a missing tour is a missing nicety, not a broken chat.

Generative UI cards

Nothing to configure on the client. When a server-side tool returns a MentorCard, the server pushes it on the Cards hub event and the widget renders it under the reply — fields, accent colour and buttons.

Buttons work the same as in Blazor Server: SendMessage sends the text as a user turn, Navigate routes to the URL, UIAction runs an action the current page registered (resolved at click time, so a stale handler from a page you have navigated away from is skipped rather than invoked).

To render a card kind yourself, supply a template and fall back to the built-in renderer for the rest:

<ChatWidget>
    <CardTemplate Context="card">
        @if (card.Kind == "order") { <OrderCard Card="card" /> }
        else                       { <MentorCardView Card="card" /> }
    </CardTemplate>
</ChatWidget>

The fallback's buttons work without any wiring: ChatWidget cascades its own card-action dispatcher around the cards, and a <MentorCardView> inside the template that sets no OnAction uses it, with the same SendMessage / Navigate / UIAction behaviour as above. An explicit OnAction on the MentorCardView still wins. The dispatcher reaches only MentorCardView: buttons you draw yourself in a template (as OrderCard might) get nothing from it, so render a MentorCardView for any card whose buttons should behave like the built-in ones.

Cards are built by server-side application code, not by the model, which is why they can safely carry buttons: nothing said in the conversation can add one or change where it points.

Image input (multimodal)

Lets the user attach images to a message. The widget accepts them four ways — 📎 file picker, Ctrl+V clipboard paste, drag & drop onto the composer, and 🔗 remote URL — and shows removable thumbnails before sending and inside the message bubble afterwards.

// Client Program.cs — mirrors the server settings (the server is what actually enforces them)
builder.Services.AddMentorAgentBlazor(options =>
{
    options.EnableImageInput    = true;
    options.MaxImageBytes       = 4 * 1024 * 1024;                            // per image (default 4 MB)
    options.MaxImagesPerMessage = 4;                                          // per turn  (default 4)
    options.AllowedImageTypes   = ["image/png", "image/jpeg", "image/webp"];  // MIME allow-list
});

The server must also enable it, with a vision-capable model:

// Server Program.cs
builder.Services.AddMentorAgent(options =>
{
    // ...AppName, ScanAssemblies as above...
    options.ChatClient       = azure.GetChatClient("gpt-4.1").AsIChatClient();   // vision-capable
    options.EnableImageInput = true;
});

The client values only drive the UI and give the user instant feedback; every attachment is re-validated server-side (allow-list, size, count) before it reaches the model. Images travel over the hub as the second argument of SendMessage(text, attachments). The client always sends both arguments, with null for a text-only turn, because SignalR binds hub arguments by count. The images ride inside that one hub message as base64, so AddMentorAgentServer() raises MentorHub's MaximumReceiveMessageSize from the server's MaxImageBytes × MaxImagesPerMessage (+512 KB). Keep the client values at or below the server's: a message larger than the hub limit makes SignalR abort the connection before the server can validate it, and the user sees their own bubble and no reply.

Sending images from your own code:

@inject IMentorOrchestrator Orchestrator

await Orchestrator.SendMessageAsync("Cosa non va in questo screenshot?", [
    new MentorAttachment { MimeType = "image/png",  DataBase64 = base64, FileName = "error.png" },
    new MentorAttachment { MimeType = "image/jpeg", Url = "https://cdn.example.com/product.jpg" },
]);

Image bytes are streamed to .NET through IJSStreamReference, never marshalled as one big interop payload — so this works unchanged on Blazor Server too, without touching HubOptions.MaximumReceiveMessageSize.

RAG citations

options.ShowRagSources = true;   // show citation chips below AI responses

MCP and A2A status badges

When the server has MCP client servers or remote A2A agents configured, the widget can display live status badges in the header. Because the WASM client doesn't read the server configuration directly, you must mirror the relevant settings:

// Client Program.cs
builder.Services.AddMentorAgentBlazor(options =>
{
    // MCP badge — mirror McpServers names from the server
    options.ShowMcpStatus  = true;
    options.HasMcpServers  = true;
    options.McpServerNames = ["time", "filesystem"];  // must match server McpServers[].Name

    // A2A badge — mirror RemoteAgents from the server
    options.ShowA2AStatus       = true;
    options.HasRemoteAgents     = true;
    options.RemoteAgentDisplays = [
        new AgentDisplayInfo { Name = "ShopFlow-B", AgentCardUrl = "http://localhost:5001" }
    ];
});

The MCP badge updates dynamically — when a server connects or disconnects the hub fires McpServerStatusChanged and the badge turns green/red. The A2A badge is static (shows configured agents, no live status).

Note: McpServerNames must match the Name fields in MentorMcpServer[] configured on the server. A mismatch shows a stale "connecting" badge.

Hosted tools badge

If the server enables hosted tools (provider-side web search, code interpreter, file search, image generation, remote MCP), an amber pill lists them in the header. Do not list them here — turn the badge on and let the server say what it enabled:

options.ShowHostedToolsStatus = true;   // that's all

The server sends its active set on the HostedToolsDeclared hub event the moment the client connects, and the widget prefers it over any local value. On WebAssembly the connection opens when the user sends the first message, so until then the badge shows options.HostedTools (nothing, by default). Setting options.HostedTools by hand still works as a pre-connection placeholder, but it is a copy that goes stale: change the server's configuration and the badge starts claiming tools that are not there — which is worse than no badge, because it is believed.

Unlike MCP the badge has no live status afterwards: hosted tools are configuration, not a connection.

Live activity needs no configuration here. When the server has ShowHostedToolActivity on, the widget already shows what the provider is doing, over the hub events it consumes anyway:

  • "Ricerca sul web… · .NET 10" in the feedback line, via ActionExecuting / ActionCompleted
  • pages cited by web search as citation chips, via RagSourcesReady — the same panel as RAG, so it also needs ShowRagSources
  • generated images attached to the finished message, via the GeneratedImages event

The WASM client handles all three out of the box.


Page context and UI actions

IMentorPageContext works identically to Blazor Server. Register context data and UI actions in any page — they are sent to the server as a snapshot before each AI message.

Inject page context

@inject IMentorPageContext PageContext
@implements IDisposable

@code {
    protected override void OnInitialized()
    {
        PageContext
            .SetPageName("Orders")
            .Set("ActiveFilter", "Pending")
            .Set("VisibleRows", _orders.Count);
    }

    public void Dispose() => PageContext.Clear("Orders");   // this page's entries only, by its name
}

Register UI actions (no parameter)

PageContext.RegisterUIAction(
    "open_create_modal",
    "Opens the modal to create a new order",
    _ => OpenCreateModal());

Register UI actions with typed parameter

// The AI calls highlight_row(42) — parameter deserialized automatically
PageContext.RegisterUIAction<int>(
    "highlight_row",
    "Highlights the specified order row",
    id => HighlightRow(id),
    parameterHint: "integer: order ID");

Async UI actions

PageContext.RegisterUIActionAsync<OrderModel>(
    "prefill_form",
    "Pre-fills the edit form with order data",
    async model => {
        _formModel = model;
        await InvokeAsync(StateHasChanged);
    },
    parameterHint: "JSON: { orderId, amount, status }");

Remove an action

PageContext.UnregisterUIAction("highlight_row");

Signal page ready (Blazor Server and MAUI Blazor Hybrid only)

On WebAssembly SignalReady() is a no-op and costs nothing, so you can keep the call in pages shared with a Blazor Server host:

protected override async Task OnInitializedAsync()
{
    await LoadDataAsync();
    PageContext.SignalReady();   // Blazor Server, MAUI Blazor Hybrid: tells navigate_to the UI actions are ready. WASM: no-op
}

What matters on WebAssembly is when the server learns about the page. Its name, data and UI actions reach the server only with the page-context snapshot sent before the user's next message (UpdatePageContext). So when the assistant moves the user with navigate_to, the server does not wait for the new page — even on a [MentorPage] with HasUIActions = true, because on a hub connection nothing could ever signal it. The new page's UI actions become callable from the user's next message, not later in the same answer.

(On Blazor Server and in MAUI Blazor Hybrid, where navigate_to does wait on HasUIActions pages, call SignalReady() as the last line of OnInitialized / OnInitializedAsync, not from OnAfterRenderAsync, or the wait may already have timed out.)


⚠️ [MentorPage] attributes are defined in the server project (scanned by ScanAssemblies), not in the client project.

// Server project — scanned via options.ScanAssemblies
[MentorPage(Url = "/orders", Name = "Orders", Description = "Order management")]
public class OrdersPage { }

[MentorPage(Url = "/products", Name = "Products", HasUIActions = true, ReadyTimeout = 3000)]
public class ProductsPage { }

The AI calls navigate_to("/orders") — the WASM widget handles navigation automatically via Blazor's NavigationManager.

HasUIActions and ReadyTimeout only affect hosts where the page runs in the same process as the turn: Blazor Server, or a MAUI Blazor Hybrid app. For a turn that arrives over the hub, navigate_to returns without waiting for SignalReady (it logs this at Debug level), and the new page's UI actions reach the model with the next page-context snapshot, on the user's next message — see Signal page ready.


UI Action overloads reference

Four overloads are available, from simple to fully typed and async:

Overload Parameter Execution Use when
RegisterUIAction(name, desc, Action<object?>) Raw object? Synchronous Simple no-param or legacy code
RegisterUIAction<TParam>(name, desc, Action<TParam>) Auto-deserialized from JSON Synchronous Typed param, sync handler
RegisterUIActionAsync(name, desc, Func<object?, Task>) Raw object? Async No-param async actions (e.g. async _ => { await LoadAsync(); })
RegisterUIActionAsync<TParam>(name, desc, Func<TParam, Task>) Auto-deserialized from JSON Async Typed param, async handler (recommended)
UnregisterUIAction(name) — — Remove a specific action dynamically

Automatic parameterHint generation

For typed overloads, parameterHint is auto-generated from the type when omitted:

TParam Auto-generated hint
int, long "integer"
float, double, decimal "number"
bool "boolean"
string "string"
Guid "string (GUID)"
DateTime "string (ISO 8601 date)"
Status (enum) "string (Active\|Inactive\|Pending)"
List<int> "array<integer>"
OrderFormModel (class) "{ customerId: integer, productName: string, ... }"

Override only when extra clarity is needed:

.RegisterUIAction<int>(
    "highlight_row", "Highlights an order row",
    id => HighlightRow(id),
    parameterHint: "integer: order ID")  // ← manual override

On WebAssembly the AI does not wait for your handler. The server forwards the call as UIActionRequested and reports the action complete as soon as it is sent. The browser then runs the handler and reports nothing back. As a result, an exception in the handler never reaches the model, and OnUIActionCompleted can fire before an async handler has finished. Make each action self-contained (load what it needs inside the handler) rather than relying on the model to chain actions that depend on the previous one having finished. (On Blazor Server, where the handler runs in-process, async handlers are awaited.)


[MentorPage] parameters (server project)

Parameter Required Description
Url ✅ Page URL (e.g. "/orders")
Name ✅ Human-readable page name injected into the system prompt
Description — Optional feature description
HasUIActions — If true, navigate_to waits for PageContext.SignalReady() before UI actions — only where the page runs in the turn's process: Blazor Server or MAUI Blazor Hybrid. On a hub turn from this WASM client it does not wait: the page's actions arrive with the user's next message. Default: false
ReadyTimeout — Timeout in ms for SignalReady() (Blazor Server and MAUI Blazor Hybrid only). Default: 2000

All AddMentorAgentBlazor() options

Option Type Default Description
HubUrl string "/mentor-hub" URL of the Novior.MentorAgent.Server SignalR hub. A relative value is resolved against the page's base address. When absolute (http(s)), its origin is also where Stop (/mentor/cancel) and confirmation answers (/mentor/approve) are posted
AccessTokenProvider Func<Task<string?>>? null Bearer token for the hub, read on connect and on every reconnect, and sent as Authorization: Bearer on every Stop and confirmation request. Without it every user is anonymous: RequiredRoles blocked; memory and rate limit are per connection (server default AnonymousIdentity = PerSession) or one shared bucket (Shared)
ConfigureConnection Action<HttpConnectionOptions>? null Escape hatch on the hub's connection options — headers, transports, cookies. Runs after AccessTokenProvider
BotName string "Mentor AI" Bot name in the widget header
WelcomeMessage string? null Welcome message (HTML supported)
ShowAiDisclosure bool true Shows the notice that tells people they are talking to an AI, under the widget's header for the whole conversation. false hides it; the replies' marker stays
AiDisclosureMessage string? null The notice's text, shown as written (as text, never as markup). null or white space: the default, translated into the configured language
AvatarUrl string? null Custom avatar URL
InputPlaceholder string? null Input box placeholder. null uses the localized text in Language ("Write a message..." in English)
Theme MentorTheme Default Widget visual theme
Position ChatPosition BottomRight Widget position on screen
PrimaryColor string? null Custom hex accent color
Language MentorLanguage English Language for widget UI strings (10 languages supported)
EnableVoiceInput bool false Show microphone button (browser Speech Recognition)
EnableVoiceOutput bool false Text-to-speech for AI responses (browser Speech Synthesis)
VoiceStreaming bool true Speak each sentence as it streams instead of reading the finished answer back
VoiceBargeIn bool true Stop playback when the user takes the floor
VoiceHandsFree bool false Voice-only conversation loop. Ignored unless both voice options are on
VoiceRate double 1.0 SpeechSynthesisUtterance.rate — useful range 0.5–2.0
EnableOnboardingTour bool false Show the guided tour on first open. This flag alone decides: the server answers GET /mentor/tour whatever its own EnableOnboardingTour says
TourUrl string "/mentor/tour" Where to fetch the tour steps from. A relative value is resolved against HubUrl's origin when HubUrl is absolute (the tour is served by the same server as the hub), otherwise against the app base address. An absolute URL is used as-is
EnableSuggestions bool false Suggestion chips in the welcome panel
EnableImageInput bool false Image attachments — 📎 upload, paste, drag & drop and 🔗 URL. Must also be enabled server-side
MaxImageBytes int 4194304 Client-side size cap per image (4 MB). Mirrors the server option
MaxImagesPerMessage int 4 Client-side cap on images per message. Mirrors the server option
AllowedImageTypes List<string> png, jpeg, gif, webp Client-side MIME allow-list. Mirrors the server option
ShowRagSources bool false Citation chips below AI responses
ShowHostedToolsStatus bool false Show the hosted-tools badge (provider-side web search / code interpreter / file search / image generation / remote MCP)
HostedTools MentorHostedTools None Pre-connection placeholder only. The server publishes its actual set on HostedToolsDeclared at connect and the widget prefers that — leave this unset rather than keeping a copy that goes stale
ShowMcpStatus bool false Show MCP server connection status badge in the widget header
HasMcpServers bool false Whether the server has MCP client servers configured (enables the MCP badge)
McpServerNames List<string> [] Names of MCP servers configured on the server — pre-populates the badge in "connecting" state at startup
ShowA2AStatus bool false Show A2A remote agent status badge in the widget header
HasRemoteAgents bool false Whether the server has remote A2A agents configured (enables the A2A badge)
RemoteAgentDisplays List<AgentDisplayInfo> [] Remote A2A agents to display in the A2A badge and detail bar

How it works

[Blazor WASM Browser]
  ChatWidget
    ↓ IMentorOrchestrator (WasmMentorOrchestrator)
    ↓ SignalR
[ASP.NET Core Server — Novior.MentorAgent.Server]
  MentorHub
    ↓ MentorOrchestrator (full AI pipeline)
    ↓ AI Provider (Azure OpenAI, OpenAI, Ollama...)
    ↑ Streaming events (chunks, confirmations, navigation, UI actions...)
    ↑ SignalR
  ChatWidget renders response
  • Page context (page name, data, UI action descriptions) is sent to the server before every message via UpdatePageContext.
  • UI action invocations arrive from the server as UIActionRequested and are executed locally in the browser by WasmMentorStateService.
  • Confirmation dialogs (HITL) are shown inline by ChatWidget. The response is sent via POST /mentor/approve?actionId=...&approved=true|false (HTTP) — not via a hub method. SignalR processes hub messages sequentially per connection, so calling RespondToApproval via hub while SendMessage is awaiting would deadlock. WasmMentorStateService sends it to the hub's origin with the hub's bearer token — see Stop and confirmations.
  • Stop (cancelling an in-flight turn) is sent via POST /mentor/cancel?connectionId=... (HTTP) — not via the CancelRequest hub method, for the same sequential-dispatch reason: while SendMessage is streaming, SignalR cannot dispatch another hub invocation on that connection, so the hub call would only run after the turn it was meant to abort. WasmMentorOrchestrator sends it the same way as the approval: to the hub's origin, with the hub's bearer token.
  • UI actions after navigate_to: the server does not wait for the new page (nothing on a hub connection can call SignalReady); the page's actions reach the model with the next UpdatePageContext, on the user's next message.
  • Navigation triggered by the AI arrives as NavigationRequested and is handled by Blazor's NavigationManager.

Conversation lifetime and session snapshots

The conversation lives on the server, in a DI scope that belongs to one SignalR connection. A reconnect (network drop, server restart, a laptop waking up) gets a new connection id and therefore a new, empty conversation on the server, even though the widget still shows the old messages.

IMentorOrchestrator.SerializeSessionAsync / RestoreSessionAsync throw NotSupportedException on WebAssembly, because the AgentSession is not in the browser. Save and restore it over HTTP instead, with the live connection id. That id is null until the first message opens the connection.

@inject Novior.MentorAgent.Blazor.Hub.MentorHubClient Hub
// BaseAddress = the server, carrying the user's token
@inject HttpClient Http

// Save — 204 means there is no conversation yet: keep what you already have
var save = await Http.GetAsync($"mentor/session?connectionId={Uri.EscapeDataString(Hub.ConnectionId!)}");
if (save.StatusCode == HttpStatusCode.OK)
    _saved = await save.Content.ReadAsStringAsync();

// Restore on the new connection (after its first message; an earlier request can get 404)
await Http.PostAsync($"mentor/session?connectionId={Uri.EscapeDataString(Hub.ConnectionId!)}",
    new StringContent(_saved, Encoding.UTF8, "application/json"));

Both endpoints check that the caller is the user who opened the connection (401/403 otherwise), before the body is read. The snapshot is opaque — protected with ASP.NET Core Data Protection and bound to that user (on a host without sign-in every visitor is the same anonymous user, so there it is bound to the application only) — so store it as the text GET returned. A body that is not a snapshot this server issued for this user, or was edited, or was saved before 1.0.0-rc.14, is refused with 400 and leaves the live conversation untouched. Restoring after a server restart needs the server's Data Protection key ring persisted (see the Novior.MentorAgent.Server README).


Events — IMentorStateService

ChatWidget handles all events automatically. If you need to subscribe to events directly in your own components, inject IMentorStateService:

@inject IMentorStateService State
@implements IDisposable

protected override void OnInitialized()
{
    State.OnStreamingChunk        += OnChunk;
    State.OnStreamingCompleted    += OnCompleted;
    State.OnBusyChanged           += OnBusy;
    State.OnError                 += OnError;
    State.OnActionExecuting       += OnActionExecuting;
    State.OnActionCompleted       += OnActionCompleted;
    State.OnActionFailed          += OnActionFailed;
    State.OnConfirmationRequired  += OnConfirmationRequired;
    State.OnNavigationRequested   += OnNavigation;
    State.OnRagSourcesReady       += OnRagSources;
    State.OnTeamMemberSpeaking    += OnTeamSpeaking;
    State.OnUIActionExecuting     += OnUIActionStart;
    State.OnUIActionCompleted     += OnUIActionEnd;
}

public void Dispose()
{
    State.OnStreamingChunk        -= OnChunk;
    // ... unsubscribe all
}

Complete event reference

Event Signature Fired when Typical use
OnStreamingChunk Action<string> Each streaming token Append text to a custom chat bubble
OnStreamingCompleted Action Full response received Finalize message, re-enable input
OnBusyChanged Action<bool> AI starts/stops processing Show/hide spinner
OnError Action<string> Critical error (rate limit, safety block) Show error banner
OnActionExecuting Action<string> Tool/agent is executing. Carries the text to show (the action's Description, or the routing, team or hosted-tool label), not the tool name Show action feedback bar. To log which tool ran, use OnActionCompleted, which carries the tool name
OnActionStarted Action<MentorActionStarted> Never raised by this client: the hub sends it only the text shown, not the tool name Record actions on the server, where it is raised with ToolName and DisplayName
OnActionCompleted Action<string> Tool execution succeeded Hide feedback bar
OnActionFailed Action<string> Tool execution failed — tool: message; with the server's OnException set, never the exception's own text Show error in feedback
OnConfirmationRequired Action<ConfirmationRequest> Destructive action needs user approval Show custom confirmation dialog
OnApprovalResponse Action<ConfirmationRequest, bool> The answer reached the waiting turn: raised once the server accepted it, never after Stop or for a second answer An audit trail of decisions
OnNavigationRequested Action<string> AI triggered navigation Custom routing logic
OnRagSourcesReady Action<IReadOnlyList<MentorRagResult>> RAG documents the finished answer cited (plus hosted web/file-search citations); not raised when nothing was cited Show custom citation UI
OnTeamMemberSpeaking Action<string, string> GroupChat member speaking Show "Team · Role" feedback
OnUIActionExecuting Action<string> UI action started Custom feedback
OnUIActionCompleted Action<string> UI action completed Custom feedback
OnMcpServerStatusChanged Action<string, bool> MCP server connects (true) or disconnects (false) Update the MCP status badge — forwarded over the hub as McpServerStatusChanged
OnCardsReady Action<IReadOnlyList<MentorCard>> A tool returned generative-UI cards Render them yourself instead of using CardTemplate
OnGeneratedImages Action<IReadOnlyList<string>> The hosted image tool produced images Show them in your own gallery. Each string is a data: URI or URL
OnHostedToolsDeclared Action<MentorHostedTools> Once per connection, right after connect Drive your own capability badge from what the server actually enabled, rather than from a client-side guess
@inject IMentorStateService State
@inject IMentorOrchestrator Orchestrator
@inject NavigationManager Nav
@implements IDisposable

@if (_capabilities.HasFlag(MentorHostedTools.WebSearch)) { <span class="badge">🌐 web</span> }

@foreach (var url in _images) { <img src="@url" alt="generata" /> }
@* Outside ChatWidget no dispatcher is cascaded: without OnAction the buttons do nothing *@
@foreach (var c in _cards)    { <MentorCardView Card="c" OnAction="OnCardAction" /> }

<span>MCP: @_mcp.Count(x => x.Value)/@_mcp.Count</span>

@code {
    private MentorHostedTools _capabilities;
    private IReadOnlyList<string> _images = [];
    private IReadOnlyList<MentorCard> _cards = [];
    private readonly Dictionary<string, bool> _mcp = new();

    protected override void OnInitialized()
    {
        State.OnHostedToolsDeclared    += Declared;
        State.OnGeneratedImages        += Images;
        State.OnCardsReady             += Cards;
        State.OnMcpServerStatusChanged += Mcp;
    }

    // Fires once per connection, before any message. Render your capability badge from THIS rather
    // than from a client-side copy of the server's configuration — the two drift, and a badge
    // claiming web search the model never got is worse than no badge.
    private void Declared(MentorHostedTools flags) { _capabilities = flags; InvokeAsync(StateHasChanged); }

    private void Images(IReadOnlyList<string> urls) { _images = urls; InvokeAsync(StateHasChanged); }

    // Only if you are NOT using ChatWidget's CardTemplate. Ignoring cards loses them outright: the
    // model is told they are already on screen, so it will not repeat their content as text.
    private void Cards(IReadOnlyList<MentorCard> cards) { _cards = cards; InvokeAsync(StateHasChanged); }

    private async Task OnCardAction(MentorCardAction action)
    {
        if (action.Kind == MentorCardActionKind.SendMessage) await Orchestrator.SendMessageAsync(action.Value);
        else if (action.Kind == MentorCardActionKind.Navigate) Nav.NavigateTo(action.Value);
        // UIAction: run the current page's registered action named action.Value, as ChatWidget does
    }

    private void Mcp(string name, bool connected) { _mcp[name] = connected; InvokeAsync(StateHasChanged); }

    public void Dispose()
    {
        State.OnHostedToolsDeclared    -= Declared;
        State.OnGeneratedImages        -= Images;
        State.OnCardsReady             -= Cards;
        State.OnMcpServerStatusChanged -= Mcp;
    }
}

All eighteen events are listed above — that is the whole of IMentorStateService's read side.

All events fire on a background thread from the SignalR connection. Always use InvokeAsync(StateHasChanged) when updating Blazor component state from these handlers.

Sending state changes — the Notify* side

Each event has a matching Notify* method on the same interface (NotifyStreamingChunk, NotifyCardsReady, …). Those are how the orchestrator raises the events; application code subscribes and does not call them.

The two members you do call are the HITL replies:

Method Purpose
ConfirmAsync(Guid actionId) Approve the pending action
Cancel(Guid actionId) Reject it

actionId is ConfirmationRequest.ActionId from OnConfirmationRequired. In WASM these travel to the server over POST /mentor/approve (at the hub's origin, with the AccessTokenProvider token — see Stop and confirmations), never as a hub method — SignalR dispatches one hub call at a time per connection, so an approval sent through the hub would deadlock behind the turn that is waiting for it.

Custom HITL confirmation dialog

ChatWidget always shows its own inline confirmation prompt when OnConfirmationRequired fires, and no parameter turns it off. Subscribing therefore adds your dialog next to the widget's prompt instead of replacing it. Answering from your dialog also does not close the widget's prompt, which reacts only to its own buttons. To show only your dialog, hide the built-in prompt with CSS (.bm-confirm { display: none !important; }: the package stylesheet sets display: flex on the same selector), then subscribe to OnConfirmationRequired and call ConfirmAsync / Cancel yourself.

This works identically whichever MentorOptions.HitlMode the server uses (Blocking or the Agent Framework's Native flow) — the WASM client sees the same ConfirmationRequired event and replies over the same POST /mentor/approve endpoint, so switching mode server-side needs no client change.

@inject IMentorStateService State
@implements IDisposable

@if (_pendingConfirmation is not null)
{
    <div class="my-confirm-dialog">
        <p>@_pendingConfirmation.Message</p>
        <button @onclick="Approve">Conferma</button>
        <button @onclick="Reject">Annulla</button>
    </div>
}

@code {
    private ConfirmationRequest? _pendingConfirmation;

    protected override void OnInitialized()
    {
        State.OnConfirmationRequired += OnConfirmationRequired;
        State.OnBusyChanged          += OnBusyChanged;
    }

    private void OnConfirmationRequired(ConfirmationRequest req)
        => InvokeAsync(() => { _pendingConfirmation = req; StateHasChanged(); });

    // The turn is over (answered, stopped or failed): nothing waits for this dialog any more.
    private void OnBusyChanged(bool busy)
    {
        if (!busy) InvokeAsync(() => { _pendingConfirmation = null; StateHasChanged(); });
    }

    private async Task Approve()
    {
        if (_pendingConfirmation is not { } req) return;
        _pendingConfirmation = null;
        await State.ConfirmAsync(req.ActionId);
    }

    private void Reject()
    {
        if (_pendingConfirmation is not { } req) return;
        _pendingConfirmation = null;
        State.Cancel(req.ActionId);
    }

    public void Dispose()
    {
        State.OnConfirmationRequired -= OnConfirmationRequired;
        State.OnBusyChanged          -= OnBusyChanged;
    }
}

Close the dialog on the click and when the turn ends, as here. OnApprovalResponse is raised only when the answer reached a turn that was waiting for it, so it suits an audit trail of decisions, not closing a dialog: a click after Stop raises nothing.

// An audit trail: one entry per answer that a waiting turn received
State.OnApprovalResponse += (req, approved) =>
    logger.LogInformation("{Tool} {Decision} by the user", req.ToolName, approved ? "approved" : "rejected");

ConfirmationRequest has three properties: ActionId (Guid), ToolName (string), and Message (string). Use ToolName to customize the dialog copy per action type if needed.


Blazor Auto tip

In a Blazor Auto app, you can keep <ChatWidget /> with @rendermode="InteractiveServer" — it stays server-side with no changes to your existing Novior.MentorAgent setup. Use Novior.MentorAgent.Blazor only when you need the widget to run fully in WebAssembly.

This needs the template's Interactivity location: Per page/component. With Global the layout runs under Auto and, once in WebAssembly, cannot host a server component (NotSupportedException): use Novior.MentorAgent.Blazor there. In the WebAssembly template, first add .AddInteractiveServerComponents() and .AddInteractiveServerRenderMode() to the server's Program.cs, or every page fails with HTTP 500.

@* Keep server-side in Blazor Auto — zero changes needed *@
<ChatWidget @rendermode="InteractiveServer" />

Requirements

  • .NET 10.0+
  • Server project must have Novior.MentorAgent + Novior.MentorAgent.Server installed and configured
  • Browser with WebAssembly support

Package Purpose
Novior.MentorAgent Blazor Server app — AI orchestration engine
Novior.MentorAgent.Server Any ASP.NET Core backend — SignalR hub + SSE + MCP + A2A
Novior.MentorAgent.Abstractions Shared UI components (transitive dep — no need to install directly)
Novior.MentorAgent.Declarative Optional — define Level-2 specialist agents in YAML instead of C#

License

Apache License 2.0 — the full text is in the LICENSE file inside this package, with the copyright notice in NOTICE. Versions up to and including 1.0.0-rc.14 were released under the MIT License, which still applies to them.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.4.0 0 11/18/2026
1.3.1 90 11/14/2026
1.3.0 106 11/11/2026
1.2.0 138 10/27/2026
1.1.0 128 10/21/2026
1.0.0 128 10/13/2026

1.3.0 - 2026-11-05

### Added

- ACTION-RULES.md lists the rules by which a method becomes an action, how actions are named, and how roles and
 confirmations add up. Each rule has a name that does not change and at least one test that fails when the rule does;
 a rule that comes in, changes or is retired is named in the release notes of its version. The rules of 1.3.0:
 `scan.assemblies-once`, `scan.concrete-classes`, `scan.public-instance-declared`, `scan.marker`,
 `scan.mentor-action-wins`, `scan.override-keeps-action`, `kind.one-per-class`, `kind.page-is-separate`,
 `kind.agent-owns-methods`, `kind.skill-methods-level1`, `kind.team-needs-members`, `kind.member-tools-leave-level1`,
 `kind.member-tools-same-rules`, `name.snake-case`, `name.team-tool`, `name.shared-warned`,
 `name.called-method-decides`, `confirm.declared-decides`, `confirm.default-for-writes`,
 `confirm.description-only-not-defaulted`, `confirm.predicate-adds`, `confirm.master-switch`,
 `confirm.beats-read-only`, `confirm.unconfirmed-writes-warned`, `roles.any-of`, `roles.signed-in`,
 `roles.checked-before-confirmation`, `roles.offered-when-allowed`, `surface.coordinator-only`,
 `surface.mcp-withholds-gated` and `surface.card-ungated-only`.

- An action can ship off, and the application can turn its actions on and off from outside its code.
 `[MentorAction(Enabled = false)]` keeps an action in the catalogue (`MentorActionInfo.EnabledByDefault` is false)
 and nowhere else: no agent is offered it, no model reads about it, the MCP server does not list it, the A2A card
 does not show it, and a call to it does not run. An `IMentorActionGovernor`, registered with
 `AddMentorActionGovernor<T>()`, answers for each action whether it is on, and can turn on one the code ships off:
 registering one gives whoever implements it the power to widen what the code allows. It is asked once as a session
 builds its tools, on every `tools/list` of the MCP server and before every call, with the session's id; a session
 keeps the tools it was built with, and a call to an action turned off meanwhile is refused. There can be one: a
 second registration throws. A governor that throws, or does not answer within `ActionPolicyTimeout`, stops the
 action. The A2A card follows the code only, so an action turned on from outside is not on it. New reason codes:
 `disabled` (`Denied`) and `governor-failed` (`PolicyFailed`). New rules: `enabled.off-by-default`,
 `enabled.external-decides` and `surface.governor-session`; `surface.mcp-withholds-gated` and
 `surface.card-ungated-only` now also leave out an action that is off.

- The governor can also give an action its roles: `IMentorActionGovernor.GetRequiredRolesAsync` answers in place of
 `[MentorAction(RequiredRoles = ...)]`, with `null` for the code's roles and an empty list for none. The answer
 decides whom the action is offered to, the check at every call, before a confirmation and again after it, and which
 MCP callers see and call it: an action the MCP server withheld only for its roles is published once the governor
 requires none. `MentorActionDecision.RolesFromOutside` says when the roles came from the governor. New rule:
 `roles.external-replace`; `roles.checked-before-confirmation` now checks the governor's roles when it gives them.

- The governor can also decide whether the user confirms an action: `IMentorActionGovernor.GetConfirmationAsync`
 answers `MentorConfirmationChoice.Code` for the code's confirmation, `Required` to ask even if the code does not,
 and `None` not to ask even if the code does — declared, by default for writes, or by `RequiresApproval`. A
 confirmation added counts from the call, one taken away from the next session, and in Native mode no auto-approval
 rule lets a required one through. A policy's `Confirm` still asks, a hosted MCP server's approval still comes from
 its provider, and with `RequireConfirmation` off nobody is asked. An action whose confirmation is taken away still
 counts as one that changes data. The MCP server publishes an action that asks for confirmation once the governor
 takes it away, and withholds one it requires. `MentorActionDecision.ConfirmationFromOutside` says when the governor
 changed whether a call is confirmed. New rule: `confirm.external-decides`; `confirm.predicate-adds` and
 `surface.mcp-withholds-gated` now say what the governor can take away.

- The governor can also rewrite the description the model reads: `IMentorActionGovernor.GetDescriptionAsync` answers
 in place of the code's, with `null` or a blank text for the code's. It is asked as a session builds its tools and
 on every `tools/list` of the MCP server, and the answer is what the coordinator, the specialists and the team
 members read, what tool filtering ranks, and what `tools/list` shows; the action's name and argument schema never
 change, and the code's `ProactiveHint` still follows the description. What the user sees keeps the code's
 description: the confirmation banner, the bar of the running action and `MentorActionDecision.DisplayName`. On a
 call to the MCP server the policies are asked with the code's description. New rule: `describe.external-replace`.

- An `IMentorAgentSource` says what it loaded and what it left out, and when it is asked is a promise. A source is
 asked whenever a coordinator is built: at least once per session — once per Blazor circuit, MAUI app scope or hub
 connection, and at every request on `/mentor/chat` and every task over A2A — and `MentorAgentSourceContext.SessionId`
 names the session, as `MentorActionRequest.SessionId` does. MentorAgent now calls `IMentorAgentSource.LoadAsync`,
 which returns a `MentorAgentSourceResult`: the agents, and a `MentorAgentRejection` (`Name`, `ReasonCode`, `Detail`,
 `Tool`) for each definition left out or tool taken away. Its default body returns the agents of `GetAgentsAsync`, so
 an existing source works unchanged. An `IMentorAgentSourceObserver`, registered with
 `AddMentorAgentSourceObserver<T>()`, receives a `MentorAgentSourceReport` for each source every time a coordinator
 is built, also when the source loaded nothing; a source that throws is reported as `source-failed`, with the
 exception's type and never its message. The reason codes, in `MentorAgentRejectionReasons`: `invalid-definition`,
 `not-an-agent`, `foreign-tools`, `invalid-configuration`, `source-failed`, `tool-not-found` and
 `hosted-tool-removed`. **Novior.MentorAgent.Declarative** reports every definition it does not load and every tool
 it takes away. New rules: `declarative.functions-match` and `declarative.no-hosted-tools`.

- `MentorRuntimeOptions.Changeable` lists the options that can be changed while the application runs, and from when
 a change applies (`MentorOptionReadAt`). From the next turn of every session: `Language`, `RateLimitPerUser`,
 `RateLimitWindowSecs`, `ConfirmationMessage`, `ConfirmationTimeout`, `ActionPolicyTimeout`, `EnableActionFeedback`,
 `EnableGenerativeCards`, `EnableSafetyCheck` and `CheckAnnouncedActions`. From the sessions that begin after the
 change: `MentorshipLevel`,
 `ProactiveNextSteps`, `EnableRichResponses`, `RefuseOutOfScope`, `ToolFilterMaxTools` and `MaxSessionMessages`. To
 change one, assign it on the `IOptions<MentorOptions>` value, replacing a collection rather than changing it in
 place. Every other option is read before the application starts: set it there. Each option listed has a test that
 changes it on a running application, and every option declares when it is read, so a new one cannot ship without
 the decision.

- After a turn in which the coordinator called no tool, MentorAgent asks a model whether its reply announces an action
 ("I'm registering the note…") or reports one as done when nothing ran (`MentorOptions.CheckAnnouncedActions`, on by
 default). If it does, the coordinator gets one more request in the same turn, with the same tools, told to call the
 tool now or to say that it was not done. The question names the tools the model was sent, and the answer names the
 one that does the action: the second request then says that this tool is there to call now. The instruction is that
 request's last message, read after the reply it is about, and never stored. A call to an action of the application
 the agent was not given (one that is off for the session) runs nothing, and the turn is checked as one in which
 nothing ran. The call is never required and passes the gate as any other, the reply
 already shown is not held back, and the second reply is not checked again. The question goes to
 `ClassifierChatClient`, or to `ChatClient` without one: a few hundred tokens after every reply that called no tool,
 so a small deployment there is worth configuring. Its verdict is logged at Information for every reply it checks,
 with the time and the tokens it took. On Path A with the history kept by MentorAgent; not with
 `UseServiceManagedHistory` nor with a pre-built `Agent` (BUG-220).

- A call the model makes to an action of the application that the coordinator was not given in the turn — one that
 is off, or another agent's — reaches no gate and runs nothing. `IMentorActionObserver` now receives its one
 decision, `Denied` with the new reason code `not-offered`, and the call's span says the same, in Blocking and in
 Native mode, with `CheckAnnouncedActions` on or off. A call the coordinator was given keeps the decisions of its
 gate, and only those.

- One instance of the application can tell which tenant a request belongs to. `IMentorTenantResolver`, registered with
 `services.AddMentorTenantResolver<T>()` (one per application), names it from the caller, the surface and the
 request's services; `IMentorTenant.Id` reads it, in an action, a policy or the governor, and
 `IMentorTenant.GetIdAsync()` resolves it first in a scope that had no turn yet. It is asked when a turn
 starts — in a Blazor circuit, on the hub, on `/mentor/chat`, in an A2A task — and for every `tools/list` and
 `tools/call` of the MCP server, where each call reads its own. A request is never served without a tenant: a resolver
 that throws, or answers `null`, empty or white space, refuses it before the model or the action, and a turn whose
 tenant is not the one its conversation began with is refused too. Without a resolver there is one tenant, as before,
 and `IMentorTenant.Id` is `null`.

- With an `IMentorTenantResolver`, two tenants on one instance share no memory, no rate limit and no conversation.
 `MentorMemoryService.GetUserIdAsync()` — the key of the memory and of `RateLimitPerUser` — is the tenant's own
 (`tenant:<id>/<the user's key>`), the shared anonymous bucket included, and so is the MCP server's per-caller
 allowance. A session snapshot names its tenant and is restored for that tenant only: one of another tenant, one that
 names none where a resolver is registered, and one that names a tenant where none is, are refused before the
 conversation changes (a 400 on `/mentor/session`). The history MentorAgent keeps is a coordinator's own, as before; a
 single `ChatHistoryProvider` instance with a resolver registered is reported at start-up, since it serves every tenant
 — `ChatHistoryProviderFactory` runs in the conversation's scope, where `IMentorTenant` reads the tenant. Without a
 resolver every key and every snapshot is as before.

- With an `IMentorTenantResolver`, every metric names its tenant: the `mentoragent.tenant` tag is on the four counters
 (`mentoragent.turns`, `mentoragent.tool_calls`, `mentoragent.errors`, `mentoragent.guardrail_blocks`) and on the
 `mentor.turn` span, the MCP server's calls included, so the whole instance is read per tenant from OpenTelemetry. The
 token & cost dashboard and `GET /mentor/admin/metrics` show the figures of the reader's tenant only: tokens, cost,
 turns, errors, guardrail blocks and top actions. A reader whose tenant the resolver does not name sees none (a 403
 on the endpoint). `IMentorMetrics.GetSnapshot(string? tenant)` and `IMentorMetricsStore.QueryAsync(string? tenant,
 CancellationToken)` are new, with defaults that keep existing implementations working. A custom `IMentorMetrics`
 shows a tenant nothing rather than the instance's figures (a 204 on the endpoint). A store is asked for a tenant only
 when it implements the new overload. A tenant's figures are kept in RAM since the process started; the store saves
 and seeds the instance's. Without a resolver the series, the dashboard and the endpoint are as before.

- With an `IMentorTenantResolver`, retrieval and the logs know the tenant. `MentorRagRequest.TenantId` gives a RAG
 source the turn's tenant; MentorAgent filters nothing, so a source that holds several tenants' documents returns
 that tenant's. A source that implements only the `(query, maxResults)` overload never sees it, and a Warning says
 so at its first search with a tenant. Every log line of a turn, the application's own code in the turn included,
 and of a call to the MCP server is written in a log scope with one pair, `mentoragent.tenant`, the key of the
 metrics and the span; a provider that includes scopes shows it. Without a resolver nothing changes.

- `MentorOptions.RagNoResultsNotice` (off by default) tells the model when the knowledge-base search of a turn kept no
 document — none returned, or every one below `RagMinScore`: a question the documents would cover is answered "not
 found in the documents" rather than from memory, and a message that needs no document, such as a greeting or an
 action, is answered as usual. The text is MentorAgent's, in the language of the turn, in that request's
 instructions only. It is not given after a search that failed, nor without a source.

- A knowledge-base search that fails can be monitored. With `EnableObservability` it is counted on
 `mentoragent.rag_failures`, tagged with the source (`mentoragent.rag.source`, its type's full name) and the
 exception's type (`mentoragent.error.type`), never its message, and with `mentoragent.tenant` when a resolver is
 registered; a Stop during the search is not counted. Each search has a `mentor.rag.search` span, with the source,
 and the status Error when it failed. The Warning names the source: "The search of … failed — RAG context skipped.".

- `IMentorRagSource.OnConversationChangedAsync` tells a source that the session's conversation changed, so one that
 keeps state for it clears it: `MentorConversationChange.Reason` is `Reset` (New conversation), `Restored` (a saved
 conversation took its place) or `Replaced` (a restored conversation the service no longer knew was replaced,
 BUG-110), with the session's id and its tenant. The default does nothing, so an existing source works unchanged. It
 is called with `UseRag` on, on the instance the session searches with, bounded by `SafetyCheckTimeout`; a source
 that throws or does not answer in time is logged as a warning, and the conversation changes anyway.

- `MentorVectorStoreRagSource<TRecord>`, a knowledge-base source over any collection of
 `Microsoft.Extensions.VectorData` (pgvector, Qdrant, Azure AI Search, an in-memory one), registered with
 `services.AddMentorVectorStoreRag(sp => collection, new MentorVectorStoreRagOptions<TRecord> { Content = … })`.
 The options say what of a record is the document, its title, its link and its metadata, and which records a request
 may see (`Filter`, given the `MentorRagRequest` with its tenant and user). Scores are read as similarities whatever
 the collection's distance function: with `CosineDistance`, the Postgres default, the source uses 1 − distance, so
 `RagMinScore` keeps the nearest documents. The function comes from `DistanceFunction` or from the record's
 `[VectorStoreVector]` attribute; when neither names one, or it is a Euclidean, Manhattan or Hamming distance,
 registering the source fails. The message is embedded once per turn with `MentorOptions.EmbeddingGenerator` and
 shared with routing, tool filtering and memory, or with a generator of the source's own; without either, the
 collection embeds the text itself. `DefaultMinScore` is 0.5. With a tenant resolver and no `Filter`, the first
 search with a tenant is logged as a warning. `Novior.MentorAgent` now references
 `Microsoft.Extensions.VectorData.Abstractions` 10.10.0, which Agent Framework already brought.

- A provider that ignores `tool_choice: "required"` is reported. `RequireLookupForRecordQuestions` and
 `RequireActionForChangeRequests` require the first call of the turn with `ChatToolMode.RequireAny`; a provider that
 answers such a request without any call — Ollama ignores `tool_choice` — makes them do nothing, and the first time
 it does a warning says so, once per provider client: "The provider answered a request that required a tool call
 (tool_choice: required) without calling one: …". A call to a tool the request did not offer is still a call, and a
 streamed reply is looked at as it goes by, nothing held back. The README has a recipe for llama-server and vLLM.

- `CoordinatorSampling` (`MentorSamplingOptions`): the coordinator's sampling — `Temperature`, `TopP`, `TopK`,
 `MaxOutputTokens`, `FrequencyPenalty`, `PresencePenalty`, `Seed` — on every request of its turns, the forced first
 call and the follow-ups of the tool loop included. The option unset, and each value left null, is the provider's
 own; in configuration, `Mentor:CoordinatorSampling:Temperature` and so on. The classifiers call the provider directly
 and keep their own settings: those that ask for temperature 0 still do, the others keep the provider's default, as
 before. A negative temperature, a top-p outside (0, 1], or a top-k or output limit below 1 stops the application at
 startup. Stop sequences are not offered: one that also occurs in a tool call's arguments would cut the call short.

- `WarmUpChatModel`: with `WarmUpAtStartup`, the warm-up also sends the coordinator's model one minimal request, so
 the first turn does not pay for opening the connection, the provider's empty prompt cache or a local model still
 loading. Every start costs one request per client — `ChatClient`, and `StrongChatClient` when it is set — with the
 coordinator's instructions, tools and sampling, no call allowed (`ChatToolMode.None`), one short user message and at
 most 16 output tokens. It goes straight to the provider client: no history, no memory, no turn on the dashboard;
 the warm-up's log line gives its time and tokens. A request that fails is a warning, and the application carries
 on; without `WarmUpAtStartup` the option has no effect, and a startup warning says so.

- `MentorEvaluator.RunConversationsAsync`: whole conversations (`EvalConversation`, `EvalTurn`) through the mentor
 itself — the orchestrator, streaming, with its tools, filters, roles, RAG, memory and the history from one turn to
 the next — each in a session of its own. A turn can require tools (`ExpectTools`: "at turn 2 it must call X"),
 forbid others (`ForbidTools`), and set a token budget, a limit on the time to the first token and an expectation
 for the judge. Its result adds `ToolsCalled`, read from the tool gate, `TimeToFirstToken`, `TurnDuration`,
 `Conversation` and `Turn`; its tokens are those of its own session, exact while other sessions talk. **Every
 confirmation is answered no by default: an evaluation does not write data on its own.**
 `MentorEvalOptions.ApproveConfirmations` answers yes, and `PrepareSession` sets the conversation's user or page
 before its first turn. `RunAsync` is unchanged; `SystemInstructions`, `Checks` and `Evaluators` stay its own.

- `EvalTurn.ExpectRefusal`: a conversation turn can expect the mentor to refuse — `EvalRefusal.OutOfScope`
 (`RefuseOutOfScope`), `EvalRefusal.Guardrail` (the safety check, the host's `InputGuardrail`, or the model refusing
 to answer) or `EvalRefusal.Any`. That refusal, shown to the user as an error, then passes the turn and the
 conversation goes on; a turn that was answered, refused the other way or failed, fails, and its notes say which. A
 safety check that could not run, a message too long, the rate limit and a missing tenant are not refusals: they stay
 errors. Without the expectation a refusal fails the turn as before. `MentorEvalResult.Refusal` reports the refusal a
 turn showed, expected or not.

- A `dotnet new` template in the repository, `templates/mentoragent-blazor`: a Blazor Server helpdesk with a
 MentorAgent assistant and three actions — `list_open_tickets`, `assign_ticket` with a confirmation, `close_ticket`
 with a confirmation and the `Agent` role — the model from the configuration with its key in the user secrets, and a
 test sign-in with two users, one without the role. Its test project runs the assistant with a scripted model through
 `RunConversationsAsync`: a support agent who confirms closes a ticket, without a yes the ticket stays open, and
 without the role the action is not offered. It is installed from a clone of the repository, not from NuGet:
 `dotnet new install templates/mentoragent-blazor`, then `dotnet new mentoragent-blazor -n Helpdesk`.

### Changed

- An `IMentorRagSource` that answers with no list (`null`) fails at once, with a message that says a source finding
 nothing returns an empty list, instead of a `NullReferenceException` later on. The turn goes on without documents,
 as before.

- **Novior.MentorAgent.Declarative:** a `kind: function` entry that names no action of the session — unknown to the
 application, or off for the session — is taken away from the agent, with a warning, and the agent loads without it.
 The Agent Framework used to give the agent a function of that name with nothing behind it: the model could call it,
 nothing ran, and the agent stopped without a word in the log. An action that is off is therefore described to no
 model through a definition that names it either.

- Every package is now checked at pack time against the public API of 1.2.0, so 1.3.0 cannot break code built
 against 1.2.0 by accident. An intended break is listed in this file as Breaking.

- The family moves onto the Microsoft Agent Framework 1.27.0 line (`Microsoft.Agents.AI` and
 `Microsoft.Agents.AI.Workflows` 1.27.0). **Novior.MentorAgent.Declarative:** `Microsoft.Agents.AI.Declarative` moves
 to 1.27.0-rc1, on the same line. The two breaking changes of Agent Framework 1.27 are in parts MentorAgent does not
 use: `AddFoundryResponses` for hosted Foundry applications, and the redirect callbacks of `DefaultHttpRequestHandler`.

- The packages' description and tags say what MentorAgent is: AI agents in a .NET application under your rules —
 roles, confirmations, cost control. The tags of `Novior.MentorAgent`, `.Server` and `.Blazor` now include
 `ai-governance`, `governance`, `authorization`, `roles`, `approval` and `human-in-the-loop`; the `mentor` tag, which
 found only namesakes, is gone from all five packages.

### Fixed

- When a restored conversation the service no longer knew was replaced by a new one (BUG-110), the knowledge-base
 search kept the recent messages of the conversation that was gone: the first search of the new one was given the
 message of the turn that had failed. They are now cleared, as on a reset or a restore.

- The turn's vector of the message (`IMentorQueryEmbedding`) was kept on its text alone (BUG-229): a knowledge-base
 source that embeds the message with a model of its own was handed the vector of `MentorOptions.EmbeddingGenerator`,
 or routing, tool filtering and memory were handed the source's, whichever asked first in the turn. Each generator
 now gets the vector it makes, still computed once per turn, compared by reference; at most four generators are
 remembered, the oldest dropped first, so one built for every call cannot make the cache grow.

### Security

- **Novior.MentorAgent.Server:** BUG-230 (S1): `GET /mentor/chat` ran a turn for any request the browser sent with the
 sign-in cookie, and with cookie authentication (`SameSite=Lax`) that includes a link clicked on another site: one
 link ran a turn as the signed-in user, with the link author's question, even with `RequireAuthorization`. Both
 `GET` and `POST /mentor/chat` now answer `403` before the turn when the browser's Fetch Metadata says another site
 started the request (`Sec-Fetch-Site` `cross-site` or `same-site`, `Sec-Fetch-Mode` not `cors`), and log a warning
 `chat.cross-site-refused` without the question. Your own page's calls, clients without Fetch Metadata and `cors`
 requests work as before. With a `SameSite=None` cookie, or for browsers that send no Fetch Metadata, add a check
 of your own: the Server README says how.

The full history is in CHANGELOG.md, inside this package.