technology-selection

.NET AI and Machine Learning

Inputs

Workflow

Step 1: Classify the task using the decision tree

Evaluate the developer's task against this decision tree and select the appropriate technology. State which branch applies and why.

Critical rule: Do NOT use an LLM for tasks that ML.NET handles well (classification on tabular data, regression, clustering). LLMs are slower, more expensive, and non-deterministic for these tasks.

Step 1b: Select the correct library layer

After identifying the task type, select the right library layer. These libraries form a stack — each builds on the one below it. Using the wrong layer is a major source of non-deterministic agent behavior.

Decision rules for library selection

1. Start with MEAI. Every AI integration begins with Microsoft.Extensions.AI for the IChatClient / IEmbeddingGenerator abstractions. This ensures provider-swappability and testability.

2. Add a provider SDK (OpenAI, Azure.AI.OpenAI) as the concrete implementation behind MEAI. Do not call the provider SDK directly in business logic — always go through the MEAI abstraction.

3. Use Agent Framework (Microsoft.Agents.AI) for any task that involves tools or agents. If the task is a single prompt → response with no tool calling, MEAI is sufficient. You MUST use Microsoft.Agents.AI when any of these apply:

   • Tool/function calling (agent decides which tools to invoke)
   • Multi-step reasoning with state carried across turns
   • Agentic loops that iterate until a goal is met
   • Multi-agent collaboration with handoff protocols
   • Graph-based or durable workflows

   Do not implement these patterns by hand with IChatClient — the Agent Framework provides iteration limits, observability, and tool dispatch that are error-prone to reimplement.

4. Add Copilot SDK only when building Copilot extensions. Use GitHub.Copilot.SDK when the goal is to build a custom agent or tool that runs inside the GitHub Copilot platform (CLI, IDE, or Copilot Chat). This is not a general-purpose LLM orchestration library — it is specifically for Copilot extensibility.

5. Never skip layers. Do not use Agent Framework without MEAI underneath. Do not call HttpClient to OpenAI alongside MEAI in the same workflow. Each layer depends on the one below it.

Step 2: Select packages and set up the project

Install only the packages needed for the selected technology branch. Do not mix competing abstractions.

Classic ML packages

<PackageReference Include="Microsoft.ML" Version="4.*" />
<PackageReference Include="Microsoft.ML.AutoML" Version="0.*" />
<!-- Only if custom numerical work is needed: -->
PackageReference Include="System.Numerics.Tensors" Version="10.*"
<PackageReference Include="MathNet.Numerics" Version="5.*" />
<!-- Only for data exploration: -->
<PackageReference Include="Microsoft.Data.Analysis" Version="0.*" />

Do NOT use Accord.NET — it is archived and unmaintained.

Modern AI packages

<!-- Always start with the abstraction layer -->
<PackageReference Include="Microsoft.Extensions.AI" Version="9.*" />

<!-- Orchestration (agents, workflows, tools, memory) — prerelease; use dotnet add package Microsoft.Agents.AI --prerelease -->
<PackageReference Include="Microsoft.Agents.AI" Version="1.*-*" />

<!-- Cloud LLM provider (pick one) -->
<PackageReference Include="Azure.AI.OpenAI" Version="2.*" />
<!-- OR -->
<PackageReference Include="OpenAI" Version="2.*" />

<!-- Client-side token counting for cost management -->
    <PackageReference Include="Microsoft.ML.Tokenizers" Version="2.*" 

<!-- Local LLM inference -->
<PackageReference Include="OllamaSharp" Version="5.*" />

<!-- Custom model inference -->
<PackageReference Include="Microsoft.ML.OnnxRuntime" Version="1.*" />

<!-- Vector store abstraction -->
<PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.*" />

<!-- Document ingestion, chunking, and vector store loading (preview) -->
<PackageReference Include="Microsoft.Extensions.AI.DataIngestion" Version="9.*-*" />

<!-- Copilot platform extensibility -->
<PackageReference Include="GitHub.Copilot.SDK" Version="1.*" />

Stack coherence rule: Never mix raw SDK calls (HttpClient to OpenAI) with Microsoft.Extensions.AI, Microsoft Agent Framework, or Copilot SDK in the same workflow. Pick one abstraction layer per workflow boundary and commit to it. See Step 1b for the layering rules.

Register services with dependency injection

All AI/ML services must be registered via DI. Never instantiate clients directly in business logic.

// Configuration via IOptions<T>
services.Configure<AiOptions>(configuration.GetSection("AI"));

// Register the AI client through the abstraction
services.AddChatClient(builder => builder
    .UseOpenAIChatClient("gpt-4o-mini-2024-07-18"));

Step 3: Implement with guardrails

Apply the guardrails for the selected technology branch. Every generated implementation must follow these rules.

Classic ML guardrails

1. Reproducibility: Always set a random seed in the ML context:

   var mlContext = new MLContext(seed: 42);
   

2. Data splitting: Always split into train/test (and optiona

Content truncated.