Che cos'è MentorAgent: gli agenti AI delle tue applicazioni, sotto il tuo controllo

MentorAgent è una libreria open source per .NET 10 che mette un agente AI fra i tuoi sistemi e i tuoi utenti, e lo tiene dentro le tue regole. Da una parte l'agente usa quello che hai già: i metodi della tua applicazione .NET, i tool dei server MCP, altri agenti con A2A. Dall'altra l'agente e le sue azioni raggiungono persone e programmi ovunque siano: sul web, sul mobile, negli assistenti AI, in altri agenti, in script e servizi. In mezzo, MentorAgent applica le tue regole, divide il lavoro fra specialisti e team, sa su quale pagina è l'utente, tiene a bada i costi, mostra cosa è successo e usa il modello che scegli tu, in cloud o locale.

• I tuoi sistemi: metodi .NET segnati con [MentorAction], tool dei server MCP, agenti raggiunti con A2A.
• MentorAgent: sei capacità fra i due lati: governance, specialisti e team, pagine e skill, controllo dei costi, osservabilità, e il modello che scegli tu, in cloud o locale.
• Ovunque siano i tuoi utenti: app web e mobili, assistenti AI con MCP, altri agenti con A2A, script e servizi con HTTP e Server-Sent Events.

Un chatbot che risponde alle domande si costruisce facilmente. Un agente che agisce dentro un'applicazione aziendale no. Appena può modificare i dati, cambiano anche le domande:

• Cosa può usare: i tuoi servizi, tool MCP, altri agenti?
• Chi può chiedere cosa, e chi conferma le modifiche?
• Come divide il lavoro complesso, e come vedi cosa ha fatto?
• Quale modello risponde, e quanto costa?
• Dove lo incontrano gli utenti: sul web, sul mobile, in un assistente AI, in un altro sistema?

MentorAgent risponde a ognuna nel tuo codice, non nel prompt.

Il problema. I tuoi servizi sanno già leggere un ordine o fare un rimborso. Riscrivere quella logica per un framework di AI la duplica, e le due copie si allontanano.

Cosa fa MentorAgent. I tuoi servizi restano quelli. L'attributo [MentorAction] segna i metodi che l'agente può usare, e una chiamata registra la libreria, il modello e le classi da cercare:

using Microsoft.Extensions.AI;
using Novior.MentorAgent.Extensions;
using OpenAI;

var builder = WebApplication.CreateBuilder(args);

// Action classes come from the DI container
builder.Services.AddScoped<IOrderStore, SqlOrderStore>();
builder.Services.AddScoped<OrderService>();

builder.Services.AddMentorAgent(options =>
{
    options.AppName = "ShopFlow back office";
    options.ScanAssemblies = [typeof(Program).Assembly];
    options.ChatClient = new OpenAIClient(builder.Configuration["OpenAI:Key"]!)
        .GetChatClient("gpt-4o-mini")
        .AsIChatClient();
});

builder.Services.AddRazorComponents().AddInteractiveServerComponents();

Il risultato. Una sola fonte per la logica di business. L'agente chiama gli stessi metodi che chiamano i tuoi controller e le tue pagine.

Il problema. Spesso le capacità utili stanno fuori dalla tua applicazione: il servizio di tracciamento del corriere, l'agente del magazzino, un tool scritto in un altro linguaggio.

Cosa fa MentorAgent. Due opzioni li collegano. McpServers aggiunge i tool dei server MCP, anche solo quelli che permetti. RemoteAgents aggiunge gli agenti A2A come specialisti a cui il coordinatore passa il lavoro. MCP e A2A hanno SDK ufficiali per Python, JavaScript e TypeScript, Java, C#, Go e Rust, quindi quei tool e quegli agenti possono essere scritti in uno di questi linguaggi.

Il risultato. Il tuo agente lavora con il resto dei tuoi sistemi attraverso standard aperti, senza integrazioni fatte a mano. Un agente remoto segue le regole del suo host: i tuoi ruoli non valgono per lui, e ogni utente del tuo agente può raggiungerlo.

Il problema. "Per favore chiedi prima di rimborsare" in un prompt è un desiderio. Un modello può dimenticarlo, fraintenderlo o farsi convincere a ignorarlo.

Cosa fa MentorAgent. Le regole stanno sul metodo e si applicano ogni volta che viene chiamato un tool, fuori dal modello:

using Novior.MentorAgent.Attributes;

public class OrderService(IOrderStore store)
{
    [MentorAction(Description = "Returns the status of an order", ReadOnly = true)]
    public Task<string> GetOrderStatus(string orderNumber)
        => store.GetStatusAsync(orderNumber);

    [MentorAction(Description = "Refunds an order, fully or in part", RequiredRoles = ["CustomerCare"])]
    public async Task<string> RefundOrder(string orderNumber, decimal amount, string reason)
    {
        await store.RefundAsync(orderNumber, amount, reason);
        return $"Order {orderNumber}: refund of {amount:0.00} registered.";
    }
}

• Le azioni in sola lettura partono senza domande.
• Ogni altra azione chiede conferma per impostazione predefinita, perché RequireConfirmationForWrites è attivo finché non lo spegni.
• La conferma è concreta: mostra l'azione con i suoi argomenti veri, come il numero dell'ordine e l'importo.
• I ruoli si controllano sui claim dell'utente, prima della conferma e di nuovo dopo.
• Il controllo segue il tool, anche dentro gli agenti specialisti e i membri dei team.
• I tool che non puoi annotare, da server MCP o da skill, si controllano per nome con RequiresApproval.

Il risultato. Il modello propone; le tue regole decidono. Un buon inizio sono le azioni in sola lettura: servono dal primo giorno e non chiedono conferma. Le azioni che scrivono arrivano quando i ruoli sono pronti.

Approfondisci nella pagina sulla governance.

Il problema. Un agente con cinquanta tool si confonde, e alcune decisioni richiedono più di uno sguardo.

Cosa fa MentorAgent. Tre livelli, tutti dichiarati con attributi:

• Azioni, con [MentorAction].
• Specialisti, con [MentorAgent]: agenti con istruzioni e azioni loro, raggiunti con un flusso di handoff.
• Team, con [MentorTeam] e [TeamMember]: una group chat che approva o respinge una decisione. Se approva, il coordinatore può passare il lavoro a uno specialista.

Gli agenti si possono anche descrivere in YAML, con Novior.MentorAgent.Declarative. Tutto poggia sulle orchestrazioni handoff e group chat di Microsoft Agent Framework.

Il risultato. Agenti mirati, ognuno con pochi tool, e decisioni che passano da una revisione prima di modificare qualcosa.

Approfondisci nella pagina sui livelli degli agenti.

Il problema. Un assistente chiuso in un riquadro nell'angolo non sa che cosa sta guardando l'utente, e un prompt di sistema lungo, pieno di regole, costa token a ogni chiamata.

Cosa fa MentorAgent.

• [MentorPage] permette all'agente di portare l'utente su una pagina della tua app; con IMentorPageContext la pagina comunica cosa sta guardando l'utente e offre azioni sull'interfaccia.
• [MentorSkill] raccoglie conoscenza, come una politica dei resi, che il modello carica solo quando gli serve (con EnableSkills attivo).

Il risultato. Un agente che fa parte dell'applicazione, con un contesto più piccolo.

Il problema. Ogni chiamata al modello ha un prezzo, e un agente ne fa molte.

Cosa fa MentorAgent. Ogni leva è un'opzione, spenta in partenza; una dashboard mostra il risultato.

• Routing fra un modello piccolo e uno forte, con una tua regola, con un classificatore, per somiglianza semantica o a cascata (per le chiamate senza streaming).
• Filtro dei tool: al modello arrivano solo le azioni più pertinenti.
• Compattazione: prima di ogni chiamata le conversazioni lunghe si accorciano.
• Limiti d'uso per ogni utente autenticato.
• Una dashboard Blazor per uso e costi, con i prezzi dei modelli che configuri tu.

Il risultato. Costi visibili, e leve per tenerli bassi.

Il problema. Quando un agente chiama tool per conto degli utenti, devi vedere cosa è successo, accanto al resto della tua telemetria.

Cosa fa MentorAgent. Con EnableObservability, MentorAgent produce span OpenTelemetry per turni e chiamate ai tool, e contatori per turni, chiamate ai tool, errori e blocchi dei guardrail. Indipendentemente dall'opzione, nei log dei rifiuti per ruolo e delle chiamate MCP il chiamante compare con un'impronta, non con il nome. Gli eventi delle conferme sono a disposizione per registrare chi ha approvato cosa. La libreria non manda telemetria ai suoi autori.

Il risultato. L'agente compare nelle stesse tracce e nelle stesse dashboard del resto della tua applicazione.

Il problema. I modelli cambiano ogni pochi mesi, e alcuni dati non devono uscire dall'azienda.

Cosa fa MentorAgent. Il modello è un IChatClient di Microsoft.Extensions.AI: Azure OpenAI e OpenAI, oppure Ollama e altri server con un'API compatibile con OpenAI. Puoi anche passare un tuo AIAgent di Agent Framework, come un agente Foundry; in quel caso specialisti, team e agenti remoti non sono disponibili. MentorAgent non include un provider; aggiungi il pacchetto di quello che scegli, per esempio Microsoft.Extensions.AI.OpenAI. Con un modello locale, la conversazione e i dati letti dalle tue azioni restano dentro la tua rete, tranne quello che mandi a server MCP o agenti remoti.

Il risultato. Il modello diventa un pezzo sostituibile, in cloud o sulle tue macchine, senza toccare le azioni.

Il problema. Gli utenti sono nel browser, in un'app mobile, in un assistente AI, oppure sono altri sistemi. Un assistente per ogni canale moltiplica il lavoro e le regole.

Cosa fa MentorAgent. Le tue azioni e le loro regole sono le stesse su ogni canale:

• Web: Blazor Server e Blazor WebAssembly o Auto hanno un <ChatWidget /> pronto. React, Angular, Vue o JavaScript senza framework si collegano all'hub SignalR con @microsoft/signalr.
• Mobile: un'app .NET MAUI su Android o Windows usa lo stesso widget; le app native usano i client SignalR ufficiali per Java su Android e per Swift su iOS.
• Assistenti AI: come server MCP, le tue azioni diventano tool per i client MCP, come gli assistenti AI dell'IDE o del desktop.
• Altri agenti: come server A2A, il tuo agente intero diventa un interlocutore che agenti scritti in altri linguaggi possono chiamare.
• Script e servizi: dove non c'è un client SignalR adatto, come uno script Python, una shell o un servizio in un altro linguaggio, i Server-Sent Events funzionano con ogni client HTTP.

Sul server bastano poche chiamate:

using Novior.MentorAgent.Extensions;
using Novior.MentorAgent.Server.Extensions;

// In AddMentorAgent: options.McpServerEnabled = true; options.A2AServerEnabled = true;
builder.Services.AddMentorAgentServer();   // hub, SSE, MCP and A2A services

var app = builder.Build();

app.MapMentorAgentServer(configureTransports: endpoints => endpoints.RequireAuthorization());
app.MapMentorAgentMcp(configure: endpoints => endpoints.RequireAuthorization());
app.MapMentorAgentA2A(configure: endpoints => endpoints.RequireAuthorization());

Le regole seguono il canale. Un client MCP non ha nessuno che possa cliccare "Conferma", quindi MCP pubblica solo le azioni che non chiedono conferma. Quelle protette da ruoli compaiono solo se identifichi il chiamante con McpCallerPrincipal e il chiamante ha il ruolo. La card A2A le lascia fuori entrambe.

Il risultato. Un solo agente da costruire e governare, ovunque siano i tuoi utenti.

Approfondisci nella pagina sui canali.

MentorAgent è una libreria .NET 10 che gira dentro la tua applicazione, un host ASP.NET Core o un'app .NET MAUI, quindi va dove va quell'applicazione: Windows o Linux, un container, il cloud o i tuoi server. Il widget non carica niente da server di terzi. Il nucleo è .NET; tutto quello che c'è intorno, dai front end ai tool e agli agenti con cui parla, può essere scritto in altri linguaggi.

Sistemi .NET esistenti che diventano pronti per l'AI. Una volta su .NET 10, un gestionale, un back office o un portale clienti contiene già anni di regole di business. Basta segnare i metodi giusti dei servizi per dargli un agente, senza riscriverlo e senza una seconda copia della logica.

Copiloti interni per gli operatori. Chi lavora in assistenza clienti, vendite, logistica o amministrazione chiede in linguaggio naturale, e l'agente trova l'ordine, il contratto o la pratica e prepara il passo successivo. Le azioni in sola lettura rispondono subito; quelle che modificano i dati aspettano la conferma dell'operatore.

Assistenti per i clienti finali. In un negozio online, nell'area clienti di un'azienda di servizi o in un portale di prenotazioni, i clienti controllano lo stato di un ordine, di una richiesta o di una consegna, e avviano operazioni semplici. Si vedono solo le azioni che scegli tu, e i ruoli decidono chi può fare cosa.

Automazioni di back office con l'approvazione di una persona. Rimborsi, note di credito, cambi di indirizzo, correzioni di dati: l'agente prepara l'operazione con i suoi argomenti veri, e una persona la approva. Un team di agenti può rivedere la richiesta prima, così l'operatore vede una decisione già controllata.

Agenti che lavorano fra aziende diverse. L'agente di un negozio chiede all'agente del corriere dov'è un pacco; l'agente di un fornitore controlla le scorte di un cliente. Con A2A ogni azienda tiene il suo agente, le sue regole e i suoi dati, e gli agenti si parlano in linguaggio naturale. All'altra parte sono aperte solo le azioni che non chiedono conferma, e i ruoli valgono solo per i chiamanti che autentichi.

Strumenti aziendali per i client AI dei dipendenti. Molti dipendenti usano già assistenti AI nell'editor o sul desktop. Con MCP, le azioni dell'azienda diventano tool per quegli assistenti, ma solo quelle che non chiedono conferma, e quelle protette da ruoli solo per i chiamanti che identifichi.

Aziende che vendono software. Un team che vende un prodotto .NET può aggiungerci un agente una volta sola e offrirlo a ogni cliente, ogni installazione con il modello del cliente, in cloud o sui propri server.

Settori regolati. Finanza, assicurazioni, sanità e pubblica amministrazione devono sapere chi ha fatto cosa e perché. Ruoli e conferme sono applicati nel codice, con EnableObservability ogni chiamata a un tool diventa uno span OpenTelemetry, ogni decisione su un'azione, con chi l'ha confermata, può alimentare il tuo registro, e un modello locale tiene i dati in casa.

App mobili e sul campo. Lo stesso agente in un'app .NET MAUI su Android o Windows, oppure in un'app nativa con i client SignalR per Java e Swift.

Quando un agente può usare i sistemi che un'azienda ha già, con le regole dell'azienda, e raggiungere i suoi utenti ovunque siano, l'applicazione guadagna una nuova interfaccia e la logica di business arriva più lontano:

• Ogni metodo di servizio è a un attributo di distanza dal diventare una capacità dell'agente, con le stesse regole per chiunque lo chiami.
• Lo stesso controllo su ogni canale: il widget, un'app mobile, uno script, un assistente dell'IDE o l'agente di un'altra azienda: i ruoli valgono per ogni chiamante, e dove nessuno può confermare le azioni che chiedono conferma non vengono offerte.
• Il modello diventa un pezzo sostituibile: un modello in cloud oggi, uno locale domani, uno piccolo per i turni facili e uno forte per quelli difficili, senza toccare le azioni.
• L'adozione cresce un passo alla volta: prima le azioni in sola lettura, poi le scritture con conferma, poi specialisti e team per le decisioni che ne hanno bisogno.
• I sistemi di un'azienda diventano raggiungibili dagli agenti dei suoi partner, con standard aperti e alle sue condizioni.

• I permessi sui dati: MentorAgent controlla i ruoli. Quali record un utente può vedere o modificare lo decide il tuo codice: nei tuoi metodi, oppure in un IMentorActionPolicy che MentorAgent interroga prima di ogni chiamata.
• ReadOnly si basa sulla fiducia: se un metodo segnato in sola lettura scrive, niente lo ferma.
• Solo [MentorAction] ha regole: un metodo esposto con un semplice [Description] non ha ruoli e non chiede conferma, a meno che RequiresApproval non lo nomini. Un avviso li elenca la prima volta che MentorAgent legge le azioni.
• Il registro: ogni decisione su un'azione, compreso chi l'ha confermata, arriva a un IMentorActionObserver da cui puoi registrarla. La libreria non tiene un registro suo.

MentorAgent è la base. Il progetto sta lavorando a una console per vedere, provare, configurare e governare gli agenti di ogni applicazione, e a un'installazione pronta che fa girare tutto sui tuoi server, modello locale compreso. Li presenteremo qui quando saranno pronti.

Segui gli aggiornamenti: il feed RSS del blog porta ogni annuncio nel tuo lettore di feed, e su GitHub ↗ (sito esterno) Watch → Custom → Releases ti manda una notifica a ogni versione nuova.

Scritto con l'aiuto dell'AI; codice e fatti verificati dal team di MentorAgent.