MentorAgent.Blazor 1.0.0-preview.3

MentorAgent.Blazor

Preview Release — MentorAgent is currently in public preview. APIs may change before the stable release.

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

Connects to a 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.

What MentorAgent can do

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

Package Family

Getting started

Installation

# Client project
dotnet add package MentorAgent.Blazor --prerelease

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

Server project setup

All AI behaviour is configured on the server (the transitive 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
app.MapMentorAgentMcp();      // optional
app.MapMentorAgentA2A();      // optional

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 =>
{
    // #7 middleware hooks
    options.OnException = ex => ex.Message.Contains("rate", StringComparison.OrdinalIgnoreCase)
        ? "The service is busy, please retry shortly." : null;
    options.ConfigureChatClientPipeline = b => b.UseLogging();

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

    // #9 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 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 MentorAgent.Abstractions.Components
@using 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 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 MentorAgent.Blazor.Extensions;

builder.Services.AddMentorAgentBlazor(options =>
{
    options.HubUrl       = "/mentor-hub";    // URL of 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".
• 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 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";
});

Add the widget

In MainLayout.razor or any page:

@using MentorAgent.Abstractions.Components

<ChatWidget />

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

Unlike Blazor Server (where the widget injects CSS automatically via <HeadContent>), Blazor WASM 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/MentorAgent.Abstractions/css/MentorAgent.css" rel="stylesheet" />
</head>
<body>
    ...
    <script src="_content/MentorAgent.Abstractions/js/MentorAgent.js"></script>
</body>

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

On Blazor Server, <ChatWidget /> injects its own CSS and JS automatically — no changes to _Host.cshtml or App.razor needed.

Widget customization

Theme and appearance

options.Theme        = MentorTheme.Minimal;   // Default | Dark | Minimal | Custom
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

Voice

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

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.

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

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 (for pages with async UI actions)

Use OnInitializedAsync — not OnAfterRenderAsync. Calling SignalReady() from OnAfterRenderAsync silently breaks all UI actions because the AI may have already timed out waiting for the signal.

protected override async Task OnInitializedAsync()
{
    await LoadDataAsync();
    PageContext.SignalReady();   // must be last — tells AI that UI actions are ready
}

Page navigation

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

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

[MentorPage("/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.

UI Action overloads reference

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

Automatic parameterHint generation

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

Override only when extra clarity is needed:

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

Async handlers are awaited — the AI waits for completion before continuing. This makes multi-action chains reliable.

[MentorPage] parameters (server project)

All AddMentorAgentBlazor() options

How it works

[Blazor WASM Browser]
  ChatWidget
    ↓ IMentorOrchestrator (WasmMentorOrchestrator)
    ↓ SignalR
[ASP.NET Core Server — 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 by ConfirmationBanner. 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 handles this automatically.
• Navigation triggered by the AI arrives as NavigationRequested and is handled by Blazor's NavigationManager.

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

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

Custom HITL confirmation dialog

By default, ChatWidget renders a built-in ConfirmationBanner. If you want to replace it with your own modal or dialog, subscribe to OnConfirmationRequired and call ConfirmAsync / Cancel yourself:

@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.OnApprovalResponse     += OnApprovalResponse;
    }

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

    private void OnApprovalResponse(ConfirmationRequest req, bool approved)
        => InvokeAsync(() => { _pendingConfirmation = null; StateHasChanged(); });

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

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

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

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 MentorAgent setup. Use MentorAgent.Blazor only when you need the widget to run fully in WebAssembly.

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

Requirements

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

Related Packages