AI Under Your Control · Parte 1
Da Microsoft Agent Framework a un agente AI governato nella tua app .NET
Agent Framework fa girare l'agente. MentorAgent gli mette intorno ruoli, conferma con human-in-the-loop, il registro di ogni decisione e il controllo dei costi, sui metodi della tua app. Lo stesso rimborso costruito nei due modi, e dove andiamo dopo.

In questo articolo
Hai un'applicazione .NET con utenti, ruoli e servizi. Ora vuoi al suo interno un assistente che faccia lavoro vero: rimborsa un ordine, cambia un indirizzo, chiude un ticket. Il modello è la parte facile. La parte difficile è che nessuno perda il controllo mentre l'assistente lavora. Chiede la persona giusta. Conferma la persona giusta. L'azione parte solo per chi è autorizzato a farla. E dopo si può dire chi ha fatto cosa.
Microsoft Agent Framework è un'ottima base per tutto questo, ed è la base su cui è costruito MentorAgent: MentorAgent 1.3.0 gira su Agent Framework 1.27.0. Il framework dà agenti, tool, workflow, middleware, provider dei modelli, approvazione dei tool (tool approval, human in the loop) e i protocolli per parlare con altri agenti, in .NET, Python e Go. Lascia a te tutto quello che fa di un agente una parte della tua applicazione, e non una demo accanto: i tuoi utenti, i tuoi ruoli (roles), le tue schermate e i tuoi registri.
Questo articolo misura quella distanza con un solo esempio, un rimborso, costruito due volte. Prima con Agent Framework da solo, con il codice che serve davvero prima di metterlo davanti al servizio clienti. Poi con MentorAgent. Dopo, cosa dà questa differenza a un team che deve rispondere del risultato, e dove porteremo MentorAgent.
Lo stesso rimborso, costruito due volte
Sezione “Lo stesso rimborso, costruito due volte”Le regole del rimborso si dicono in poche righe:
- Solo gli utenti con il ruolo
CustomerCarepossono rimborsare. - L'assistente non rimborsa mai da solo. Una persona dà una conferma (tool approval, human-in-the-loop) e vede l'ordine vero e l'importo vero.
- Il ruolo si ricontrolla quando la persona conferma, perché nel frattempo può essere cambiato.
- Ogni passo viene registrato: chi ha chiesto, chi ha confermato, cosa è successo.
- Altri agenti possono leggere lo stato di un ordine con MCP, se chi li usa ha il ruolo. Su MCP nessuno può premere "Conferma", quindi lì il rimborso non si offre.
Con Agent Framework da solo: ruoli, human in the loop e un registro
Sezione “Con Agent Framework da solo: ruoli, human in the loop e un registro”I ruoli sono la prima domanda che i team fanno su Microsoft Agent Framework. Il framework fa girare l'agente e il flusso di approvazione; quali dei tuoi utenti possono far partire un tool è una regola che scrivi tu. I pezzi per farlo ci sono. Un tool avvolto in ApprovalRequiredAIFunction ferma l'esecuzione e ti consegna una richiesta, invece di chiamare il metodo. Il middleware delle chiamate alle funzioni (function calling middleware) ti fa vedere ogni chiamata. Una sessione tiene la conversazione. Ecco cosa ci costruisci, seguendo le pagine sull'approvazione dei tool (sito esterno) e sul middleware (sito esterno).
Prima il tool. Il metodo fa il lavoro, e l'involucro fa fermare l'agente per chiedere prima che parta:
using Microsoft.Extensions.AI;
public sealed class RefundTools(IOrderStore store)
{
public AIFunction Create() => new ApprovalRequiredAIFunction(
AIFunctionFactory.Create(RefundOrder, "RefundOrder", "Refunds an order, fully or in part"));
private async Task<string> RefundOrder(string orderNumber, decimal amount)
{
await store.RefundAsync(orderNumber, amount);
return $"Order {orderNumber}: refund of {amount:0.00} registered.";
}
}Poi il ruolo. Una tabella dice quale ruolo serve a ogni tool, e il middleware delle chiamate alle funzioni lo controlla. Il middleware gira quando il tool sta per partire, cioè dopo che la persona ha confermato, quindi fa anche da secondo controllo. La tabella è chiusa per default: un tool che non c'è viene rifiutato.
using System.Security.Claims;
using Microsoft.Agents.AI;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.AI;
public static class ToolRoles
{
private static readonly Dictionary<string, string> Required = new() { ["RefundOrder"] = "CustomerCare" };
// A tool that is not in the table is refused: the default is closed
public static bool MayCall(ClaimsPrincipal? user, string tool) =>
Required.TryGetValue(tool, out var role) && user?.IsInRole(role) == true;
}
public sealed class RefundGuard(IHttpContextAccessor http, DecisionLog log)
{
// Function calling middleware: it runs when the tool is about to run, so after the user has confirmed
public async ValueTask<object?> CheckRoleAsync(
AIAgent agent,
FunctionInvocationContext context,
Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
CancellationToken cancellationToken)
{
var user = http.HttpContext?.User;
var tool = context.Function.Name;
if (!ToolRoles.MayCall(user, tool))
{
log.Record(new Decision("blocked", tool, user?.Identity?.Name));
return "Refused: the signed-in user may not use this action.";
}
var result = await next(context, cancellationToken);
log.Record(new Decision("executed", tool, user?.Identity?.Name));
return result;
}
}Ora l'assistente, la parte con cui parla il front end. Costruisce l'agente con il tool e il middleware, esegue il messaggio dell'utente sulla sessione e trasforma una richiesta di approvazione in qualcosa che il front end può mostrare: il tool e i suoi argomenti veri, presi dalla FunctionCallContent. La domanda si fa solo se l'utente può usare l'azione. Se non può, non si chiede niente a nessuno, e Agent Framework rifiuta la richiesta rimasta senza risposta all'esecuzione successiva.
Una parte della protezione è già nel framework. Agent Framework 1.27.0 registra ogni richiesta di approvazione nella sessione, accetta una risposta solo se corrisponde a una di quelle, e una volta sola, esegue la chiamata con gli argomenti che erano stati mostrati e rifiuta le richieste rimaste senza risposta. Quello che non può sapere è chi sta rispondendo. Per questo l'assistente accetta una risposta solo dal proprietario della conversazione, e rifiuta quella per una richiesta che non è in attesa: così il registro non scrive mai "approvato" per una risposta che il framework ignorerebbe.
using System.Security.Claims;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
public sealed class RefundAssistant(
IChatClient chatClient, RefundTools tools, RefundGuard guard, ConversationStore conversations, DecisionLog log)
{
private readonly AIAgent agent = chatClient
.AsAIAgent(instructions: "You help the customer care team with refunds.", tools: [tools.Create()])
.AsBuilder()
.Use(guard.CheckRoleAsync)
.Build();
public async Task<ChatReply> AskAsync(ClaimsPrincipal user, string? conversationId, string text, CancellationToken ct)
{
var id = conversationId ?? Guid.NewGuid().ToString("N");
var conversation = conversations.TryGetValue(id, out var existing)
? existing
: conversations[id] = new Conversation(user.Identity!.Name!, await agent.CreateSessionAsync(ct));
EnsureOwner(conversation, user);
conversation.Pending = null;
var response = await agent.RunAsync(text, conversation.Session, cancellationToken: ct);
return Reply(id, conversation, user, response);
}
public async Task<ChatReply> AnswerAsync(
ClaimsPrincipal user, string conversationId, string requestId, bool approved, CancellationToken ct)
{
if (!conversations.TryGetValue(conversationId, out var conversation)) throw new KeyNotFoundException();
EnsureOwner(conversation, user);
// Agent Framework would ignore a stale answer; refusing it here keeps the record from saying "approved"
if (conversation.Pending is not { } request || request.RequestId != requestId)
throw new InvalidOperationException("There is no such request waiting for an answer.");
conversation.Pending = null;
var call = (FunctionCallContent)request.ToolCall;
log.Record(new Decision(approved ? "approved" : "rejected", call.Name, user.Identity?.Name, conversationId));
var answer = new ChatMessage(ChatRole.User, [request.CreateResponse(approved)]);
var response = await agent.RunAsync(answer, conversation.Session, cancellationToken: ct);
return Reply(conversationId, conversation, user, response);
}
private ChatReply Reply(string id, Conversation conversation, ClaimsPrincipal user, AgentResponse response)
{
var request = response.Messages.SelectMany(m => m.Contents).OfType<ToolApprovalRequestContent>().FirstOrDefault();
if (request is null) return new ChatReply(id, response.Text, null);
var call = (FunctionCallContent)request.ToolCall;
if (!ToolRoles.MayCall(user, call.Name))
{
// Nobody is asked. The request stays unanswered and the next run rejects it
log.Record(new Decision("not offered", call.Name, user.Identity?.Name, id));
return new ChatReply(id, "You may not use this action.", null);
}
conversation.Pending = request;
log.Record(new Decision("asked", call.Name, user.Identity?.Name, id));
return new ChatReply(id, null, new PendingApproval(request.RequestId, call.Name, call.Arguments));
}
private static void EnsureOwner(Conversation conversation, ClaimsPrincipal user)
{
if (conversation.Owner != user.Identity?.Name) throw new UnauthorizedAccessException();
}
}Questo è il cuore. Intorno ci sono altri cinque pezzi, ognuno semplice, ognuno da scrivere:
- Il registro (16 righe): chi ha chiesto, chi ha confermato, cosa è partito e cosa è stato bloccato. In produzione, una tabella da interrogare.
- Le conversazioni (12 righe): la sessione, il suo proprietario e la richiesta in attesa, tenuti fra le due richieste HTTP di una conferma.
- Due endpoint (25 righe): uno per il messaggio, uno per la risposta della persona, con gli errori tradotti in HTTP.
- Il server MCP (15 righe), con l'SDK C# ufficiale,
ModelContextProtocol: un client MCP non ha nessuno che confermi, quindi si pubblica solo la lettura dello stato dell'ordine, e il tool controlla da solo il ruolo di chi chiama. - La registrazione in
Program.cs(16 righe) che lega tutto.
La versione completa, che abbiamo compilato e provato, è di 180 righe di C# in otto file, contando ogni riga che non è vuota né di commento, graffe e righe using comprese. I pacchetti di hosting di Agent Framework, ancora in prerelease per .NET, possono prendersi una parte di questo lavoro: un archivio delle sessioni isolato in base al claim dell'utente che ha fatto l'accesso può sostituire le conversazioni e il controllo del proprietario, e se il tuo front end parla AG-UI, MapAGUIServer può sostituire i due endpoint. La tabella dei ruoli, il middleware, la scelta di chi interpellare e il registro restano tuoi in ogni caso.
Ogni nuova azione da proteggere, un cambio di indirizzo o un annullamento, vuol dire un tool nuovo, una riga nuova nella tabella dei ruoli e, se serve ad altri agenti, un nuovo tool MCP con il suo controllo del ruolo. È buon codice, ed è codice tuo da mantenere.
Con MentorAgent: le regole sul metodo
Sezione “Con MentorAgent: le regole sul metodo”MentorAgent parte dai metodi che hai già. Questo è tutto il rimborso, più la lettura per gli altri agenti:
using Novior.MentorAgent.Attributes;
public class OrderService(IOrderStore store)
{
[MentorAction(Description = "Refunds an order, fully or in part", RequiredRoles = ["CustomerCare"])]
public async Task<string> RefundOrder(string orderNumber, decimal amount)
{
await store.RefundAsync(orderNumber, amount);
return $"Order {orderNumber}: refund of {amount:0.00} registered.";
}
[MentorAction(Description = "Returns the status of an order", ReadOnly = true, RequiredRoles = ["CustomerCare"])]
public Task<string> GetOrderStatus(string orderNumber) => store.GetStatusAsync(orderNumber);
}L'attributo dice a cosa serve l'azione e chi la può usare. RequiredRoles si controlla con ClaimsPrincipal.IsInRole sull'utente che ha fatto l'accesso: chi non ha il ruolo non si vede mai offrire l'azione, e il ruolo si ricontrolla dopo la conferma. Un [MentorAction] chiede conferma, a meno che non dichiari ReadOnly = true, come la lettura, o RequiresConfirmation = false. La domanda che vede l'utente nasce dalla chiamata vera: la descrizione dell'azione, poi gli argomenti.
La registrazione dice dove sono le azioni, quale modello usare e quali canali aprire. Qui la stessa app serve l'hub SignalR e i Server-Sent Events per il tuo front end, e un endpoint MCP:
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.AI;
using Novior.MentorAgent.Extensions;
using Novior.MentorAgent.Options;
using Novior.MentorAgent.Server.Extensions;
using OpenAI;
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();
options.McpServerEnabled = true;
});
// On MCP, the signed-in caller of the request decides which actions with roles are published
builder.Services.AddOptions<MentorOptions>()
.Configure<IHttpContextAccessor>((options, http) => options.McpCallerPrincipal = () => http.HttpContext?.User);
builder.Services.AddMentorAgentServer();
builder.Services.AddMentorActionObserver<DecisionObserver>();
var app = builder.Build();
app.MapMentorAgentServer(configureTransports: endpoints => endpoints.RequireAuthorization());
app.MapMentorAgentMcp(configure: endpoints => endpoints.RequireAuthorization());Su MCP il rimborso non viene pubblicato: richiede una conferma, e un client MCP non ha nessuno che prema "Conferma". La lettura sì, ma solo per chi ha il ruolo. Sull'hub, la risposta a una conferma si accetta solo dall'utente che ha aperto la connessione; con i Server-Sent Events la chiave è l'id dell'azione, quindi gli endpoint vanno tenuti dietro autenticazione, come qui. Nessuna di queste regole l'hai scritta tu: vengono dall'attributo e dal canale.
Il registro delle decisioni è una classe che la libreria chiama per ogni decisione del suo controllo, con chi ha chiesto, chi ha confermato e l'esito:
using Microsoft.Extensions.Logging;
using Novior.MentorAgent.Abstractions.Interfaces;
using Novior.MentorAgent.Abstractions.Models;
public sealed class DecisionObserver(ILogger<DecisionObserver> logger) : IMentorActionObserver
{
public ValueTask OnDecisionAsync(MentorActionDecision decision, CancellationToken cancellationToken)
{
logger.LogInformation("{Outcome} {Tool}: asked by {User}, confirmed by {ConfirmedBy}",
decision.Outcome, decision.ToolName, decision.User?.Identity?.Name, decision.ConfirmedBy?.Identity?.Name);
return ValueTask.CompletedTask;
}
}Sono 180 righe contro 48, contate nello stesso modo. La finestra che mostra la domanda non è in nessuno dei due conteggi: in Blazor e in MAUI è il widget di MentorAgent, quello dell'immagine, mentre un front end React o Angular la disegna da sé in tutti e due i casi. I numeri non sono il punto. Il punto sono i posti. Con Agent Framework da solo, le regole di un rimborso sono sparse fra un tool, una tabella dei ruoli, un middleware, un assistente, due endpoint e una classe MCP. Con MentorAgent stanno sul metodo, nel codice che fa il lavoro, e lo stesso metodo serve la chat e MCP.
Agent Framework da solo è la scelta giusta se lavori in Python o in Go, se disegni tu il workflow a grafo o costruisci a mano l'orchestrazione, o se costruisci agenti senza un'applicazione intorno. MentorAgent è per il caso di questo articolo: un agente dentro un'app .NET che ha degli utenti.
Governance degli agenti AI in .NET: cosa ottieni
Sezione “Governance degli agenti AI in .NET: cosa ottieni”Governance (AI agent governance) è una parola grossa per una richiesta semplice: l'assistente deve rispettare le stesse regole delle persone che lo usano, e devi poterlo dimostrare. In MentorAgent questa richiesta poggia su tre cose.
Le regole stanno sul metodo
Sezione “Le regole stanno sul metodo”La regola su chi può rimborsare, e se una persona deve confermare, non sta in un prompt che un modello può seguire o no, e non è sparsa fra middleware ed endpoint che qualcuno deve ricordarsi di aggiornare. Sta sul metodo, nel codice che fa il lavoro. Leggi il metodo e leggi le sue regole. Rivedi il metodo e rivedi il controllo. Se il metodo viene rinominato o spostato, le regole vanno con lui.
Anche il default è sicuro. Un'azione che modifica dati chiede conferma, a meno che non dichiari altro, e un metodo esposto con la sola descrizione, che non ha nessuna regola, riceve un avviso nel log se non è dichiarato di sola lettura, così il buco si vede.
L'identità della tua app decide chi può fare cosa
Sezione “L'identità della tua app decide chi può fare cosa”MentorAgent non inventa un secondo elenco di utenti. Legge l'identità che la tua app ha già, il ClaimsPrincipal di chi ha fatto l'accesso, e usa i ruoli che porta con sé. La stessa regola vale così su ogni canale. Nel widget di chat, chi non ha il ruolo non vede l'azione. Su MCP, le azioni che richiedono un ruolo si offrono solo ai chiamanti che il server sa identificare, e quelle che richiedono una conferma non si offrono affatto. Per gli altri agenti che chiamano il tuo con A2A vale lo stesso: dove nessuno può rispondere a una conferma, l'azione non è in offerta.
Anche le tue regole di business entrano nello stesso controllo. Una policy può consentire, far confermare o fermare una chiamata in base ai tuoi dati: questo cliente, questo importo. E le decisioni finiscono nel tuo registro, tutta la sequenza, con chi ha chiesto e chi ha confermato.
Costi e modelli restano sotto il tuo controllo
Sezione “Costi e modelli restano sotto il tuo controllo”Un agente che funziona bene in una demo può costare molto in produzione, perché ogni messaggio porta con sé tutta la conversazione e ogni definizione dei tool. MentorAgent ha le leve per questo, e ognuna resta spenta finché non la accendi. Può mandare solo le domande difficili a un modello più forte. Può mandare al modello solo i tool adatti al messaggio. Può compattare le conversazioni lunghe. Può limitare le richieste di ogni utente. E la dashboard di token e costi è un componente che metti in una pagina di amministrazione. Il provider del modello lo scegli tu, e la scelta resta tua.
Agent Framework in Blazor, in MAUI e in qualunque front end
Sezione “Agent Framework in Blazor, in MAUI e in qualunque front end”Per Blazor, <ChatWidget /> funziona in Blazor Server, WebAssembly e Auto, e nelle app .NET MAUI su Android e Windows, con la finestra di conferma già dentro. React, Angular, Vue e altri client si collegano con SignalR o con i Server-Sent Events, e rimandano le conferme con POST /mentor/approve. Dietro, gli specialisti che dichiari e i team di agenti che discutono una richiesta prima di rispondere girano come workflow di handoff e di group chat di Agent Framework, e i loro tool mantengono gli stessi controlli di ruolo e di conferma. Se i tuoi workflow si aspettano il flusso di approvazione del framework, HitlMode = Native avvolge i tool del coordinatore in ApprovalRequiredAIFunction, e l'utente vede la stessa conferma.
Dove va MentorAgent
Sezione “Dove va MentorAgent”Agent Framework continua a crescere, e MentorAgent lo segue: oggi sulla 1.27.0, con MentorAgent 1.3.0, aggiungendo lo strato applicativo che ogni passo del framework rende più utile. Quello che segue è lavoro deciso, e va in una sola direzione: l'agente diventa una parte nativa della tua applicazione, non un componente attaccato.
Più modi di dare le azioni all'agente. L'attributo è il modo più semplice, e non sarà l'unico. Un team con un'architettura pulita deve poter descrivere le azioni di un agente in altri modi, per esempio con una registrazione fluente, con i comandi e le query che l'applicazione ha già, e con le API che già espone. Così un agente si aggiunge anche a un'app che non è nata per averne uno, senza mettere attributi su ogni servizio. Le regole restano le stesse ovunque: ruoli, conferma, registro.
Le azioni dell'interfaccia sotto le stesse regole. Quello che l'agente fa sullo schermo, e non solo nei tuoi servizi, seguirà gli stessi ruoli, la stessa conferma e lo stesso registro di ogni altra azione.
React e Angular alla pari di Blazor. Oggi si collegano con SignalR o con i Server-Sent Events e disegnano la loro schermata. L'obiettivo è un agente che lavori nel tuo front end bene come in Blazor.
Compatibilità con lo standard AG-UI e i suoi client. Agent Framework ha un'integrazione AG-UI, ancora in prerelease per .NET. MentorAgent funzionerà con quello standard e con i client costruiti per lui, così la scelta del front end non ti lega a una sola libreria.
Poi, in breve:
- Confronta due modelli sui tuoi casi di prova prima di cambiare, e ferma il rilascio se il nuovo fa peggio.
- Costi chiari, quanto spende ogni agente e ogni utente.
- Un widget che tutti possono usare, secondo la norma europea sull'accessibilità.
Due passi di questa strada sono già usciti, con MentorAgent 1.3.0: risposte dai tuoi documenti, anche da un database vettoriale come pgvector, Qdrant o Azure AI Search, e un'app per tanti clienti, con dati e limiti separati per ognuno. Le note della 1.3.0 dicono cosa cambia.
Il filo è lo stesso in tutto. Agent Framework dà il motore e corre veloce. MentorAgent è lo strato che fa di quel motore una parte della tua app, sotto le tue regole.
Approfondisci
Sezione “Approfondisci”- Ruoli, conferma e governance: i controlli, in ordine, e cosa resta nel tuo codice.
- Server MCP: cosa si pubblica, a chi e perché.
- Provider dei modelli: il percorso del chat client, quello dell'
AIAgente cosa cambia. - I tre livelli degli agenti: azioni, specialisti e team sui workflow di Agent Framework.
- Che cos'è MentorAgent: il quadro completo, in una pagina.
Come iniziare
Sezione “Come iniziare”Scritto con l'aiuto dell'AI; codice e fatti verificati dal team di MentorAgent.
