Avvio rapido

In questo avvio rapido costruisci Cases, una piccola app Blazor Server per le pratiche di assistenza. Il suo agente legge lo stato di una pratica ogni volta che gli serve, e aggiunge una nota a una pratica solo dopo che hai confermato. Questa regola sta nel tuo codice, accanto al metodo, quindi il modello non può aggirarla con le parole.

Questo avvio rapido usa Blazor, perché per Blazor il widget della chat è già pronto. Con un front end React, Angular o Vue, o con un'app mobile, il servizio e la sua registrazione restano gli stessi: vedi Any front end.

Cosa ti serve:

• l'SDK di .NET 10;
• una chiave API di OpenAI.

Prerequisites elenca le versioni con cui MentorAgent è provato. Puoi anche scaricare il progetto finito come file zip, con licenza MIT.

Crea una Blazor Web App con interattività Server:

dotnet new blazor -n Cases --interactivity Server --all-interactive
cd Cases

--all-interactive rende interattive tutte le pagine, e il widget ne ha bisogno: in una pagina resa in modo statico il suo pulsante compare, ma un clic non fa niente.

Aggiungi MentorAgent:

dotnet add package Novior.MentorAgent

<ItemGroup>
  <PackageReference Include="Novior.MentorAgent" Version="1.2.0" />
</ItemGroup>

<ItemGroup>
  <PackageVersion Include="Novior.MentorAgent" Version="1.2.0" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="Novior.MentorAgent" />
</ItemGroup>

#:package Novior.MentorAgent@1.2.0

MentorAgent non contiene il pacchetto di un provider di modelli. Questo avvio rapido usa OpenAI, quindi aggiungi il client OpenAI per Microsoft.Extensions.AI:

dotnet add package Microsoft.Extensions.AI.OpenAI --version 10.6.0

Il pacchetto installa anche OpenAI. L'opzione --version del comando è la versione con cui è stato provato il progetto dell'avvio rapido.

Crea CaseService.cs nella cartella del progetto:

using Novior.MentorAgent.Attributes;

public class CaseService
{
    [MentorAction(
        Description = "Returns the status of a case",
        ReadOnly = true)]
    public string GetCaseStatus(string caseNumber)
        => $"Case {caseNumber} is under review.";

    [MentorAction(Description = "Adds a note to a case")]
    public string AddNote(string caseNumber, string text)
        => $"Note added to case {caseNumber}.";
}

L'attributo [MentorAction] segna un metodo come azione. Il modello vede ogni azione come un tool: una funzione che il modello può chiedere a MentorAgent di eseguire. Il tool prende il nome del metodo in snake case, cioè parole minuscole unite da trattini bassi: GetCaseStatus diventa get_case_status, e AddNote diventa add_note.

• GetCaseStatus legge soltanto, quindi dichiara ReadOnly = true. L'agente lo chiama senza chiedere a nessuno.
• AddNote cambia i dati. Una [MentorAction] che non è di sola lettura chiede conferma per default, quindi l'agente mostra un riquadro di conferma prima di aggiungere la nota.

In questo avvio rapido i metodi restituiscono un testo fisso, così puoi provare l'agente senza un database.

In cima a Program.cs aggiungi le direttive using:

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

Poi, dopo var builder = WebApplication.CreateBuilder(args);, registra il servizio e MentorAgent:

builder.Services.AddScoped<CaseService>();
builder.Services.AddMentorAgent(options =>
{
    options.AppName = "Case management";
    options.ChatClient = new OpenAIClient(builder.Configuration["OpenAI:Key"]
            ?? throw new InvalidOperationException("OpenAI:Key is missing: run "
                + "dotnet user-secrets set OpenAI:Key <your-key>"))
        .GetChatClient("gpt-4o-mini")
        .AsIChatClient();
    options.ScanAssemblies = [typeof(Program).Assembly];
});

• AddScoped<CaseService>() registra il tuo servizio come al solito. MentorAgent trova i suoi metodi negli assembly elencati in ScanAssemblies, e prende l'istanza dalla dependency injection.
• AppName, ScanAssemblies e un modello sono obbligatori. Qui il modello lo imposti con ChatClient. Se hai già un tuo agente di Agent Framework, imposta invece Agent.
• gpt-4o-mini è il modello. Va bene qualunque modello che supporti il tool calling.

Tieni la chiave fuori dal codice, negli user secrets del progetto. Nel secondo comando sostituisci <your-key> con la tua chiave API di OpenAI:

dotnet user-secrets init
dotnet user-secrets set OpenAI:Key <your-key>

Per usare Azure OpenAI o un modello locale con Ollama, cambia le righe che impostano ChatClient. Model providers elenca i pacchetti e le direttive using che ti servono. Parla anche dei provider che chiedono invece un Agent.

Aggiungi il namespace del widget a Components/_Imports.razor:

@using Novior.MentorAgent.Abstractions.Components

Poi metti il widget in fondo a Components/Layout/MainLayout.razor:

<ChatWidget />

Il widget carica da solo i suoi stili e i suoi script, quindi App.razor resta com'è.

Avvia l'app:

dotnet run

Apri l'indirizzo che compare nel terminale e fai clic sul pulsante del widget, nell'angolo della pagina.

1. Scrivi "Qual è lo stato della pratica C-1?". L'agente chiama get_case_status e risponde con quello che ha restituito il tuo metodo.
2. Scrivi "Aggiungi una nota alla pratica C-1: documenti ricevuti". L'agente chiama add_note, e nel widget compare un riquadro di conferma, con l'azione e i suoi argomenti. Le etichette vengono dai nomi dei parametri: caseNumber diventa "Case Number".
3. Fai clic su Confirm. AddNote parte e restituisce il suo messaggio.

Se invece fai clic su Cancel, il metodo non parte, e il modello viene a sapere che hai rifiutato. In questo avvio rapido AddNote non salva la nota: il tutorial aggiunge un archivio che tiene le note.

Se qualcosa non funziona, Troubleshooting parte da quello che vedi.

Mentre un'azione è in corso, il widget mostra la sua descrizione, non il nome del tool. Per vedere quale tool chiama l'agente mentre sviluppi, porta a Debug il livello di log della categoria Novior.MentorAgent in appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Novior.MentorAgent": "Debug"
    }
  }
}

Il terminale mostra allora una riga come [MentorAgent] Tool call: get_case_status per ogni chiamata. Tieni le altre voci della sezione LogLevel che il file ha già.

• Costruisci passo per passo, nel tutorial, un agente più completo per le pratiche, a partire da 1. Turn service methods into actions.
• Aggiungi MentorAgent a un progetto che hai già: Add MentorAgent to an existing app oppure, con un front end React, Angular, Vue o mobile, Any front end.
• Configuralo per il tuo host e il tuo provider: Blazor Server app, Model providers e, prima di andare in produzione, la Production checklist.
• Leggi come ruoli e conferma proteggono le tue azioni: Ruoli, conferma e governance.
• Cerca un termine che non conosci nel Glossary.