Microsoft.Maui.Essentials.AI
11.0.0-preview.9.26567.2
Prefix Reserved
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
<PackageReference Include="Microsoft.Maui.Essentials.AI" Version="11.0.0-preview.9.26567.2" />
<PackageVersion Include="Microsoft.Maui.Essentials.AI" Version="11.0.0-preview.9.26567.2" />
<PackageReference Include="Microsoft.Maui.Essentials.AI" />
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"
#:package Microsoft.Maui.Essentials.AI@11.0.0-preview.9.26567.2
#addin nuget:?package=Microsoft.Maui.Essentials.AI&version=11.0.0-preview.9.26567.2&prerelease
#tool nuget:?package=Microsoft.Maui.Essentials.AI&version=11.0.0-preview.9.26567.2&prerelease
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 reportsChatModelCapability.ToolCalling, such asgemini-nano-preview-fast; the default Nano V3 model has no tool support.ChatToolMode.RequireAnyis 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.
RawRepresentationcan carry aCGImage,UIImageorNSImage, and localfile://imageUriContentis 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
- Apple Foundation Models — availability, images, tools, and native bridge.
- Windows AI language models — packaging, readiness, and dependencies.
- Gemini Nano Android — AICore readiness, download, models, and tools.
- Gemini Nano structured output — supported schemas, streaming, tools, and thinking.
- Chat provider contract — shared behavior across providers.
- Chat Playground and Essentials AI sample
- Source and build instructions
| Product | Versions 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. |
-
net10.0
- Microsoft.Extensions.AI.Abstractions (>= 10.4.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.5)
-
net10.0-android36.0
- Microsoft.Extensions.AI.Abstractions (>= 10.4.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.5)
- Xamarin.AndroidX.Lifecycle.Process (>= 2.9.2.1)
- Xamarin.Firebase.Encoders (>= 117.0.0.21)
- Xamarin.Firebase.Encoders.JSON (>= 118.0.1.13)
- Xamarin.Google.Android.DataTransport.TransportApi (>= 4.0.0.3)
- Xamarin.Google.Android.DataTransport.TransportBackendCct (>= 4.0.0.3)
- Xamarin.Google.Android.DataTransport.TransportRuntime (>= 4.0.0.3)
- Xamarin.Google.Guava (>= 33.6.0.1)
- Xamarin.Google.MLKit.Common (>= 118.11.0.3)
- Xamarin.GooglePlayServices.Basement (>= 118.9.0)
- Xamarin.GooglePlayServices.Tasks (>= 118.3.0.1)
- Xamarin.Kotlin.StdLib (>= 2.4.0.1)
- Xamarin.KotlinX.Coroutines.Core (>= 1.11.0.1)
- Xamarin.KotlinX.Coroutines.Guava (>= 1.11.0.1)
- Xamarin.KotlinX.Coroutines.Reactive (>= 1.11.0.1)
-
net10.0-ios26.0
- Microsoft.Extensions.AI.Abstractions (>= 10.4.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.5)
-
net10.0-maccatalyst26.0
- Microsoft.Extensions.AI.Abstractions (>= 10.4.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.5)
-
net10.0-macos26.0
- Microsoft.Extensions.AI.Abstractions (>= 10.4.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.5)
-
net10.0-windows10.0.19041
- Microsoft.Extensions.AI.Abstractions (>= 10.4.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.5)
- Microsoft.WindowsAppSDK.AI (>= 2.4.4)
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 |