# Agentic workflows with Microsoft Agent Framework

Use when the task needs tools/function calling, multi-step reasoning, agent loops, or multiple
agents. Built **on top of** Microsoft.Extensions.AI — never hand-roll a tool loop on `IChatClient`.

## Packages

```xml
<PackageReference Include="Microsoft.Extensions.AI" Version="9.*" />
<PackageReference Include="Microsoft.Agents.AI" Version="1.*-*" />  <!-- prerelease: dotnet add --prerelease -->
<PackageReference Include="Azure.AI.OpenAI" Version="2.*" />        <!-- or another MEAI provider -->
<PackageReference Include="Azure.Identity" Version="1.*" />
```

## Guardrails

1. **Framework, not raw loops** — orchestrate with `Microsoft.Agents.AI`; do not loop raw LLM calls
   by hand.
2. **Foundation layer** — build on `Microsoft.Extensions.AI` (`IChatClient`).
3. **Bounded iteration** — set `MaximumIterations` to cap the agent loop and prevent runaway
   execution.
4. **Explicit tools** — define each tool/function with a clear schema and description
   (`AIFunctionFactory.Create`).
5. **Cost ceiling** — enforce a token budget; stop when exceeded.
6. **Observability** — log each step (tool selected, input, output metadata) — never raw sensitive
   content.
7. Prefer a **single agent with tools** over multi-agent unless the task truly needs specialization.

## Minimal shape

```csharp
IChatClient chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient("gpt-4o-2024-08-06").AsIChatClient();

AIAgent agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    Instructions = "Research the topic, then summarize findings.",
    ChatOptions = new ChatOptions
    {
        Tools = [AIFunctionFactory.Create(WebSearch), AIFunctionFactory.Create(TakeNote)],
    },
});

var runOptions = new ChatClientAgentRunOptions { MaximumIterations = 10 };
var result = await agent.RunAsync("Research the .NET 10 release highlights.", options: runOptions);
```

# Classic ML with ML.NET

Use for structured/tabular tasks: classification, regression, clustering, anomaly detection,
recommendation. Deterministic, local, no cloud dependency.

## Packages

```xml
<PackageReference Include="Microsoft.ML" Version="4.*" />
<PackageReference Include="Microsoft.ML.AutoML" Version="0.*" />          <!-- optional: model search -->
<PackageReference Include="Microsoft.Extensions.ML" Version="4.*" />      <!-- PredictionEnginePool for ASP.NET Core -->
```

## Guardrails

1. **Reproducible seed** — always construct `MLContext` with a fixed seed.
2. **Held-out evaluation** — split with `TrainTestSplit`, evaluate on the test set, never on training data.
3. **Report real metrics** — multiclass: MicroAccuracy, MacroAccuracy, LogLoss; binary: AUC, F1;
   regression: RMSE, R².
4. **Thread-safe serving** — in ASP.NET Core use `PredictionEnginePool<TIn,TOut>`, never a singleton
   `PredictionEngine` (it is not thread-safe).
5. Prefer `mlContext.Auto()` (AutoML) for initial trainer/hyperparameter selection.

## Minimal shape

```csharp
var mlContext = new MLContext(seed: 42);

var data = mlContext.Data.LoadFromTextFile<TicketRow>("tickets.csv", hasHeader: true, separatorChar: ',');
var split = mlContext.Data.TrainTestSplit(data, testFraction: 0.2);

var pipeline = mlContext.Transforms.Conversion.MapValueToKey("Label", nameof(TicketRow.Category))
    .Append(mlContext.Transforms.Text.FeaturizeText("SubjectF", nameof(TicketRow.Subject)))
    .Append(mlContext.Transforms.Text.FeaturizeText("DescriptionF", nameof(TicketRow.Description)))
    .Append(mlContext.Transforms.Concatenate("Features", "SubjectF", "DescriptionF", nameof(TicketRow.Priority)))
    .Append(mlContext.MulticlassClassification.Trainers.SdcaMaximumEntropy())
    .Append(mlContext.Transforms.Conversion.MapKeyToValue("PredictedLabel"));

var model = pipeline.Fit(split.TrainSet);
var metrics = mlContext.MulticlassClassification.Evaluate(model.Transform(split.TestSet));
// log metrics.MicroAccuracy, metrics.MacroAccuracy, metrics.LogLoss

// ASP.NET Core endpoint:
builder.Services.AddPredictionEnginePool<TicketRow, TicketPrediction>().FromFile(modelPath);
// inject PredictionEnginePool<TicketRow, TicketPrediction> and call .Predict(input)
```

**Reject LLMs for these tasks.** If asked to use GPT/an LLM for tabular prediction, redirect to
ML.NET with rationale: faster, cheaper, deterministic, no per-call cost.

# GitHub Copilot SDK extensions

Use only for custom developer workflows that must run through the GitHub Copilot agent runtime.
Do not use it as a general LLM client.

## Package

```xml
<PackageReference Include="GitHub.Copilot.SDK" Version="0.3.0" />
```

The SDK is pre-1.0. Pin an exact version and review release notes before each upgrade.

## Guardrails

1. Start and reuse one `CopilotClient`; stop it during application shutdown.
2. Create a bounded session for each workflow and dispose the session after use.
3. Set the working directory, model, system message, and permission handler explicitly.
4. Default permission requests to deny when no user is available.
5. Subscribe to session error, usage, and completion events before sending a prompt.
6. Enforce a timeout and cancellation token, and record token usage without sensitive content.

## Minimal shape

```csharp
var client = new CopilotClient(new CopilotClientOptions());
await client.StartAsync();

await using var session = await client.CreateSessionAsync(sessionConfig);
await session.SendAsync(new MessageOptions { Prompt = prompt });
await client.StopAsync();
```

# LLM integration with Microsoft.Extensions.AI

Use for text generation, summarization, reasoning — single prompt → response, **no tools**. If the
task needs tools/agent loops, use `references/agentic.md` instead.

## Packages

```xml
<PackageReference Include="Microsoft.Extensions.AI" Version="9.*" />
<PackageReference Include="Azure.AI.OpenAI" Version="2.*" />   <!-- or OpenAI / Azure.AI.Inference / OllamaSharp -->
<PackageReference Include="Azure.Identity" Version="1.*" />
<PackageReference Include="Microsoft.ML.Tokenizers" Version="2.*" />  <!-- client-side token budgeting -->
```

## Guardrails

1. **Abstraction, not provider** — depend on `IChatClient`; do not call `Azure.AI.OpenAI` / `OpenAI`
   directly in business logic.
2. **DI registration** — register via `AddChatClient`; never `new` a client in business logic.
3. **Explicit options** — set `Temperature` (0 for factual/deterministic tasks) and
   `MaxOutputTokens` in `ChatOptions`.
4. **Resilience** — wrap with `RetryingChatClient` (or a Polly pipeline) for retry/timeout.
5. **Pinned model** — use a dated version (e.g. `gpt-4o-2024-08-06`), not an unversioned alias.
6. **Safe secrets** — load keys from user-secrets / env / Key Vault. Never hardcode (`sk-...`) keys.
7. **Non-determinism** — output varies even at temperature 0; validate against a schema with a
   graceful fallback (`GetResponseAsync<T>`), and count tokens with `Microsoft.ML.Tokenizers`.

## Minimal shape

```csharp
builder.Services.AddChatClient(sp =>
    new AzureOpenAIClient(new Uri(cfg["Ai:Endpoint"]!), new DefaultAzureCredential())
        .GetChatClient("gpt-4o-2024-08-06").AsIChatClient()
        .AsBuilder()
        .Use(inner => new RetryingChatClient(inner, maxRetries: 3))
        .Build());

var options = new ChatOptions { Temperature = 0f, MaxOutputTokens = 1024 };
var summary = await chatClient.GetResponseAsync(
    [new(ChatRole.System, "Summarize concisely."), new(ChatRole.User, document)], options, ct);
```

# Local LLM inference with OllamaSharp

Use for local or offline prompt-response work when privacy, air-gapped operation, or cloud cost is
the main constraint. Use the same MEAI abstractions as a hosted provider.

## Packages

```xml
<PackageReference Include="Microsoft.Extensions.AI" Version="9.*" />
<PackageReference Include="OllamaSharp" Version="5.*" />
```

## Guardrails

1. Depend on `IChatClient`; keep OllamaSharp behind the MEAI abstraction.
2. Configure the Ollama endpoint and model name; do not hardcode deployment-specific values.
3. Set `Temperature` and `MaxOutputTokens`, and bound prompt size for local memory limits.
4. Add timeout and cancellation handling because model startup and inference can be slow.
5. Verify that the selected model is present before serving traffic.
6. Measure latency and memory on the target hardware; local does not mean free or fast.

## Minimal shape

```csharp
builder.Services.AddChatClient(
    new OllamaApiClient(new Uri(options.Endpoint), options.Model));
```

# ONNX Runtime inference

Use when a trained model is already available in ONNX format and the .NET application only needs
production inference. Train or convert the model outside the application.

## Package

```xml
<PackageReference Include="Microsoft.ML.OnnxRuntime" Version="1.*" />
```

Use the GPU-specific package only when the deployment target and execution provider require it.

## Guardrails

1. Validate model input names, element types, dimensions, and output names at startup.
2. Create and warm one `InferenceSession` through DI; do not reload the model per request.
3. Normalize and tokenize input exactly as the model expects.
4. Dispose inference results and other native-memory-backed values promptly.
5. Bound input sizes and batch sizes, and measure latency and memory on the deployment hardware.
6. Pin and record the model artifact version with its preprocessing contract.

## Minimal shape

```csharp
builder.Services.AddSingleton(_ => new InferenceSession(modelPath));

var input = NamedOnnxValue.CreateFromTensor("input", tensor);
using var results = session.Run([input]);
```

# RAG, embeddings, and document ingestion

Use for semantic search and retrieval-augmented Q&A over documents. Two concerns: **ingestion**
(parse → chunk → embed → store) and **query** (embed question → vector search → ground the answer).

## Packages

```xml
<PackageReference Include="Microsoft.Extensions.AI" Version="9.*" />                       <!-- IEmbeddingGenerator, IChatClient -->
<PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.*" />  <!-- MEVD -->
<PackageReference Include="Microsoft.Extensions.AI.DataIngestion" Version="9.*-*" />       <!-- preview: parse/chunk/embed/upsert -->
<!-- + a vector provider, e.g. pgvector for PostgreSQL, Azure AI Search, Qdrant, Redis -->
```

## Guardrails

1. **Abstractions** — `IEmbeddingGenerator` for embeddings,
   `Microsoft.Extensions.VectorData.Abstractions` (MEVD) for the store, `IChatClient` for generation.
2. **Semantic chunking** — chunk on paragraph/semantic boundaries, not naive fixed-size cuts.
   Use `Microsoft.Extensions.AI.DataIngestion` (or equivalent parse/chunk) for PDFs/markdown.
3. **Relevance threshold** — filter retrieved chunks by a **minimum similarity score**; don't feed
   low-scoring noise to the model.
4. **Source attribution** — track which document chunks contributed to each answer.
5. **Cache embeddings** — persist embeddings; never re-embed the corpus on every query. Batch
   embedding calls during ingestion.

## Minimal query shape (provider-specific pseudocode)

```csharp
var queryEmbedding = await embeddingGenerator.GenerateAsync(question, ct);
var hits = await SearchProviderAsync(queryEmbedding, top: 5, cancellationToken: ct);
var grounded = hits.Where(h => h.Score >= 0.75);   // minimum similarity threshold
// build prompt with the grounded chunks + their source ids for attribution, then IChatClient.GetResponseAsync
```