The .NET AI Stack in 2026: Microsoft.Extensions.AI, Agent Framework and IChatClient

// FAKE, DETERMINISTIC AI SERVICES FOR TEACHING. No model, no network, no API key.
// FakeChatClient implements the real Microsoft.Extensions.AI IChatClient interface, but its "intelligence" is a
// script you pass in. HashingEmbeddingGenerator implements the real IEmbeddingGenerator interface with a
// bag-of-words hashing trick, so similar wording gives similar vectors. Swap either for a real provider
// (Azure OpenAI, OpenAI, Ollama, ...) by changing one registration; the calling code stays the same.
using System.Runtime.CompilerServices;
using System.Text.RegularExpressions;
using Microsoft.Extensions.AI;

namespace FakeAI;

public delegate ChatMessage Script(IReadOnlyList<ChatMessage> messages, ChatOptions? options);

public sealed class FakeChatClient(Script script, string modelId = "fake-model-1") : IChatClient
{
    public int Calls { get; private set; }

    public Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken ct = default)
    {
        ct.ThrowIfCancellationRequested();
        Calls++;
        var list = messages.ToList();
        var reply = script(list, options);
        bool toolCall = reply.Contents.OfType<FunctionCallContent>().Any();
        return Task.FromResult(new ChatResponse(reply)
        {
            ModelId = modelId,
            FinishReason = toolCall ? ChatFinishReason.ToolCalls : ChatFinishReason.Stop,
            Usage = new UsageDetails { InputTokenCount = Tokens.Estimate(list), OutputTokenCount = Tokens.Estimate([reply]), TotalTokenCount = Tokens.Estimate(list) + Tokens.Estimate([reply]) },
        });
    }

    public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken ct = default)
    {
        var response = await GetResponseAsync(messages, options, ct);
        var msg = response.Messages[^1];
        foreach (var c in msg.Contents.Where(c => c is not TextContent)) yield return new ChatResponseUpdate(msg.Role, [c]) { ModelId = modelId };
        foreach (Match w in Regex.Matches(msg.Text, @"\S+\s*"))      // one update per word, like token-by-token streaming
        {
            ct.ThrowIfCancellationRequested();
            await Task.Yield();
            yield return new ChatResponseUpdate(msg.Role, w.Value) { ModelId = modelId };
        }
        yield return new ChatResponseUpdate { FinishReason = response.FinishReason, Contents = [new UsageContent(response.Usage!)], ModelId = modelId };
    }

    public object? GetService(Type serviceType, object? serviceKey = null) =>
        serviceType == typeof(ChatClientMetadata) ? new ChatClientMetadata("fake", null, modelId) :
        serviceType.IsInstanceOfType(this) ? this : null;
    public void Dispose() { }
}

public static class Tokens
{
    /// <summary>FAKE token estimate: about 4 characters per token, the usual English rule of thumb. Real counts come from the provider's Usage.</summary>
    public static int Estimate(IEnumerable<ChatMessage> messages) => messages.Sum(m => (m.Text.Length + 3) / 4 + 4);
    public static int Estimate(string text) => (text.Length + 3) / 4;
}

public sealed class HashingEmbeddingGenerator(int dimensions = 256) : IEmbeddingGenerator<string, Embedding<float>>
{
    public Task<GeneratedEmbeddings<Embedding<float>>> GenerateAsync(IEnumerable<string> values, EmbeddingGenerationOptions? options = null, CancellationToken ct = default)
    {
        var result = new GeneratedEmbeddings<Embedding<float>>(values.Select(v => new Embedding<float>(Embed(v)) { ModelId = "fake-hashing-embeddings" }));
        return Task.FromResult(result);
    }
    float[] Embed(string text)
    {
        var v = new float[dimensions];
        foreach (var word in Words(text)) v[(int)(Fnv(word) % (uint)dimensions)] += 1f;   // stable hash, not string.GetHashCode()
        var norm = MathF.Sqrt(v.Sum(x => x * x));
        if (norm > 0) for (int i = 0; i < v.Length; i++) v[i] /= norm;                    // unit length: cosine = dot product
        return v;
    }
    public static IEnumerable<string> Words(string text) =>
        Regex.Matches(text.ToLowerInvariant(), "[a-z0-9]+").Select(m => m.Value).Where(w => w.Length > 2 && !Stop.Contains(w)).Select(Stem);
    static string Stem(string w) => w.Length > 4 && w.EndsWith('s') ? w[..^1] : w;
    static readonly HashSet<string> Stop = ["the", "and", "for", "are", "with", "that", "this", "you", "can", "how", "what", "does", "from", "your", "not", "but", "has", "have", "into", "when", "which", "its", "our", "use", "was", "will"];
    static uint Fnv(string s) { uint h = 2166136261; foreach (char c in s) { h ^= c; h *= 16777619; } return h; }
    public object? GetService(Type serviceType, object? serviceKey = null) =>
        serviceType == typeof(EmbeddingGeneratorMetadata) ? new EmbeddingGeneratorMetadata("fake", null, "fake-hashing-embeddings", dimensions) :
        serviceType.IsInstanceOfType(this) ? this : null;
    public void Dispose() { }
}

// IChatClient basics with a FAKE, scripted client (no model, no key). The calling code is what you would
// write against Azure OpenAI, OpenAI or Ollama; only the registration line changes.
using FakeAI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;

// The "model": a script that answers from a tiny FAQ and remembers the user's name from history.
Script faq = (messages, options) =>
{
    var last = messages[^1].Text.ToLowerInvariant();
    var name = messages.Where(m => m.Role == ChatRole.User).Select(m => m.Text)
                       .Select(t => t.StartsWith("I am ") ? t[5..].TrimEnd('.') : null).LastOrDefault(n => n is not null);
    string text = last.Contains("refund") ? "Refunds are issued to the original payment method within 5 business days."
                : last.Contains("my name") ? (name is null ? "You have not told me your name." : $"Your name is {name}.")
                : last.StartsWith("i am ") ? "Nice to meet you."
                : "I can answer questions about refunds.";
    if (options?.Temperature is float t) text += $" (temperature {t})";
    return new ChatMessage(ChatRole.Assistant, text);
};

var services = new ServiceCollection();
services.AddChatClient(new FakeChatClient(faq));          // real app: new AzureOpenAIClient(...).GetChatClient("deployment").AsIChatClient()
using var sp = services.BuildServiceProvider();
var chat = sp.GetRequiredService<IChatClient>();

// 1. One call, and everything that comes back besides the text.
ChatResponse r = await chat.GetResponseAsync("How long do refunds take?");
Console.WriteLine($"text:          {r.Text}");
Console.WriteLine($"model:         {r.ModelId}");
Console.WriteLine($"finish reason: {r.FinishReason}");
Console.WriteLine($"usage:         in={r.Usage?.InputTokenCount} out={r.Usage?.OutputTokenCount} total={r.Usage?.TotalTokenCount} (fake estimate)");
Console.WriteLine($"metadata:      provider={chat.GetService<ChatClientMetadata>()?.ProviderName} defaultModel={chat.GetService<ChatClientMetadata>()?.DefaultModelId}");

// 2. The client is stateless: conversation memory is the list of messages YOU send each time.
List<ChatMessage> history = [new(ChatRole.System, "You are a support assistant for Contoso. Answer briefly.")];
foreach (var user in new[] { "I am Priya.", "What is my name?" })
{
    history.Add(new(ChatRole.User, user));
    var reply = await chat.GetResponseAsync(history);
    history.AddMessages(reply);                               // append the assistant message(s) to the history
    Console.WriteLine($"user: {user,-18} assistant: {reply.Text}   [messages sent: {history.Count - 1}, input tokens ~{reply.Usage?.InputTokenCount}]");
}
var fresh = await chat.GetResponseAsync("What is my name?");
Console.WriteLine($"new conversation, same question: {fresh.Text}");

// 3. ChatOptions travel with each request.
var opt = await chat.GetResponseAsync("Tell me about refunds", new ChatOptions { Temperature = 0.2f, MaxOutputTokens = 200 });
Console.WriteLine($"with options: {opt.Text}");
Console.WriteLine($"history roles: {string.Join(", ", history.Select(m => m.Role.Value))}");

text:          Refunds are issued to the original payment method within 5 business days.
model:         fake-model-1
finish reason: stop
usage:         in=11 out=23 total=34 (fake estimate)
metadata:      provider=fake defaultModel=fake-model-1
user: I am Priya.        assistant: Nice to meet you.   [messages sent: 2, input tokens ~25]
user: What is my name?   assistant: Your name is Priya.   [messages sent: 4, input tokens ~42]
new conversation, same question: You have not told me your name.
with options: Refunds are issued to the original payment method within 5 business days. (temperature 0.2)
history roles: system, user, assistant, user, assistant