Microsoft.Maui.Essentials.AI 11.0.0-preview.9.26567.2

Prefix Reserved
This is a prerelease version of Microsoft.Maui.Essentials.AI.
dotnet add package Microsoft.Maui.Essentials.AI --version 11.0.0-preview.9.26567.2
                    
NuGet\Install-Package Microsoft.Maui.Essentials.AI -Version 11.0.0-preview.9.26567.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Microsoft.Maui.Essentials.AI" Version="11.0.0-preview.9.26567.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Microsoft.Maui.Essentials.AI" Version="11.0.0-preview.9.26567.2" />
                    
Directory.Packages.props
<PackageReference Include="Microsoft.Maui.Essentials.AI" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Microsoft.Maui.Essentials.AI --version 11.0.0-preview.9.26567.2
                    
#r "nuget: Microsoft.Maui.Essentials.AI, 11.0.0-preview.9.26567.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Microsoft.Maui.Essentials.AI@11.0.0-preview.9.26567.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Microsoft.Maui.Essentials.AI&version=11.0.0-preview.9.26567.2&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Microsoft.Maui.Essentials.AI&version=11.0.0-preview.9.26567.2&prerelease
                    
Install as a Cake Tool

Microsoft.Maui.Essentials.AI

On-device chat and text embeddings for .NET MAUI through Microsoft.Extensions.AI, backed by Apple Intelligence, Apple NaturalLanguage, Windows AI, and Gemini Nano. No cloud service is used.

Experimental: this package ships as a preview. APIs may change.

Platform support

Platform Chat (IChatClient) Image input Embeddings (IEmbeddingGenerator)
iOS 26+ Apple Intelligence, with tools and structured responses OS 27+ NaturalLanguage, iOS 13+
Mac Catalyst 26+ Apple Intelligence, with tools and structured responses OS 27+ NaturalLanguage, Mac Catalyst 13.1+
macOS 26+ Apple Intelligence, with tools and structured responses OS 27+ NaturalLanguage, macOS 10.15+
Windows 11 24H2+ Windows AI on Copilot+ hardware, with structured responses Not supported Not supported
Android API 26+ Gemini Nano on supported AICore hardware, with structured responses; tools on capable models In-memory images Not supported

Requires .NET 10 and the matching MAUI workloads.

Install

dotnet add package Microsoft.Maui.Essentials.AI --prerelease

Set up a chat client

Register the client for the current platform, and check that its model is ready before offering chat. Generation never downloads a model.

Apple

Apple Intelligence must be available and enabled. Image input, token usage and explicit tool modes need OS 27+ and a native bridge built with Xcode 27+. Response and tool schemas that allow null values need OS 26.4+.

using Microsoft.Extensions.AI;
using Microsoft.Maui.Essentials.AI;

#if IOS || MACCATALYST || MACOS
if (OperatingSystem.IsIOSVersionAtLeast(26) ||
    OperatingSystem.IsMacCatalystVersionAtLeast(26) ||
    OperatingSystem.IsMacOSVersionAtLeast(26))
{
    builder.Services.AddSingleton<IChatClient>(new AppleIntelligenceChatClient());
}
#endif
var status = await AppleIntelligenceChatClient.GetModelStatusAsync();
if (status.Availability != ChatModelAvailability.Available)
    Console.WriteLine(status.Availability);

Windows

The app must be MSIX-packaged, declare the systemAIModels capability, and use a compatible Windows App SDK with the applicable model-access configuration.

#if WINDOWS
if (OperatingSystem.IsWindowsVersionAtLeast(10, 0, 26100))
{
    builder.Services.AddSingleton<IChatClient>(new WindowsAIChatClient());
}
#endif
var status = await WindowsAIChatClient.GetModelStatusAsync();
if (status.Availability == ChatModelAvailability.NotReady)
    await WindowsAIChatClient.EnsureReadyAsync(cancellationToken);

Android

#if ANDROID
if (OperatingSystem.IsAndroidVersionAtLeast(26))
{
    builder.Services.AddSingleton<IChatClient>(new GeminiNanoChatClient());
}
#endif

Download the model only after an explicit app or user decision. PrepareModelAsync waits for the download to finish; use DownloadModelAsync to show ML Kit's progress, then query the status again.

var status = await GeminiNanoChatClient.GetModelStatusAsync(cancellationToken);
if (status.Availability == ChatModelAvailability.NotReady)
    await GeminiNanoChatClient.PrepareModelAsync(cancellationToken);

The status lists the model's capabilities, such as ChatModelCapability.StructuredOutput and ChatModelCapability.ToolCalling. Set MaxOutputTokens for longer responses: when it is unset, the default Nano V3 model stops after about 40 tokens.

Chat

Use the injected IChatClient:

var response = await chat.GetResponseAsync("Plan a day trip to Tokyo");
Console.WriteLine(response.Text);

await foreach (var update in chat.GetStreamingResponseAsync("Suggest a walking route"))
    Console.Write(update.Text);

Structured responses

Use GetResponseAsync<T> to generate a schema and deserialize a typed response. For trimmed and AOT apps, pass source-generated JsonSerializerOptions:

using System.ComponentModel;
using System.Text.Json.Serialization;

var response = await chat.GetResponseAsync<TripSuggestion>(
    "Suggest a day trip near Seattle.",
    AppJsonContext.Default.Options);

Console.WriteLine($"{response.Result.Destination}: {response.Result.Reason}");

[Description("A day trip recommendation.")]
public sealed record TripSuggestion(
    [property: Description("The destination name.")] string Destination,
    [property: Description("A short reason to visit.")] string Reason);

[JsonSerializable(typeof(TripSuggestion))]
internal partial class AppJsonContext : JsonSerializerContext;

Each platform supports its own subset of JSON Schema; see the platform guides. Streamed structured responses can arrive as one update when the platform doesn't report partial output.

On Android, the selected model must report structured output support. As with OpenAI, the schema root must be an object and the JSON is returned unchanged. Schema-free JSON is not supported. Structured output works with streaming, tools and thinking; see the structured output guide for supported keywords.

Tools

Supply AIFunction tools through ChatOptions. Set ChatOptions.ToolMode to ChatToolMode.None to disable them for a request.

using System.ComponentModel;

var options = new ChatOptions
{
    Tools = [AIFunctionFactory.Create(GetWeather, name: nameof(GetWeather))],
};
var weather = await chat.GetResponseAsync("What's the weather in Boston?", options);
Console.WriteLine(weather.Text);

[Description("Get demonstration weather for a city.")]
static string GetWeather(
    [Description("The city to check.")] string city) => $"{city}: sunny.";
  • Apple runs the tools itself and returns their results to the model.
  • Android returns the model's tool calls, so wrap the client to run them: chat.AsBuilder().UseFunctionInvocation().Build(). Tools need a model that reports ChatModelCapability.ToolCalling, such as gemini-nano-preview-fast; the default Nano V3 model has no tool support. ChatToolMode.RequireAny is not supported. See the tool-calling guide.
  • Windows doesn't support tools.

Image input

Add images as DataContent parts:

var message = new ChatMessage(ChatRole.User,
[
    new TextContent("Describe this photo."),
    new DataContent(pngBytes, "image/png"),
]);
var response = await chat.GetResponseAsync([message]);
  • Apple needs OS 27+ and a ready vision-capable model; on OS 26 image requests throw. RawRepresentation can carry a CGImage, UIImage or NSImage, and local file:// image UriContent is supported. Remote URLs are rejected rather than fetched.
  • Android accepts in-memory images.

Token usage

var response = await chat.GetResponseAsync("Summarize this text.");
Console.WriteLine($"Input: {response.Usage?.InputTokenCount}");
Console.WriteLine($"Output: {response.Usage?.OutputTokenCount}");

Usage is per request; add it up with UsageDetails.Add. Streams end with a UsageContent update, and ToChatResponseAsync() collects it into ChatResponse.Usage.

  • Apple reports input, output, cached-input, reasoning and total counts on OS 27+, and none on OS 26.
  • Android reports input tokens.
  • Windows doesn't report usage.

Telemetry

Wrap any client with the Microsoft.Extensions.AI OpenTelemetry middleware:

var instrumentedChat = chat.AsBuilder()
    .UseOpenTelemetry(
        sourceName: "MyApp.AI",
        configure: telemetry => telemetry.EnableSensitiveData = false)
    .Build();

Configure listeners or exporters for the MyApp.AI activity source and meter. The middleware records request timing, time to first chunk and between chunks, model metadata and token usage. Fully enumerate streams to capture final usage. With EnableSensitiveData = false, prompts and responses are excluded.

For Apple tool diagnostics, pass an ILoggerFactory to the client: lifecycle logs use Debug, and tool arguments and results use Trace.

Embeddings

using var generator = new NLEmbeddingGenerator();
var embeddings = await generator.GenerateAsync(["sunset beach", "mountain hiking"]);

The default generator uses English sentence embeddings. Pass an NLLanguage to the constructor for another supported language, or wrap an existing NLEmbedding. The language's model asset must be installed.

Guides and samples

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-android36.0 is compatible.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-ios26.0 is compatible.  net10.0-maccatalyst was computed.  net10.0-maccatalyst26.0 is compatible.  net10.0-macos was computed.  net10.0-macos26.0 is compatible.  net10.0-tvos was computed.  net10.0-windows was computed.  net10.0-windows10.0.19041 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
11.0.0-preview.9.26567.2 84 11/17/2026
11.0.0-preview.8.26555.2 366 11/6/2026
11.0.0-preview.8.26531.2 227 10/31/2026
11.0.0-preview.7.26526.5 110 10/26/2026
11.0.0-preview.7.26512.5 259 10/12/2026
11.0.0-preview.6.26360.8 2,180 7/14/2026
11.0.0-preview.5.26358.7 99 7/8/2026
11.0.0-preview.5.26304.4 108 6/9/2026
11.0.0-preview.4.26230.3 110 5/12/2026
11.0.0-preview.3.26203.7 107 4/14/2026
11.0.0-preview.2.26152.10 121 3/10/2026
10.0.80-preview.1.26319.4 638 6/24/2026
10.0.71-preview.1.26305.4 112 6/10/2026
10.0.70-preview.1.26269.8 440 5/21/2026
10.0.60-preview.1.26227.7 120 4/29/2026
10.0.51-preview.1.26168.3 366 3/25/2026
10.0.50-preview.1.26158.1 753 3/10/2026