MentorAgent

← Tutti gli articoli

Meno token, meno costi: come MentorAgent snellisce ogni richiesta

Dove vanno i token di un agente AI, cosa fa MentorAgent per ogni parte e le impostazioni da cui partire per un gestionale, chat lunghe, molti utenti e un modello locale.

MentorAgent team · 13 min di lettura· Read in English

Copertina di MentorAgent: il titolo Meno token, meno costi; una richiesta al modello è disegnata come una pila di blocchi (istruzioni, tool, cronologia, contesto, domanda); MentorAgent tiene solo i blocchi che servono al turno e manda il turno a un modello piccolo o a uno potente.
In questo articolo

Un chatbot manda una domanda e riceve una risposta. Un agente che agisce manda molto di più. Ogni chiamata porta con sé le istruzioni, la definizione di ogni tool, la conversazione fin lì e il contesto della pagina. Poi chiama un tool, e l'intera richiesta riparte.

MentorAgent snellisce ognuna di queste parti, con opzioni che puoi leggere, impostare e misurare. Questo articolo mostra dove vanno i token, cosa fa ogni leva, da quali impostazioni partire e come controllare il risultato.

In un agente costruito con MentorAgent, una richiesta al modello è fatta di:

  • Istruzioni: il prompt di sistema, con le regole, le pagine e l'utente.
  • Definizioni dei tool: nome, descrizione e parametri di ogni azione che il modello può chiamare.
  • Cronologia: la conversazione fin lì, con le chiamate ai tool e i loro risultati.
  • Contesto: la pagina aperta, la data, la memoria dell'utente, i documenti trovati dal RAG.
  • La domanda e la risposta.

Un turno può fare anche altre chiamate: una per ogni andata e ritorno con un tool, le piccole chiamate delle decisioni di MentorAgent, e quelle degli specialisti e dei team che aggiungi.

Due parti crescono da sole: le definizioni dei tool crescono con la tua applicazione, la cronologia con la conversazione. Quasi tutte le leve qui sotto lavorano su queste due, sulla scelta del modello o sulle chiamate in più.

Una parte del lavoro non chiede impostazioni.

  • Le istruzioni non elencano le azioni. Il prompt del coordinatore porta il numero delle azioni dirette, non le azioni, e le pagine e gli specialisti con una descrizione breve. Il testo che non cambia viene per primo.
  • Un'azione che l'utente non può eseguire non viene mandata. Il modello non vede mai la definizione di un'azione che i ruoli dell'utente non permettono. Gli viene solo detto che alcune azioni non sono disponibili.
  • Un solo embedding per messaggio. Lo condividono filtro dei tool, instradamento semantico e memoria. Le descrizioni dei tool si trasformano in embedding una volta per processo.
  • Le skill si caricano quando servono. Con le skill accese (EnableSkills) il prompt porta nome e descrizione di ogni skill, e il modello carica il testo intero con load_skill solo quando gli serve.

Tutto il resto è un'opzione, e le leve che risparmiano token sono spente per default. Scegli tu quelle adatte alla tua applicazione.

Definizioni dei tool: mandare solo le azioni che c'entrano

Sezione “Definizioni dei tool: mandare solo le azioni che c'entrano”

Il problema. Un gestionale ha decine di azioni, e ogni definizione arriva al modello a ogni chiamata.

Cosa fa MentorAgent. Con EnableToolFiltering viaggiano solo le azioni che corrispondono al messaggio. MentorAgent confronta il messaggio con nome e descrizione di ogni azione per somiglianza di embedding, quindi un messaggio in italiano può trovare un'azione in inglese. Viaggiano al massimo ToolFilterMaxTools azioni (12 per default), sopra la soglia ToolFilterMinScore (0,35). I tool di base, come la navigazione e il passaggio agli specialisti, viaggiano sempre. La scelta si fa una volta per messaggio e vale per tutte le andate e ritorni del turno. Il filtro vuole un EmbeddingGenerator: senza, vengono mandati tutti i tool e nel log compare un avviso.

Il punteggio di un embedding ordina bene ma fa da soglia male, quindi il filtro ha delle reti di sicurezza:

  • Se nessuna azione supera la soglia, vengono mandate comunque le tre meglio classificate che non chiedono conferma né ruolo. La docs le stima in circa 80 token di input per chiamata.
  • Se tutte le azioni trovate chiedono conferma, viaggiano con loro fino a tre delle azioni meglio classificate che non la chiedono.
  • Se un messaggio non corrisponde a niente, come "Sì, procedi", tornano le azioni del messaggio precedente.

Con il filtro acceso, lo stesso filtro decide anche, turno per turno, se dichiarare i tool ospitati del provider (ricerca sul web, ricerca nei file): FilterHostedTools, attivo per default.

Una misura. L'app di prova di questo articolo ha trenta azioni. Per la domanda "What is the status of order 1042?" la richiesta porta 31 tool (le 30 azioni e il tool di navigazione) e 4.818 caratteri di definizioni senza il filtro. Con il filtro porta 7 tool e 1.296 caratteri. La prova gira sulla pipeline vera di MentorAgent con modelli finti e senza chiamare nessun provider, quindi le misure sono caratteri, non token, e le azioni scelte dipendono dal modello di embedding. Quello che vale anche da te è la proporzione.

Con poche azioni c'è poco da risparmiare, mentre restano la chiamata di embedding e il rischio di una scelta sbagliata. Provalo con le tue domande.

Cronologia: mandare meno passato

Sezione “Cronologia: mandare meno passato”

Il problema. La cronologia riparte a ogni chiamata, risultati dei tool compresi, quindi in una chat lunga ogni chiamata è più grande della precedente.

Cosa fa MentorAgent. Due impostazioni lavorano insieme.

  • MaxSessionMessages (50 per default) limita la cronologia conservata. MentorAgent toglie turni interi, i più vecchi per primi, e tiene ogni chiamata a un tool con il suo risultato, così il modello vede ancora i dati che un tool ha letto.
  • EnableCompaction accorcia ciò che viene mandato, senza chiamare un modello. Tiene gli ultimi CompactionMaxTurns turni (8) e lascia fuori i più vecchi. Compatta anche le vecchie chiamate ai tool e, sopra CompactionTokenThreshold (4000 token), toglie i messaggi più vecchi, ma tiene sempre i più recenti. La conversazione conservata resta intera.

Una misura. Nell'app di prova, quindici turni leggono ciascuno un risultato di 2.800 caratteri. Nell'ultima richiesta i messaggi mandati sono 37.415 caratteri senza compattazione e 23.033 con la compattazione. Dal nono turno in poi la misura resta piatta: il lavoro lo fa la finestra di otto turni, e un risultato lungo dentro quei turni viene ancora mandato intero. Limitando ogni risultato a 2.000 caratteri con OnToolResult, come nelle impostazioni più sotto, si scende a 16.633. Anche qui sono caratteri, misurati con modelli finti.

Quanto costa. Tagliare la cronologia fa risparmiare token e può costare precisione. Il README di MentorAgent confronta una cronologia che scarta le chiamate ai tool e i loro risultati con quella predefinita, che li tiene: in una prova di laboratorio di 84 turni le risposte corrette sono passate dall'85% al 95%, e i token sono cresciuti di circa il 9%. Compatta il minimo che serve.

La compattazione non viene installata con UseServiceManagedHistory (per esempio l'API Responses con conversazione conservata): la cronologia la tiene il servizio, quindi in locale non c'è niente da accorciare.

Contesto: tenere stabile l'inizio del prompt

Sezione “Contesto: tenere stabile l'inizio del prompt”

Il problema. La pagina, i suoi dati, il suo indirizzo e l'ora cambiano a ogni pagina e a ogni minuto. Per default stanno in fondo alle istruzioni, che vengono prima di tutta la conversazione. Un modello che tiene in cache il prompt dal suo inizio rilegge allora tutta la conversazione.

Cosa fa MentorAgent. Con SessionContextPlacement = LastUserMessage quelle righe passano all'inizio dell'ultimo messaggio dell'utente, solo nella richiesta mandata al modello. Le istruzioni restano uguali per tutta la sessione, e la conversazione conservata tiene le parole dell'utente. Nell'app di prova le istruzioni hanno la stessa lunghezza al primo e al secondo turno.

Conta soprattutto per un modello locale, dove rileggere la conversazione può richiedere molti secondi su una CPU. I provider ospitati che usano la cache per prefisso seguono la stessa regola: la documentazione di Azure OpenAI chiede il contenuto stabile all'inizio e quello dinamico in fondo, e riporta i token trovati in cache come cached_tokens nell'uso di ogni risposta (prompt caching (sito esterno)). MentorAgent non ha un'opzione che accenda o spenga la cache del provider. Tiene stabile l'inizio e lascia il resto al provider.

Da sapere. I documenti del RAG, il nome e i ruoli dell'utente e la memoria restano nelle istruzioni. L'opzione non ha effetto con UseServiceManagedHistory o con un Agent già costruito, e un avviso lo dice. Il filtro dei tool cambia l'elenco dei tool da un messaggio all'altro, e questo può andare contro un provider che mette in cache le definizioni dei tool insieme al prompt: confronta i token in cache del provider prima e dopo.

Il modello giusto per ogni chiamata

Sezione “Il modello giusto per ogni chiamata”

Il problema. Un saluto e un'analisi in più passaggi non richiedono lo stesso modello.

Cosa fa MentorAgent. Imposta un ChatClient piccolo, uno StrongChatClient e una RoutingStrategy che sceglie il modello di ogni turno:

StrategiaCome decideCosto in più
Custom (predefinita)il tuo UseStrongModelAsync o UseStrongModelquello che fa il tuo codice
Semanticsomiglianza del messaggio con turni di esempionessuno oltre all'embedding, condiviso con il filtro dei tool
Classifieruna chiamata breve chiede a un modello se il turno è difficileuna piccola chiamata per turno, su ChatClient o RoutingClassifierClient
Cascaderisponde il modello piccolo, un giudice legge la risposta, risponde di nuovo il modello potente se non bastauna chiamata del giudice, più una seconda risposta quando sale; solo senza streaming: nella chat, che è in streaming, decide come Classifier

La decisione vale per tutto il ciclo dei tool del turno. Se a una strategia manca ciò che le serve, per esempio Semantic senza un modello di embedding, MentorAgent scrive un avviso nel log e ogni turno resta su ChatClient.

ClassifierChatClient serve le piccole decisioni di MentorAgent: i controlli di sicurezza, il controllo del tema, il controllo delle risposte senza tool, i fatti da ricordare, il controllo dei tool ospitati e i controlli dietro le due opzioni "require". Per default è ChatClient. Puntalo a un modello piccolo e veloce.

Specialisti, membri dei team e router del passaggio girano su ChatClient, senza instradamento né filtro dei tool. I loro tool vanno solo a loro, e questo tiene corto l'elenco del coordinatore, ma un passaggio aggiunge almeno due chiamate al modello.

Chiamate che puoi spegnere o spostare

Sezione “Chiamate che puoi spegnere o spostare”

Alcune opzioni aggiungono una chiamata prima o dopo la risposta.

  • Memoria. Con UseMemoryContext, MemoryAutoCapture (attivo per default) fa una piccola chiamata dopo ogni messaggio per estrarre i fatti. Spento, risparmia la chiamata, ma il modello scrive i ricordi con un tool remember, in modo meno affidabile, e il tool e il suo blocco di prompt viaggiano a ogni chiamata. MemoryContextCount (10) limita i ricordi nel prompt; MemoryRelevanceFiltering manda solo quelli pertinenti.
  • Controlli di sicurezza. EnableSafetyCheck ed EnableOutputSafetyCheck aggiungono una chiamata ciascuno. RefuseOutOfScope aggiunge una piccola chiamata per turno, o condivide quella del controllo in ingresso quando è acceso. Poi chiude un turno fuori tema senza chiamare il coordinatore.
  • Le due opzioni "require". RequireLookupForRecordQuestions e RequireActionForChangeRequests aggiungono una chiamata del classificatore per turno. Comprano affidabilità, non risparmio.
  • Il controllo delle risposte senza tool. Dalla 1.3.0, CheckAnnouncedActions (attivo per default) aggiunge una chiamata al modello del classificatore dopo ogni risposta che non ha chiamato tool: cerca una risposta che annuncia o dà per fatta un'azione non eseguita e, quando la trova, il coordinatore riceve un'altra richiesta nello stesso turno. Costa qualche centinaio di token per ognuna di queste risposte e parte dopo che la risposta è comparsa, quindi l'utente non la aspetta. Con CheckAnnouncedActions = false si risparmia la chiamata, ma una risposta che annuncia un'azione e non esegue niente resta com'è. Di più in Cost and latency e nel riferimento delle opzioni.
  • Tool ospitati. HostedToolDomainCheck chiede al modello del classificatore se un messaggio riguarda la tua applicazione prima di dichiarare un tool a pagamento. MaxHostedToolCallsPerSession mette un tetto a una sessione; FileSearchMaxResults limita ciò che la ricerca nei file inserisce.
  • RAG. RagResultCount (5) e RagMinScore decidono quanti documenti entrano nel prompt.
  • Team. Il turno di ogni membro è una chiamata, fino a MaxIterations (10 per default in [MentorTeam]). Tienilo basso.

MaxMessageLength (4000 caratteri) rifiuta un messaggio lungo prima di chiamare il modello. RateLimitPerUser conta i messaggi per utente in una finestra: 0 per default, cioè nessun limite. Vale per persona solo con gli utenti autenticati. Gli utenti anonimi sono contati per sessione, per default, quindi un ricaricamento ricomincia.

Nella libreria non c'è un budget di token per utente o per turno, né un'opzione per la lunghezza massima della risposta. Se te ne serve uno, ConfigureChatClientPipeline aggiunge un tuo middleware attorno alle chiamate del coordinatore al modello. Solo quelle chiamate ci passano.

Quattro scenari, poche righe ciascuno. Si combinano: una chat lunga su un modello locale usa entrambe le impostazioni.

Un'app interna con molte azioni

Sezione “Un'app interna con molte azioni”
Program.cs
using Microsoft.Extensions.AI;
using Novior.MentorAgent.Extensions;
using OpenAI;

var openAI = new OpenAIClient(builder.Configuration["OpenAI:Key"]!);

builder.Services.AddScoped<BackOfficeActions>();
builder.Services.AddMentorAgent(options =>
{
    options.AppName = "Back office";
    options.ScanAssemblies = [typeof(BackOfficeActions).Assembly];
    options.ChatClient = openAI.GetChatClient("gpt-4.1").AsIChatClient();

    // Only the actions that match the message travel with it
    options.EmbeddingGenerator = openAI.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator();
    options.EnableToolFiltering = true;
    options.ToolFilterMaxTools = 12;

    // MentorAgent's own short decisions go to a small model
    options.ClassifierChatClient = openAI.GetChatClient("gpt-4.1-mini").AsIChatClient();
});

BackOfficeActions è la classe con i tuoi metodi [MentorAction]. Tieni le descrizioni brevi e precise: il filtro confronta il messaggio con nome e descrizione di ogni azione.

C#
using System.Text.Json;

options.EnableCompaction = true;
options.CompactionTokenThreshold = 4000;
options.CompactionMaxTurns = 8;

// A text result is capped before the model reads it; the hook receives it as a JsonElement
options.OnToolResult = (tool, result) =>
    result is JsonElement { ValueKind: JsonValueKind.String } json && json.GetString() is { Length: > 2000 } text
        ? text[..2000]
        : result;

Il limite taglia il testo. Usalo dove basta l'inizio di un risultato, e lascia passare intatti i risultati strutturati, come qui.

C#
options.ChatClient = openAI.GetChatClient("gpt-4o-mini").AsIChatClient();
options.StrongChatClient = openAI.GetChatClient("gpt-4o").AsIChatClient();

// Needs the EmbeddingGenerator: the message is embedded once per turn and shared with the tool filter
options.RoutingStrategy = MentorRoutingStrategy.Semantic;

options.MaxMessageLength = 2000;
options.RateLimitPerUser = 20;
options.RateLimitWindowSecs = 60;

Se hai già un modello di embedding per il filtro dei tool, l'instradamento Semantic non aggiunge chiamate al modello. Senza, Classifier non chiede altro, al prezzo di una piccola chiamata per turno.

C#
using System.ClientModel;

options.ChatClient = new OpenAIClient(
        new ApiKeyCredential("ollama"),
        new OpenAIClientOptions
        {
            Endpoint = new Uri("http://localhost:11434/v1"),
            NetworkTimeout = TimeSpan.FromMinutes(20),
        })
    .GetChatClient("llama3.2-16k")
    .AsIChatClient();

// The start of the prompt stays the same through the session; the history sent stays short
options.SessionContextPlacement = MentorSessionContextPlacement.LastUserMessage;
options.EnableCompaction = true;

// The safety checks run on the same slow model: give them time
options.SafetyCheckTimeout = TimeSpan.FromMinutes(2);

Il prompt di MentorAgent può essere più lungo del contesto predefinito di Ollama, e Ollama allora taglia l'inizio del prompt senza dare errore. Crea una variante con un contesto più grande (PARAMETER num_ctx 16384 in un Modelfile) e usane il nome, qui llama3.2-16k. Altro in Ollama e altri modelli locali.

Non cambiare cinque opzioni insieme. Cambiane una, fai le stesse domande, leggi i numeri.

  • Il log. Ogni chiamata a un modello scrive una riga Information: modello, token in ingresso e in uscita, tempo, totali della sessione.
  • Il contatore. IMentorMetrics.GetSnapshot() restituisce token, richieste e latenza media per ogni id di modello, quindi si distinguono il modello piccolo, quello potente e quello di embedding. Il componente MentorDashboard e GET /mentor/admin/metrics mostrano le stesse cifre. I conteggi stanno in memoria, a meno che registri un IMentorMetricsStore.
  • Il costo. MentorAgent non porta prezzi. Li inserisci in ModelPricing, per milione di token, con l'id del modello che mostra la dashboard. Il contatore non distingue i token in ingresso trovati in cache, quindi con la cache del provider il suo costo è una stima, non la fattura.
Program.cs
// Prices per million input and output tokens, under the model id the dashboard shows
options.ModelPricing = new Dictionary<string, ModelPrice>
{
    ["gpt-4o-mini"] = new(
        configuration.GetValue<decimal>("Prices:Small:InputPer1M"),
        configuration.GetValue<decimal>("Prices:Small:OutputPer1M")),
    ["gpt-4o"] = new(
        configuration.GetValue<decimal>("Prices:Strong:InputPer1M"),
        configuration.GetValue<decimal>("Prices:Strong:OutputPer1M")),
};

app.MapGet("/ops/tokens", (IMentorMetrics metrics) =>
    metrics.GetSnapshot().Models.Select(m => new
    {
        m.ModelId,
        m.InputTokens,
        m.OutputTokens,
        m.RequestCount,
        m.AvgLatencyMs,
        m.TotalCost,
    })).RequireAuthorization();

Le tracce di EnableObservability coprono solo le chiamate del coordinatore al modello: avvolgi gli altri client con UseOpenTelemetry() per tracciare anche quelli. Per un controllo nella tua pipeline di build, MentorEvaluator esegue prompt di prova sul tuo ChatClient e fallisce quando l'uso di token o la qualità peggiorano. Chiama il modello, quindi lo lanci quando lo decidi tu.

LevaOpzione e valore predefinitoQuando usarla
Solo i tool pertinentiEnableToolFiltering spento, ToolFilterMaxTools 12, ToolFilterMinScore 0,35; serve EmbeddingGeneratorl'applicazione ha decine di azioni
Cronologia mandata più cortaEnableCompaction spento, CompactionTokenThreshold 4000, CompactionMaxTurns 8le chat sono lunghe
Risultati dei tool limitatiOnToolResult nessunoun tool restituisce testo lungo e basta l'inizio
Inizio del prompt stabileSessionContextPlacement Instructionsmodello locale, o provider che usa la cache per prefisso
Modello piccolo di baseStrongChatClient nessuno, RoutingStrategy Customturni facili e difficili si mescolano
Modello piccolo per le decisioni proprieClassifierChatClient nessuno (usa ChatClient)è attivo un controllo di sicurezza, di tema, di memoria o "require"
Meno ricordi nel promptMemoryContextCount 10, MemoryRelevanceFiltering spentogli utenti hanno molti ricordi
Meno documenti nel promptRagResultCount 5, RagMinScore 2 o quello della sorgenteil RAG è attivo e bastano meno documenti
Tool ospitati sotto controlloFilterHostedTools attivo, HostedToolDomainCheck spento, MaxHostedToolCallsPerSession 0è attiva la ricerca sul web o nei file
LimitiMaxMessageLength 4000, RateLimitPerUser 0l'applicazione è aperta a molti utenti

Non conosci ancora MentorAgent? Parti da Che cos'è MentorAgent.

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