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.

<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.

<!-- 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.

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

   var mlContext = new MLContext(seed: 42);

2. Data splitting: Always split into train/test (and optionally validation). Never evaluate on training data:
   csharp

   var split = mlContext.Data.TrainTestSplit(data, testFraction: 0.2);

3. Metrics logging: Always compute and log evaluation metrics appropriate to the task:
   csharp

   var metrics = mlContext.BinaryClassification.Evaluate(predictions);
   logger.LogInformation("AUC: {Auc:F4}, F1: {F1:F4}", metrics.AreaUnderRocCurve, metrics.F1Score);

4. AutoML first: Prefer

   mlContext.Auto()

   for initial model selection, then refine manually.
5. PredictionEngine pooling: In ASP.NET Core, always use the pooled prediction engine — never a singleton:
   csharp

   services.AddPredictionEnginePool<ModelInput, ModelOutput>()
       .FromFile(modelPath);

1. Temperature: Always set explicitly. Use

   0

   for factual/deterministic tasks:
   csharp

   var options = new ChatOptions
   {
       Temperature = 0f,
       MaxOutputTokens = 1024,
   };

2. Structured output: Always parse LLM output into strongly-typed objects with fallback handling:
   csharp

   var result = await chatClient.GetResponseAsync<MySchema>(prompt, options, cancellationToken);

3. Retry logic: Always implement retry with exponential backoff:
   csharp

   services.AddChatClient(builder => builder
       .UseOpenAIChatClient(modelId)
       .Use(new RetryingChatClient(maxRetries: 3)));

4. Cost control: Always estimate and log token usage. Use Microsoft.ML.Tokenizers to count tokens client-side before sending requests so you can enforce budgets proactively. Choose the smallest model tier that meets quality requirements (e.g., gpt-4o-mini before gpt-4o).
5. Secret management: Never hardcode API keys. Use Azure Key Vault, user-secrets, or environment variables:
   csharp

   var apiKey = configuration["AI:ApiKey"]
       ?? throw new InvalidOperationException("AI:ApiKey not configured");

6. Model version pinning: Specify exact model versions to reduce behavioral drift:
   csharp

   // Pin to a specific dated version, not just "gpt-4o"
   var modelId = "gpt-4o-2024-08-06";

1. Use

   Microsoft.Agents.AI

   for all agentic workflows. Do not implement tool dispatch loops or multi-step agent reasoning by hand with

   IChatClient

   . The Agent Framework provides

   ChatClientAgent

   (or

   AgentWorker

   ) which handles the tool call → result → re-prompt cycle with built-in guardrails. All rules below assume you are using

   Microsoft.Agents.AI

   .
2. Iteration limits: Always cap agentic loops to prevent runaway execution:
   csharp

   var settings = new AgentInvokeOptions
   {
       MaximumIterations = 10,
   };

3. Cost ceiling: Implement a token budget per execution and terminate when reached. Use Microsoft.ML.Tokenizers to count prompt and completion tokens locally and compare against the budget before each iteration.
4. Observability: Log non-sensitive metadata for every agent step. Never log raw

   message.Content

   — it may contain user prompts, tool outputs, secrets, or PII that persist in plaintext in central logging systems:
   csharp

   await foreach (var message in agent.InvokeStreamingAsync(history, settings))
   {
       logger.LogDebug("Agent step: Role={Role}, ContentLength={Length}",
           message.Role, message.Content?.Length ?? 0);
   }

5. Tool schemas: Define explicit tool/function schemas with descriptions. Never rely on implicit tool discovery.
6. Simplicity preference: Prefer single-agent with tools over multi-agent unless the task genuinely requires agent collaboration.

1. Embedding caching: Never re-embed the same content on every query. Cache embeddings in the vector store.
2. Chunking strategy: Use semantic chunking (split on paragraph/section boundaries) over fixed-size chunking. Ensure chunks have enough context to be useful on their own.
3. Relevance thresholds: Do not inject low-relevance chunks into context. Set a minimum similarity score:
   csharp

   var results = await vectorStore.SearchAsync(query, new VectorSearchOptions
   {
       Top = 5,
       MinimumScore = 0.75f,
   });

4. Source attribution: Track which chunks contributed to the final response. Include source references in the output.
5. Batch embeddings: Batch embedding API calls where possible to reduce latency and cost.

1. Acknowledge it: Inform the developer that LLM outputs are non-deterministic even at temperature 0 (due to batching, quantization, and model updates).
2. Validate outputs: Implement schema validation and content assertion checks on every LLM response.
3. Graceful degradation: Design a fallback path for when the LLM returns unexpected, malformed, or empty output:
   csharp

   var response = await chatClient.GetResponseAsync<ClassificationResult>(prompt, options);
   if (response is null || !response.IsValid())
   {
       logger.LogWarning("LLM returned invalid response, falling back to rule-based classifier");
       return ruleBasedClassifier.Classify(input);
   }

4. Evaluation harness: For any prompt that will be iterated on, recommend creating a golden dataset and evaluation scaffold to measure prompt quality over time.
5. Model version pinning: Pin to specific dated model versions (e.g.,

   gpt-4o-2024-08-06

   ) to reduce drift between deployments.

1. Connection pooling: Use

   IHttpClientFactory

   and DI-managed clients for all external services.
2. Response caching: Cache repeated or similar queries. Consider semantic caching for LLM responses where appropriate.
3. Streaming: Use

   IAsyncEnumerable

   for LLM responses in user-facing scenarios to reduce time-to-first-token:
   csharp

   await foreach (var update in chatClient.GetStreamingResponseAsync(prompt, options))
   {
       yield return update.Text;
   }

4. Health checks: Implement health checks for external AI service dependencies:
   csharp

   services.AddHealthChecks()
       .AddCheck<OpenAIHealthCheck>("openai");

5. ML.NET prediction pooling: In web applications, always use

   PredictionEnginePool<TIn, TOut>

   , never a single

   PredictionEngine

   instance (it is not thread-safe).

1. Build the project and verify no warnings:
   bash

   dotnet build -c Release -warnaserror

2. Run tests, including integration tests that validate AI/ML behavior:
   bash

   dotnet test -c Release

3. For ML.NET pipelines, verify that evaluation metrics meet the project's quality bar and that the model can be serialized and loaded correctly.
4. For LLM integrations, verify that structured output parsing handles both valid and malformed responses.
5. For RAG pipelines, verify that retrieval returns relevant results and that irrelevant chunks are filtered out.

• Technology selection follows the decision tree — LLMs are not used for tasks ML.NET handles
• All AI/ML services are registered via dependency injection
• Configuration uses

  IOptions<T>

  pattern — no hardcoded values
• API keys are loaded from secure sources — not in source code or committed config files
• ML.NET pipelines set a random seed and split data for evaluation
• LLM calls set temperature, max tokens, and retry logic explicitly
• Agentic workflows have iteration limits and cost ceilings
• RAG pipelines implement chunking, relevance thresholds, and source attribution
• Non-deterministic outputs have validation and fallback paths

• dotnet build -c Release -warnaserror

  completes cleanly