MentorAgent.Abstractions 1.0.0-preview.4

This is a prerelease version of MentorAgent.Abstractions.

dotnet add package MentorAgent.Abstractions --version 1.0.0-preview.4

NuGet\Install-Package MentorAgent.Abstractions -Version 1.0.0-preview.4

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="MentorAgent.Abstractions" Version="1.0.0-preview.4" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="MentorAgent.Abstractions" Version="1.0.0-preview.4" />
                    

                            Directory.Packages.props

<PackageReference Include="MentorAgent.Abstractions" />
                    

                            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 MentorAgent.Abstractions --version 1.0.0-preview.4

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: MentorAgent.Abstractions, 1.0.0-preview.4"

#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 MentorAgent.Abstractions@1.0.0-preview.4

#: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=MentorAgent.Abstractions&version=1.0.0-preview.4&prerelease
                    

                            Install as a Cake Addin

#tool nuget:?package=MentorAgent.Abstractions&version=1.0.0-preview.4&prerelease
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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.

Package Family

Package	Install when
MentorAgent	Blazor Server app
MentorAgent.Server	Web API / headless backend, or Blazor Auto server-side project
MentorAgent.Blazor	Blazor WASM / Blazor Auto client project
MentorAgent.Abstractions ← you are here	Never directly — it arrives with any of the above

What's included

Interfaces

Interface	Description
`IMentorOrchestrator`	AI orchestrator contract — implemented by `MentorOrchestrator` (server) and `WasmMentorOrchestrator` (WASM)
`IMentorStateService`	Thread-safe event bus between the AI layer and the UI layer
`IMentorPageContext`	Page context and UI actions registry
`IMentorAgent`	Marker interface for Level 2 specialized agents
`IMentorTeam`	Marker interface for Level 3 collaborative teams
`IMentorStructured`	Typed generation — `GenerateAsync<T>(input, instructions)` returns a deserialized `T`, with the JSON schema derived from your type
`IMentorMetrics`	Read-side of the token/cost counters — `GetSnapshot()` feeds `MentorDashboard`
`IMentorMetricsStore`	Optional persistence/aggregation for those metrics. Implement it to survive restarts or to read an external aggregate (Prometheus, Azure Monitor) instead of the in-RAM snapshot

Models

Type	Description
`ConfirmationRequest`	HITL confirmation request shown in `ConfirmationBanner`
`MentorRagResult`	A single RAG search result with content, URL, title, and score
`MentorWidgetOptions`	UI-only options for `ChatWidget` (theme, position, language, etc.)
`UIActionRegistration`	Handler registration for a page-level UI action
`PageContextSnapshot`	Serializable page context sent from WASM client to server hub
`UIActionInfo`	UI action descriptor in a `PageContextSnapshot`
`AgentDisplayInfo`	Remote agent display info for the A2A detail badge
`MentorAttachment`	One image on a user turn — `DataBase64` (upload/paste) or `Url` (remote), mapped to the Agent Framework's `DataContent` / `UriContent`
`MentorUserMessage`	A user turn as text + attachments; an image-only turn (empty text) is valid
`MentorMetricsSnapshot`	Point-in-time totals, per-model breakdown, hourly series, top actions and cost — the payload of `GET /mentor/admin/metrics`
`MentorModelUsage`	One model's slice of that snapshot (tokens, calls, latency, cost)
`ModelPrice`	`record ModelPrice(decimal InputPer1M, decimal OutputPer1M)` — you supply prices; the library ships no price table, because they change and a stale one lies

Enums

Enum	Values
`MentorLanguage`	English, Italian, French, German, Spanish, Portuguese, Dutch, Polish, Japanese, Chinese
`MentorTheme`	Default, Dark, Minimal, Custom
`ChatPosition`	BottomRight, BottomLeft, TopRight, TopLeft, SideRight, SideLeft
`MentorshipLevel`	Minimal, Standard, Proactive
`MentorHostedTools`	`[Flags]` — None, WebSearch, CodeInterpreter, FileSearch, ImageGeneration, HostedMcp. The set the model provider may run on its own infrastructure; also what the server publishes on connect so a client badge never drifts from the server
`MentorModelKind`	Cheap, Strong, Embedding — how a model's usage is attributed in the metrics snapshot

UI Components (Razor)

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

Component	Description
`ChatWidget`	Main floating chat widget — injects CSS/JS automatically
`MessageBubble`	A chat message: Markdown rendering, citation chips and any images the message carries. XSS-safe by construction — every piece of model text is HTML-encoded before a tag is emitted, so the model supplies data, never markup
`ChatInput`	Text input with voice recognition and the image composer (upload, paste, drag & drop, remote URL)
`MentorDashboard`	Admin token & cost dashboard — per-model breakdown, temporal SVG charts, cost table. Presentational: hand it a `MentorMetricsSnapshot`, from DI in Blazor Server or from `GET /mentor/admin/metrics` in WASM. Never rendered by `ChatWidget` — keep it off end-user pages
`ConfirmationBanner`	HITL approval dialog
`WelcomePanel`	Empty-state welcome screen with suggestion chips
`TypingIndicator`	Animated typing dots while AI processes
`RagSourcePanel`	Citation chips below AI responses
`McpStatusBadge` / `McpDetailBar`	MCP server connection status
`A2AStatusBadge` / `A2ADetailBar`	A2A remote agent status

Core

Type	Description
`MentorLocalizer`	In-memory i18n for 10 languages — no `.resx` files, no external dependencies

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 *@
@inject IMentorMetrics Metrics
<MentorDashboard Snapshot="Metrics.GetSnapshot()" />

@* 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.

Package	Purpose
MentorAgent	Blazor Server — full AI assistant
MentorAgent.Server	Any ASP.NET Core app — headless AI backend
MentorAgent.Blazor	Blazor WASM — SignalR client

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.

net10.0
- Microsoft.AspNetCore.Components.Authorization (>= 10.0.3)
- Microsoft.AspNetCore.Components.Web (>= 10.0.3)
- Microsoft.Extensions.AI (>= 10.6.0)

NuGet packages (2)

Showing the top 2 NuGet packages that depend on MentorAgent.Abstractions:

Package	Downloads
MentorAgent A Blazor Razor Class Library that adds an AI-powered floating chat assistant to any Blazor application, built on Microsoft Agent Framework. Supports multi-level agent orchestration (tools, handoff, group chat), page navigation, UI actions, contextual memory, streaming, voice, and security — all with zero boilerplate.	273
MentorAgent.Blazor Blazor WebAssembly client for MentorAgent. Install 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.	250

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.0-preview.4	69	8/4/2026
1.0.0-preview.3	67	7/24/2026
1.0.0-preview.2	80	6/22/2026
1.0.0-preview	83	6/22/2026

1.0.0-preview.4

=== Provider-hosted tools ===================================================
- NEW — ChatWidget shows an amber pill in the header listing the provider-hosted tools the model may use (web search, code interpreter, file search, image generation, remote MCP), with a detail bar making clear they run on the AI provider and not in the application. Driven by MentorWidgetOptions.ShowHostedToolsStatus + HostedTools; new shared enum MentorHostedTools. Localized in all 10 languages.
- NEW — IMentorStateService.OnHostedToolsDeclared + NotifyHostedToolsDeclared: a server can publish the set it actually enabled and ChatWidget prefers it over the local option, so the badge no longer drifts from the server. Unlike the MCP badge this stays a one-shot declaration, not a live connection state.
- Fix — a citation with no URL (a document matched inside a provider vector store, a file produced by the code interpreter) rendered as a link to "#", which navigated to the top of the host page and looked like a broken download. The chip now omits href entirely and is styled as non-interactive.
- Fix — the hosted-tools (amber) and A2A (indigo) chips hard-coded pale dark-theme text, so on the Minimal (light) theme the tool names were nearly invisible against their own tint. They now use --bm-hosted-text / --bm-a2a-text CSS variables, overridden per theme.

=== Multimodal image input =================================================
- NEW — ChatInput gained an image composer: 📎 file upload (multi-select), Ctrl+V clipboard paste, drag & drop (files, or an image dragged from another page) and 🔗 remote URL, with removable thumbnails; MessageBubble renders the images carried by the message's own content parts. Enabled by MentorWidgetOptions.EnableImageInput (+ MaxImageBytes / MaxImagesPerMessage / AllowedImageTypes, which mirror the server options and drive client-side pre-checks only). New shared contracts: MentorAttachment (DataBase64 or Url → AF DataContent/UriContent) and MentorUserMessage. Breaking (source): ChatInput.OnSend is now EventCallback<MentorUserMessage> instead of EventCallback<string>. Image bytes are pulled through IJSStreamReference, never one large interop payload, so Blazor Server circuits are unaffected by HubOptions.MaximumReceiveMessageSize.
- Fix — Ctrl+V did nothing unless the caret was already inside the text box. A paste event is delivered to whatever has focus, and the handler was bound to the composer, so pasting a screenshot right after opening the widget was silently dropped. Paste is now handled while the widget is open regardless of focus (a paste aimed at another input of the host app is never hijacked), and drag & drop is accepted anywhere in the chat panel, not only on the composer.
- Improved — an image larger than MaxImageBytes is now downscaled in the browser (max 2000 px, original MIME preserved so the server allow-list still applies) instead of being refused; screenshots are routinely 5-10 MB. Animated GIFs are never re-encoded. Dropping an image dragged from another page now also works when the browser hands over a blob:/data: URL instead of a file (it used to be ignored silently).

=== Robustness =============================================================
- Fix — ChatWidget sends the turn fire-and-forget, so a failure in the send itself (for example the transport rejecting the payload) left the chat sitting there with no reply, no error and no busy indicator. A faulted send now surfaces as an error bubble and clears the busy state.

=== Human-in-the-loop approval ==============================================
- Note — the approval protocol is unchanged. ConfirmationRequest, the ConfirmationRequired event and ConfirmAsync/Cancel are identical whether the server runs MentorAgent's own approval flow or the Agent Framework's native one, so components built against them keep working with either mode.