Function calling in .NET: far chiamare il tuo codice a un LLM con Microsoft.Extensions.AI

# scarica un modello che supporta il tool calling (llama3.1, qwen3, mistral...)
$ ollama pull llama3.1

# avvia il server (di solito parte gia' da solo)
$ ollama serve                 # http://localhost:11434

# prova veloce dal terminale
$ ollama run llama3.1 "Ciao, chi sei?"

# nuova Minimal API
$ dotnet new web -n ToolCallingDemo && cd ToolCallingDemo

# astrazioni AI + provider Ollama (OllamaSharp) + Refit + driver Mongo
$ dotnet add package Microsoft.Extensions.AI
$ dotnet add package OllamaSharp
$ dotnet add package Refit.HttpClientFactory
$ dotnet add package MongoDB.Driver

{
  "Ollama": {
    "Endpoint": "http://localhost:11434",
    "ChatModel": "llama3.1"
  },
  "ExchangeRates": {
    "BaseUrl": "https://api.exchangerate.host"
  },
  "Mongo": {
    "ConnectionString": "mongodb://localhost:27017",
    "Database": "shopdemo"
  }
}

using Microsoft.Extensions.AI;
using MongoDB.Driver;
using OllamaSharp;
using Refit;
using ToolCallingDemo.Tools;

namespace ToolCallingDemo.Extensions;

// Un'unica extension method registra tutto lo stack: il chat client Ollama
// (via OllamaSharp), la pipeline di function invocation, MongoDB, il client
// Refit e i "tool" come servizi tipizzati.
public static class AssistantServiceExtensions
{
    public static IServiceCollection AddAssistant(this IServiceCollection services, IConfiguration config)
    {
        var ollama = config.GetSection("Ollama");
        var chatClient = new OllamaApiClient(new Uri(ollama["Endpoint"]!), ollama["ChatModel"]!);

        // OllamaApiClient implementa IChatClient. UseFunctionInvocation aggiunge il
        // FunctionInvokingChatClient, che esegue da solo i tool richiesti dal modello.
        services.AddChatClient(chatClient)
            .UseFunctionInvocation()
            .UseLogging();

        var mongo = config.GetSection("Mongo");
        var mongoClient = new MongoClient(mongo["ConnectionString"]);
        services.AddSingleton<IMongoDatabase>(_ => mongoClient.GetDatabase(mongo["Database"]));

        // Client HTTP tipizzato con Refit: niente HttpClient scritto a mano.
        services.AddRefitClient<IExchangeRateApi>()
            .ConfigureHttpClient(c => c.BaseAddress = new Uri(config["ExchangeRates:BaseUrl"]!));

        services.AddScoped<OrderTools>();
        services.AddScoped<PricingTools>();
        return services;
    }
}

using ToolCallingDemo.Endpoints;
using ToolCallingDemo.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Una riga registra Ollama (chat + function invocation), MongoDB, Refit e i tool.
builder.Services.AddAssistant(builder.Configuration);

var app = builder.Build();

app.MapAssistantEndpoints();   // POST /assistant

app.Run();

using System.ComponentModel;
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Driver;

namespace ToolCallingDemo.Tools;

// I tool sono normali metodi C#. L'attributo [Description] e' cio' che il modello
// legge per capire QUANDO e COME chiamarli; parametri e tipo di ritorno diventano
// lo schema JSON del tool.
public class OrderTools(IMongoDatabase database)
{
    private readonly IMongoCollection<Order> _orders = database.GetCollection<Order>("orders");

    [Description("Recupera stato, totale e data di consegna di un ordine dato il suo codice.")]
    public async Task<OrderStatus> GetOrderStatusAsync(
        [Description("Il codice ordine, es. ORD-1024")] string orderCode,
        CancellationToken ct = default)
    {
        var order = await _orders.Find(o => o.Code == orderCode).FirstOrDefaultAsync(ct);
        if (order is null)
            return new OrderStatus(orderCode, "not_found", 0m, null);

        return new OrderStatus(order.Code, order.Status, order.Total, order.EstimatedDelivery);
    }
}

// DTO tipizzati: mai object/dynamic/anonimi al confine di un tool.
public record OrderStatus(string OrderCode, string Status, decimal Total, DateOnly? EstimatedDelivery);

// Documento MongoDB letto dal tool. [BsonId] mappa la chiave _id e
// [BsonIgnoreExtraElements] evita che campi extra sul documento rompano
// la deserializzazione (utile quando lo schema evolve).
[BsonIgnoreExtraElements]
public class Order
{
    [BsonId]
    public ObjectId Id { get; set; }

    public string Code { get; set; } = "";
    public string Status { get; set; } = "";

    // decimal -> Decimal128 e' gia' il default; l'attributo lo rende esplicito
    // ed evita sorprese se un vecchio documento salvo' l'importo come double.
    [BsonRepresentation(BsonType.Decimal128)]
    public decimal Total { get; set; }

    public DateOnly? EstimatedDelivery { get; set; }
}

using System.ComponentModel;
using Refit;

namespace ToolCallingDemo.Tools;

// Il contratto dell'API esterna e' l'interfaccia stessa: Refit genera il client.
// I parametri non nel path diventano querystring: /convert?from=EUR&to=USD&amount=100
public interface IExchangeRateApi
{
    [Get("/convert")]
    Task<ConvertResponse> ConvertAsync(string from, string to, decimal amount, CancellationToken ct = default);
}

public record ConvertResponse(decimal Result);

// Secondo gruppo di tool: converte un importo tra due valute al tasso corrente.
public class PricingTools(IExchangeRateApi api)
{
    [Description("Converte un importo da una valuta a un'altra al tasso di cambio corrente.")]
    public async Task<decimal> ConvertPriceAsync(
        [Description("Importo da convertire")] decimal amount,
        [Description("Valuta di partenza ISO 4217, es. EUR")] string from,
        [Description("Valuta di arrivo ISO 4217, es. USD")] string to,
        CancellationToken ct = default)
    {
        var conversion = await api.ConvertAsync(from, to, amount, ct);
        return Math.Round(conversion.Result, 2);
    }
}

using Microsoft.Extensions.AI;
using ToolCallingDemo.Tools;

namespace ToolCallingDemo.Endpoints;

public record AssistantRequest(string Question);
public record AssistantReply(string Answer);

public static class AssistantEndpoints
{
    // POST /assistant — il modello risponde e, se serve, chiama i tool da solo.
    public static void MapAssistantEndpoints(this IEndpointRouteBuilder app) =>
        app.MapPost("/assistant", async (
            AssistantRequest req,
            IChatClient chat,
            OrderTools orderTools,
            PricingTools pricingTools,
            CancellationToken ct) =>
        {
            // I due gruppi di metodi diventano i tool disponibili per questa richiesta.
            var options = new ChatOptions
            {
                Tools =
                [
                    AIFunctionFactory.Create(orderTools.GetOrderStatusAsync),
                    AIFunctionFactory.Create(pricingTools.ConvertPriceAsync)
                ]
            };

            var messages = new List<ChatMessage>
            {
                new(ChatRole.System,
                    "Sei l'assistente di un negozio. Usa i tool per dati reali su ordini e prezzi. " +
                    "Non inventare stati o importi: se un tool non trova nulla, dillo."),
                new(ChatRole.User, req.Question)
            };

            var response = await chat.GetResponseAsync(messages, options, ct);
            return Results.Ok(new AssistantReply(response.Text));
        });
}

# lo stato di un ordine: il modello chiamera' GetOrderStatus da solo
$ curl http://localhost:5000/assistant \
    -H "Content-Type: application/json" \
    -d '{"question":"A che punto e' l ordine ORD-1024?"}'

# una conversione: il modello chiamera' ConvertPrice
$ curl http://localhost:5000/assistant \
    -H "Content-Type: application/json" \
    -d '{"question":"Quanto fa 149,90 EUR in USD?"}'

using Microsoft.Extensions.AI;

// Stessi tool, ma con limiti espliciti sul loop di function calling.
services.AddChatClient(chatClient)
    .UseFunctionInvocation(configure: c =>
    {
        c.MaximumIterationsPerRequest = 5;          // al massimo 5 round-trip col modello
        c.MaximumConsecutiveErrorsPerRequest = 2;   // stop dopo 2 errori di fila
        c.IncludeDetailedErrors = false;            // non passare stack trace al modello
    })
    .UseLogging();