MentorAgent.Abstractions 1.0.0-rc.3

MentorAgent.Abstractions

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

You do not need to install this package directly. It is included automatically as a transitive dependency of MentorAgent and MentorAgent.Blazor.

This package is the shared foundation of the MentorAgent family. It contains all the contracts, models, and UI components shared between the server-side and client-side packages — with no AI or ASP.NET Core server dependencies, making it fully compatible with Blazor WebAssembly.

Table of Contents

• Package Family
• What's included
  • Interfaces
  • Models
  • Enums
  • UI Components (Razor)
  • Core
• Component parameter reference
• Static assets — CSS and JS
• When you actually touch this package
• Why a separate package?
• Requirements
• Related Packages
• License

Package Family

What's included

Interfaces

Models

Enums

UI Components (Razor)

All MentorAgent UI components live here so they work identically in both Blazor Server and Blazor WASM:

Core

Component parameter reference

Every component is presentational in the sense that matters: it takes its data through parameters and raises callbacks out, never calling the AI itself. That is what lets the identical component serve Blazor Server (data from DI) and WebAssembly (data over HTTP), and it is what lets you compose the parts on your own pages instead of taking the whole widget.

ChatWidget is the exception — it is the assembled widget and resolves IMentorOrchestrator, IMentorStateService and navigation for itself.

They still need DI. Every component injects IOptions<MentorWidgetOptions>, MentorLocalizer or both, so AddMentorAgent() / AddMentorAgentBlazor() must have run in that host. Rendering MessageBubble on a page of an app that never registered MentorAgent throws at build-render time, not at first interaction.

ChatWidget

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

Everything else about the widget comes from MentorWidgetOptions in DI, not from parameters — see the option tables in the MentorAgent or MentorAgent.Blazor README, depending on which host you use.

MentorDashboard

The Refresh button is always rendered; OnRefresh only decides whether anything of yours runs when it is pressed. With no data at all the component renders its empty state rather than throwing.

Its resolution order when Snapshot is null is: an external IMentorMetricsStore.QueryAsync() first (so a Prometheus/Azure Monitor aggregate wins), then the live in-RAM IMentorMetrics snapshot.

@* Blazor Server — no parameters needed *@
<MentorDashboard />

@* WASM — you own the fetch *@
<MentorDashboard Snapshot="_snapshot"
                 OnRefresh="Reload"
                 Currency="€"
                 Language="MentorLanguage.Italian" />

MentorCardView

<MentorCardView Card="_card" OnAction="RunCardAction" />

@code {
    private readonly MentorCard _card = new("order")
    {
        Title    = "Ordine #1002",
        Subtitle = "Laura Bianchi",
        Accent   = MentorCardAccent.Info,
        Fields   = [new("Stato", "Shipped"), new("Totale", "1.249,98 €")],
        Actions  =
        [
            new("Apri",     MentorCardActionKind.Navigate,    "/orders/1002"),
            new("Dettagli", MentorCardActionKind.SendMessage, "Dammi i dettagli dell'ordine 1002"),
        ],
    };

    private Task RunCardAction(MentorCardAction action) => action.Kind switch
    {
        MentorCardActionKind.Navigate    => Task.Run(() => Nav.NavigateTo(action.Value)),
        MentorCardActionKind.SendMessage => Orchestrator.SendMessageAsync(action.Value),
        _                                => Task.CompletedTask,
    };
}

The buttons are written by the tool that produced the card, never by the model's prose — which is why a card can safely carry actions. ChatWidget wires OnAction for you; wire it yourself only when you render cards outside the widget.

MessageBubble

@foreach (var m in _messages)
{
    <MessageBubble Message="m.Message" SentAt="m.At" Sources="m.Sources" />
}

@* the one still arriving — the caret is the only difference *@
@if (_streaming is not null)
{
    <MessageBubble Message="_streaming" IsStreaming="true" />
}

Message is MEAI's own ChatMessage, so the role decides the side and the styling. Model text is HTML-encoded before any Markdown tag is emitted, so a reply containing <script> renders as text.

ChatInput

<ChatInput OnSend="Send" Disabled="_busy" Placeholder="Chiedi qualcosa sugli ordini…" />

@code {
    private bool _busy;

    private async Task Send(MentorUserMessage message)
    {
        _busy = true;
        try
        {
            // Text AND attachments. An image-only turn — empty Text, one attachment — is valid.
            await Orchestrator.SendMessageAsync(message.Text, message.Attachments);
        }
        finally { _busy = false; }
    }
}

OnboardingTour

OnNavigate and OnAsk are engagement, not dismissal: the host is expected to suspend the tour and resume at the next step, not mark it seen. ChatWidget already does this.

@if (_tourOpen)
{
    <OnboardingTour Steps="_steps"
                    StartIndex="_resumeAt"
                    OnIndexChanged="Persist"
                    OnNavigate="GoThere"
                    OnAsk="AskThat"
                    OnClose="Finish" />
}

@code {
    private IReadOnlyList<MentorTourStep> _steps = [];
    private bool _tourOpen;
    private int  _resumeAt;

    protected override async Task OnInitializedAsync()
    {
        // Blazor Server: IMentorTour from DI. WASM: GET /mentor/tour.
        _steps    = await Tour.GetStepsAsync();
        _resumeAt = await LoadSavedIndex();          // your storage; clamped for you
        _tourOpen = _steps.Count > 0;
    }

    private Task Persist(int index) => SaveIndex(index);

    // Engagement, not dismissal: suspend and resume at the NEXT step rather than marking it seen.
    private async Task GoThere(string url)  { _tourOpen = false; await SaveIndex(_resumeAt + 1); Nav.NavigateTo(url); }
    private async Task AskThat(string q)    { _tourOpen = false; await SaveIndex(_resumeAt + 1); await Orchestrator.SendMessageAsync(q); }

    private Task Finish() { _tourOpen = false; return MarkSeen(); }
}

ConfirmationBanner

@if (_pending is not null)
{
    <ConfirmationBanner Request="_pending" OnConfirm="Approve" OnCancel="Reject" />
}

@code {
    private ConfirmationRequest? _pending;

    protected override void OnInitialized() =>
        State.OnConfirmationRequired += r => { _pending = r; InvokeAsync(StateHasChanged); };

    private async Task Approve() { var r = _pending!; _pending = null; await State.ConfirmAsync(r.ActionId); }
    private Task     Reject()    { var r = _pending!; _pending = null; State.Cancel(r.ActionId); return Task.CompletedTask; }
}

On WebAssembly answer over HTTP — POST /mentor/approve?actionId=…&approved=true|false — not through a hub method: SignalR dispatches one invocation at a time per connection, so a hub call would queue behind the very turn it is meant to release.

WelcomePanel

@if (_messages.Count == 0)
{
    <WelcomePanel BotName="Assistente ShopFlow"
                  WelcomeMessage="Ciao! Posso aiutarti con ordini e prodotti."
                  EnableSuggestions="true"
                  OnChipClick="Send" />
}

The chip's text arrives as an ordinary user turn — there is nothing special about it, which is why OnChipClick and the input's OnSend can share one handler.

RagSourcePanel

<RagSourcePanel Sources="_sources" />

@code {
    // null or empty renders nothing at all, so there is no need to guard the element.
    private IReadOnlyList<MentorRagResult>? _sources;

    protected override void OnInitialized() =>
        State.OnRagSourcesReady += s => { _sources = s; InvokeAsync(StateHasChanged); };
}

Status badges

bool? in ServerStatus is three-valued on purpose: true connected, false failed, null not yet probed. Rendering null as "failed" would show a red badge during startup.

<McpStatusBadge ServerStatus="_mcp" OnToggle="() => _mcpOpen = !_mcpOpen" />
<McpDetailBar   Visible="_mcpOpen" ServerStatus="_mcp" OnClose="() => _mcpOpen = false" />

<A2AStatusBadge OnToggle="() => _a2aOpen = !_a2aOpen" />
<A2ADetailBar   Visible="_a2aOpen" OnClose="() => _a2aOpen = false" />

@code {
    private bool _mcpOpen, _a2aOpen;

    // name → connected. Start empty rather than false: nothing has been probed yet.
    private Dictionary<string, bool?> _mcp = new();

    protected override void OnInitialized() =>
        State.OnMcpServerStatusChanged += (name, ok) =>
        {
            _mcp[name] = ok;
            InvokeAsync(StateHasChanged);
        };
}

The A2A badge takes no data parameter on purpose — its agent list comes from MentorWidgetOptions.RemoteAgentDisplays, because a remote agent is configuration rather than runtime state.

TypingIndicator

No parameters — animated dots. Show it while a turn is in flight and nothing has streamed yet.

@if (_busy && _streaming is null)
{
    <TypingIndicator />
}

Show it only while a turn is in flight and nothing has streamed yet — once the first token lands, MessageBubble with IsStreaming="true" carries the signal instead.

Composing your own chat surface

The reason these components take parameters and raise callbacks instead of calling the AI is so you can build a surface that is not the floating widget — an inline panel, a side rail, a page of your own. Everything below is host-agnostic: in Blazor Server the state service comes from DI, on WebAssembly the same interface is backed by the hub.

@inject IMentorOrchestrator Orchestrator
@inject IMentorStateService State
@implements IDisposable

<div class="my-chat">
    @if (_messages.Count == 0)
    {
        <WelcomePanel BotName="Assistente" OnChipClick="Send" />
    }

    @foreach (var m in _messages)
    {
        <MessageBubble Message="m" />
    }
    @if (_streaming is not null) { <MessageBubble Message="_streaming" IsStreaming="true" /> }
    @if (_busy && _streaming is null) { <TypingIndicator /> }

    <RagSourcePanel Sources="_sources" />

    @if (_pending is not null)
    {
        <ConfirmationBanner Request="_pending" OnConfirm="Approve" OnCancel="Reject" />
    }

    <ChatInput OnSend="OnSend" Disabled="_busy" />
</div>

@code {
    private readonly List<ChatMessage> _messages = [];
    private ChatMessage? _streaming;
    private IReadOnlyList<MentorRagResult>? _sources;
    private ConfirmationRequest? _pending;
    private bool _busy;
    private readonly System.Text.StringBuilder _buffer = new();

    protected override void OnInitialized()
    {
        State.OnStreamingChunk     += Chunk;
        State.OnStreamingCompleted += Completed;
        State.OnBusyChanged        += Busy;
        State.OnRagSourcesReady    += Rag;
        State.OnConfirmationRequired += Confirm;
    }

    private void Chunk(string c)
    {
        _buffer.Append(c);
        _streaming = new ChatMessage(ChatRole.Assistant, _buffer.ToString());
        InvokeAsync(StateHasChanged);
    }

    private void Completed()
    {
        if (_buffer.Length > 0) _messages.Add(new ChatMessage(ChatRole.Assistant, _buffer.ToString()));
        _buffer.Clear();
        _streaming = null;
        InvokeAsync(StateHasChanged);
    }

    private void Busy(bool b)                          { _busy = b; InvokeAsync(StateHasChanged); }
    private void Rag(IReadOnlyList<MentorRagResult> s) { _sources = s; InvokeAsync(StateHasChanged); }
    private void Confirm(ConfirmationRequest r)        { _pending = r; InvokeAsync(StateHasChanged); }

    private async Task Send(string text) => await OnSend(new MentorUserMessage(text));

    private async Task OnSend(MentorUserMessage m)
    {
        _messages.Add(new ChatMessage(ChatRole.User, m.Text));
        _sources = null;
        await Orchestrator.SendMessageAsync(m.Text, m.Attachments);
    }

    private async Task Approve() { var r = _pending!; _pending = null; await State.ConfirmAsync(r.ActionId); }
    private Task     Reject()    { var r = _pending!; _pending = null; State.Cancel(r.ActionId); return Task.CompletedTask; }

    public void Dispose()
    {
        State.OnStreamingChunk       -= Chunk;
        State.OnStreamingCompleted   -= Completed;
        State.OnBusyChanged          -= Busy;
        State.OnRagSourcesReady      -= Rag;
        State.OnConfirmationRequired -= Confirm;
    }
}

Unsubscribe. These are plain C# events on a scoped service that outlives your component, so a component that subscribes and never detaches is kept alive by the service and re-rendered after disposal. ChatWidget does this for you; a hand-built surface has to do it itself.

Static assets — CSS and JS---

Static assets — CSS and JS

The stylesheet and the JavaScript layer ship in this package, not in MentorAgent:

_content/MentorAgent.Abstractions/css/MentorAgent.css
_content/MentorAgent.Abstractions/js/MentorAgent.js
_content/MentorAgent.Abstractions/IconMA.png     ← default avatar

ChatWidget injects the first two itself through <HeadContent>, so a Blazor Server or Blazor Web App host needs no markup. A standalone WASM host references them manually in index.html instead — and neither file is fingerprinted, so the ?v= query string is the cache buster and you must bump it by hand after changing either. A stale MentorAgent.js fails silently and looks like missing features rather than a caching problem.

The JS layer covers text-to-speech (sentence-queued, barge-in, hands-free), speech recognition, the image composer (upload, paste, drag & drop, client-side downscaling) and localStorage helpers. It is called through IJSRuntime by the components; there is no supported way to call it directly.

For the complete CSS variable reference — palette, widget size, fonts, the dashboard and chart colours — see Widget customization → CSS variables in the MentorAgent README. The variables are defined here but documented there, next to the options that set them.

When you actually touch this package

Most of the time you never reference these types by name — MentorAgent and MentorAgent.Blazor wire them for you. Three cases where you do:

1. Rendering the admin dashboard yourself. MentorDashboard is presentational, so the same component works in-process and over HTTP. In Blazor Server, inject the metrics; in WASM, fetch the snapshot from the admin endpoint:

@* Blazor Server — in-process. It resolves the metrics itself; no parameters needed. *@
<MentorDashboard />

@* WASM — over HTTP. No MentorAgent DI here, so pass the language explicitly. *@
@inject HttpClient Http
<MentorDashboard Snapshot="_snapshot" Language="MentorLanguage.Italian" />
@code {
    MentorMetricsSnapshot? _snapshot;
    protected override async Task OnInitializedAsync() =>
        _snapshot = await Http.GetFromJsonAsync<MentorMetricsSnapshot>("/mentor/admin/metrics");
}

Put it behind authorization. The snapshot is operator data — cost, volumes, top actions — and must never appear on an end-user page.

2. Persisting or aggregating metrics. Implement IMentorMetricsStore and register it before AddMentorAgent() / AddMentorAgentServer(). Without one the snapshot lives in RAM and resets on restart; with one you get durability, or you can serve an external aggregate instead:

Every method has a default no-op implementation, because the two scenarios use different halves of the contract — implement only the one you need:

// (A) Local durability — restore totals at startup, persist periodically and on shutdown.
//     QueryAsync stays default (null) so the dashboard keeps serving the live in-RAM snapshot.
public sealed class FileMetricsStore : IMentorMetricsStore
{
    public Task<MentorMetricsSnapshot?> LoadForSeedAsync(CancellationToken ct = default) => /* read  */;
    public Task SaveAsync(MentorMetricsSnapshot s, CancellationToken ct = default)       => /* write */;
}

// (B) External source — serve the aggregate your OpenTelemetry export already pushed to
//     Prometheus / Azure Monitor (multi-instance, historical). Nothing to seed, nothing to save.
public sealed class PrometheusMetricsStore : IMentorMetricsStore
{
    public Task<MentorMetricsSnapshot?> QueryAsync(CancellationToken ct = default) => /* query */;
}

builder.Services.AddSingleton<IMentorMetricsStore, FileMetricsStore>();   // BEFORE AddMentorAgent()

3. Building your own composer or transcript. MentorUserMessage + MentorAttachment are the shape of a user turn, and IMentorOrchestrator.SendMessageAsync(text, attachments) is what consumes it — so a custom input control can replace ChatInput without touching the orchestration layer.

Working implementations of all three ship in the MentorAgentSample repository.

Why a separate package?

MentorAgent (server) depends on Microsoft.Agents.AI, ModelContextProtocol.AspNetCore, and other server-only packages that are not compatible with Blazor WebAssembly. MentorAgent.Blazor (WASM) cannot reference MentorAgent directly.

MentorAgent.Abstractions contains only WebAssembly-safe dependencies:

• Microsoft.AspNetCore.Components.Web
• Microsoft.AspNetCore.Components.Authorization
• Microsoft.Extensions.AI

Both MentorAgent and MentorAgent.Blazor reference MentorAgent.Abstractions — sharing interfaces, models, and UI components without cross-contaminating dependencies.

The practical rule: anything that must run in the browser goes here. If you are adding a type and it needs Microsoft.Agents.AI, an HttpContext, or the file system, it does not belong in this package — the WASM build will not fail at compile time, it will fail at runtime in the browser.

Requirements

• .NET 10.0 or later
• Microsoft.AspNetCore.Components.Web 10.0.3
• Microsoft.AspNetCore.Components.Authorization 10.0.3
• Microsoft.Extensions.AI 10.6.0

No AI provider, no server packages, no JavaScript dependencies beyond the browser's own Speech and File APIs.

Related Packages

License

MIT — the full text ships in the repository's LICENSE file.