DEV Community: Lukas Walter

Build and deploy an MCP server with .NET and Azure Container Apps

Lukas Walter — Mon, 15 Jun 2026 15:30:00 +0000

MCP servers do not have to be local stdio processes. If you want a tool surface that can run as a normal HTTP service, scale like an app, and be reachable from a separate client, Streamable HTTP is the practical transport to look at.

Terminology note: current MCP specs call this transport Streamable HTTP. It replaced the older HTTP+SSE transport, but it can still use Server-Sent Events (SSE) when the server streams messages back to the client.

We will build a small MCP server in C# with the official MCP .NET SDK, run it locally, containerize it, deploy it to Azure Container Apps, and call it from a C# client.

Repository: MCP Server on Azure Container Apps with C# and .NET

The sample exposes three tools:

echo: returns a message
add: adds two integers
server_time: returns the server time for a supplied time zone

The sample is intentionally small. It does not try to become a production agent platform. It gets you from zero to a deployed MCP endpoint, with enough structure that you can replace the demo tools with your own application logic.

Prerequisites

You need:

.NET 10 SDK
Docker
Azure CLI
An Azure subscription
Optional: Node.js if you want to test with the MCP Inspector

The project uses:

ModelContextProtocol.AspNetCore for the server
ModelContextProtocol for the client
Streamable HTTP transport
Azure Container Apps for hosting

Project structure

The repository is split into a server, a client, and a small test project:

McpAzureContainerAppsDemo/
  McpAzureContainerAppsDemo.slnx
  Directory.Build.props
  Directory.Packages.props
  src/
    McpAzureContainerAppsDemo.Server/
      Program.cs
      Dockerfile
      Configuration/
      Security/
      Services/
      Tools/
    McpAzureContainerAppsDemo.Client/
      Program.cs
      Configuration/
      Rendering/
  tests/
    McpAzureContainerAppsDemo.Server.Tests/

The MCP-specific code stays small. Most of the actual behavior lives in normal C# services.

That is the pattern I prefer for demos like this: keep the protocol wiring thin and put the business logic somewhere testable.

Create the projects

Start with a solution, a web project for the server, a console project for the client, and an xUnit test project:

mkdir McpAzureContainerAppsDemo
cd McpAzureContainerAppsDemo

dotnet new sln -n McpAzureContainerAppsDemo

mkdir -p src tests
dotnet new web -n McpAzureContainerAppsDemo.Server -o src/McpAzureContainerAppsDemo.Server --framework net10.0
dotnet new console -n McpAzureContainerAppsDemo.Client -o src/McpAzureContainerAppsDemo.Client --framework net10.0
dotnet new xunit -n McpAzureContainerAppsDemo.Server.Tests -o tests/McpAzureContainerAppsDemo.Server.Tests --framework net10.0

Add the projects to the solution:

dotnet sln add \
  src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj \
  src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj \
  tests/McpAzureContainerAppsDemo.Server.Tests/McpAzureContainerAppsDemo.Server.Tests.csproj

Then add the MCP packages:

dotnet add src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj package ModelContextProtocol.AspNetCore
dotnet add src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj package ModelContextProtocol
dotnet add tests/McpAzureContainerAppsDemo.Server.Tests/McpAzureContainerAppsDemo.Server.Tests.csproj reference src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj

If you cloned the repository, you can skip this setup. The packages are already referenced centrally in Directory.Packages.props.

Register the MCP server

The server is a regular ASP.NET Core app.

In Program.cs, the MCP server is added to the service collection, configured with Streamable HTTP, and mapped to /mcp:

builder.Services
    .AddMcpServer(options =>
    {
        options.ServerInfo = new()
        {
            Name = "mcp-azure-container-apps-demo",
            Version = "1.0.0"
        };
    })
    .WithHttpTransport(options => options.Stateless = true)
    .WithToolsFromAssembly();

app.MapMcp("/mcp");

The useful detail is WithToolsFromAssembly().

Instead of manually registering every tool, the SDK discovers tool classes and methods through attributes. That keeps the server startup small and moves tool definitions into their own files.

The sample also adds two regular HTTP endpoints:

app.MapGet("/", (IOptions<McpServerSettings> options) => Results.Ok(new
{
    service = options.Value.Name,
    mcpEndpoint = "/mcp",
    health = "/health"
}));

app.MapGet("/health", () => Results.Ok(new
{
    status = "ok",
    utc = TimeProvider.System.GetUtcNow()
}));

/health is useful for Container Apps health checks and basic smoke testing.

Add tools with attributes

The tools live in Tools/DemoTools.cs.

The class is marked with [McpServerToolType], and each exposed method is marked with [McpServerTool]:

[McpServerToolType]
public sealed class DemoTools(
    CalculatorService calculator,
    ServerTimeService serverTime,
    ILogger<DemoTools> logger)
{
    [McpServerTool(Name = "echo", ReadOnly = true, Idempotent = true)]
    [Description("Returns the message supplied by the caller.")]
    public string Echo(string message)
    {
        logger.LogInformation("Echo tool invoked.");
        return message;
    }

    [McpServerTool(Name = "add", ReadOnly = true, Idempotent = true)]
    [Description("Adds two 32-bit integers and returns the sum.")]
    public int Add(int left, int right) =>
        calculator.Add(left, right);
}

Tool methods can still call normal injected services.

For example, the add tool does not do arithmetic directly in the tool method. It calls a CalculatorService:

public sealed class CalculatorService
{
    public int Add(int left, int right) => checked(left + right);
}

That makes the behavior easy to test without going through MCP at all.

For the server_time tool, the service uses TimeProvider so tests can supply a fixed clock:

public sealed class ServerTimeService(TimeProvider timeProvider, ILogger<ServerTimeService> logger)
{
    public ServerTimeResult GetTime(string? timeZoneId)
    {
        string resolvedTimeZoneId = string.IsNullOrWhiteSpace(timeZoneId)
            ? "UTC"
            : timeZoneId;

        TimeZoneInfo timeZone = TimeZoneInfo.FindSystemTimeZoneById(resolvedTimeZoneId);
        DateTimeOffset utcNow = timeProvider.GetUtcNow();
        DateTimeOffset localTime = TimeZoneInfo.ConvertTime(utcNow, timeZone);

        logger.LogDebug("Resolved server time for timezone {TimeZoneId}.", timeZone.Id);
        return new(timeZone.Id, utcNow, localTime);
    }
}

This is a useful split: tools are the integration layer, services are the behavior.

Run the server locally

Start the server:

dotnet run --project src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj --launch-profile http

The sample listens on:

http://localhost:8080

Check the health endpoint:

curl http://localhost:8080/health

You should get a small JSON response with status and utc.

Call the MCP server from C

The client uses the same MCP SDK, but with the client package.

The transport is configured for Streamable HTTP:

var transportOptions = new HttpClientTransportOptions
{
    Name = "mcp-azure-container-apps-demo-client",
    Endpoint = settings.ServerUrl,
    TransportMode = HttpTransportMode.StreamableHttp,
    AdditionalHeaders = settings.CreateHeaders()
};

await using var transport = new HttpClientTransport(transportOptions, loggerFactory);
await using McpClient client = await McpClient.CreateAsync(transport, loggerFactory: loggerFactory);

Then the client lists available tools and calls two of them:

IList<McpClientTool> tools = await client.ListToolsAsync();

CallToolResult addResult = await client.CallToolAsync(
    "add",
    new Dictionary<string, object?>
    {
        ["left"] = 40,
        ["right"] = 2
    });

Run it against the local server:

dotnet run --project src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj -- \
  --url http://localhost:8080/mcp \
  --time-zone Europe/Berlin

You should see the tool list, the result of add, and a structured result from server_time.

Add simple API-key protection

For a public HTTP endpoint, even a demo should not leave the MCP endpoint completely open by accident.

This sample uses a very small API-key middleware. It protects /mcp when McpServer__ApiKey is configured and leaves /health unauthenticated:

private static bool RequiresApiKey(PathString path, string? configuredApiKey) =>
    path.StartsWithSegments("/mcp", StringComparison.OrdinalIgnoreCase)
    && !string.IsNullOrWhiteSpace(configuredApiKey);

Run the server with a local key:

McpServer__ApiKey=local-dev-key \
dotnet run --project src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj --launch-profile http

Then pass the same key to the client:

dotnet run --project src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj -- \
  --url http://localhost:8080/mcp \
  --api-key local-dev-key

The client sends the key as an X-Api-Key header.

For production, I would not stop here. I would look at Microsoft Entra ID, managed identity, stricter network boundaries, logging, and proper secret management. For a minimal deployable sample, an environment-driven key keeps the flow understandable.

Inspect with MCP Inspector

You can also test the server with the MCP Inspector:

npx @modelcontextprotocol/inspector

Use Streamable HTTP and connect to:

http://localhost:8080/mcp

If API-key protection is enabled, add this header:

X-Api-Key: local-dev-key

This is useful when you want to inspect the tool schema without writing client code first.

Containerize the server

The Dockerfile uses a normal multi-stage .NET build:

One repo-specific detail: the sample repository uses Directory.Build.props and Directory.Packages.props. If you followed the manual dotnet new steps and kept package versions in the project files, remove COPY Directory.Build.props Directory.Packages.props ./ from the Dockerfile. Do not replace those files with empty placeholders, because MSBuild expects valid XML.

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

COPY Directory.Build.props Directory.Packages.props ./
COPY src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj src/McpAzureContainerAppsDemo.Server/
RUN dotnet restore src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj

COPY src/McpAzureContainerAppsDemo.Server/ src/McpAzureContainerAppsDemo.Server/
RUN dotnet publish src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj \
    --configuration Release \
    --no-restore \
    --output /app/publish

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
ENV ASPNETCORE_URLS=http://0.0.0.0:8080
EXPOSE 8080
USER $APP_UID
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "McpAzureContainerAppsDemo.Server.dll"]

Build the image from the repository root:

docker build -f src/McpAzureContainerAppsDemo.Server/Dockerfile -t mcp-aca-demo .

Run it locally:

docker run --rm -p 8080:8080 mcp-aca-demo

Or run it with API-key protection:

docker run --rm -p 8080:8080 \
  -e McpServer__ApiKey=local-dev-key \
  mcp-aca-demo

At this point, the server is a containerized ASP.NET Core app exposing /mcp.

That is why Azure Container Apps fits this kind of demo. You do not need a special hosting model for MCP. You can deploy a regular container and let the platform handle ingress, revisions, scaling, and environment variables.

Deploy to Azure Container Apps

az login

export RESOURCE_GROUP=mcp-aca-demo-rg
export LOCATION=westeurope
export APP_NAME=mcp-aca-demo-$RANDOM
export ENVIRONMENT_NAME=mcp-aca-demo-env
export MCP_API_KEY="$(openssl rand -base64 32)"

If this is the first time your subscription uses these services, register the required resource providers:

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights
az provider register --namespace Microsoft.ContainerRegistry

Wait until Azure Container Registry is registered:

az provider show \
  --namespace Microsoft.ContainerRegistry \
  --query registrationState \
  --output tsv

Continue when the command prints:

Registered

Create the resource group:

az group create \
  --name "$RESOURCE_GROUP" \
  --location "$LOCATION"

Deploy from local source:

# This builds the image and creates an Azure Container Registry (ACR)
# in the resource group if one is needed.
az containerapp up \
  --name "$APP_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --location "$LOCATION" \
  --environment "$ENVIRONMENT_NAME" \
  --source . \
  --ingress external \
  --target-port 8080 \
  --env-vars McpServer__ApiKey="$MCP_API_KEY"

The settings that matter here are:

--source .: build and deploy from the local repository
--ingress external: expose the app publicly
--target-port 8080: match the port used by the container
--env-vars McpServer__ApiKey=...: pass the API key into the app configuration

Get the public URL:

export MCP_FQDN="$(az containerapp show \
  --name "$APP_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --query properties.configuration.ingress.fqdn \
  --output tsv)"

echo "https://$MCP_FQDN/mcp"

Then call the deployed MCP server:

dotnet run --project src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj -- \
  --url "https://$MCP_FQDN/mcp" \
  --api-key "$MCP_API_KEY" \
  --time-zone Europe/Berlin

If everything is wired correctly, the client behaves the same way as it did locally. It lists tools, calls add, and calls server_time.

That is the practical value of this setup: once the MCP server is exposed over Streamable HTTP, the local and deployed client flow look almost identical.

Cleanup

When you are done, remove the resource group:

az group delete \
  --name "$RESOURCE_GROUP" \
  --yes \
  --no-wait

What I would change for a real system

This repository is a demo. I would change a few things before using the same shape in production.

First, I would replace the static API key with a stronger authentication and authorization model. MCP is a tool boundary. If a tool can read or mutate real data, access control matters.

Second, I would add proper observability. At minimum, I would want logs around tool calls, failures, request IDs, latency, and downstream dependencies. For real operations, OpenTelemetry and the Aspire dashboard are useful places to start.

Third, I would make the tool contract boring and explicit. Clear names, narrow parameters, validation, and predictable errors matter more than clever tool descriptions.

Fourth, I would add integration tests around the HTTP surface. Unit tests are enough for the arithmetic and time services, but the /mcp endpoint, headers, and deployment configuration need their own checks once the sample grows.

Takeaway

You can build and deploy a remote MCP server in .NET without much ceremony.

The flow is:

Create a normal ASP.NET Core app.
Add ModelContextProtocol.AspNetCore.
Register MCP with Streamable HTTP.
Expose tools with attributes.
Keep tool behavior in regular services.
Containerize the server.
Deploy it to Azure Container Apps.
Call it from a C# MCP client.

The add tool is just there to prove the path works. The useful part is the hosting model.

Once MCP runs as a regular HTTP service, it fits naturally into the same deployment path many .NET teams already use: container image, environment variables, ingress, health endpoint, and a small client that points at /mcp.

Use this shape when you need a remote MCP tool service that behaves like a normal .NET web app and can be called from clients outside the host machine.

Do not use the sample as-is when tools can access production data, mutate state, or need user-level authorization. Add real authentication, tighter network boundaries, observability, and integration tests first.

Microsoft Agent Framework Workflows: When to Use Them and When to Stay in C#

Lukas Walter — Thu, 11 Jun 2026 15:30:00 +0000

This is Part 12 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

In the previous article, we looked at agents as tools.
A coordinator agent could delegate work to focused specialist agents without exposing every low-level tool directly.

Before that, we looked at manual multi-agent routing.
A small intent agent returned structured output, and normal C# code decided which specialist agent should run.

Both patterns are useful because they keep orchestration close to the application.
But Microsoft Agent Framework also includes a real workflow engine.
It has executors, edges, graph-based orchestration, streaming events, handoffs, checkpointing, and human-in-the-loop scenarios.

That is powerful.
It is also not free.

Just because the framework provides a workflow engine does not mean every multi-agent interaction should become a workflow graph.
In production systems, the best architecture is often the smallest abstraction that makes the system understandable and reliable.

My rule is simple:

Microsoft Agent Framework workflows are useful when the process itself needs to be explicit, observable, resumable, and long-running.
For simple orchestration, normal C# code is often the better choice.

Why Workflows Exist

A workflow makes orchestration explicit.

Instead of hiding the process inside ad-hoc method calls, the process becomes a model.
The model is a graph.
The graph contains units of work and connections between them.

That graph can represent:

sequential execution
branching
parallel execution
fan-out and fan-in
handoffs between agents
human input
long-running processes
events emitted while the process runs
checkpointing and resumption

This is a different abstraction from a single agent call.

An agent decides dynamically what to do based on its instructions, tools, and conversation context.
A workflow defines a process outside the model.
Agents can be steps inside that process, but the process itself is controlled by the workflow.

That distinction matters.

If you are building a document review flow, a support escalation flow, or an approval process that may pause and resume later, the workflow is not just plumbing.
It is part of the system.
You may need to inspect it, persist it, test it, version it, and explain it to other people.

That is where a workflow engine becomes useful.

But there is a cost.
A workflow graph introduces more setup code, more types, more event handling, and another layer between the application code and the thing that happens.
For complex systems, that cost can be worth paying.
For small flows, it can make the system harder to read.

Executors and Edges

The two basic building blocks are executors and edges.

An executor is a unit of work.
It receives input, runs logic, and produces output or events.

An executor can wrap:

deterministic C# code
an agent call
a tool call
validation logic
a transformation step
a human approval request
another piece of process logic

In agentic workflows, many executors are either agents or agent-driven steps.
For example, one executor might call a document summarizer agent.
Another executor might validate the generated summary.
Another executor might wait for a human reviewer.

Edges define how data moves between executors.
They are the connections in the graph.

An edge can represent:

a direct connection from one step to the next
conditional routing
switch-like branching
fan-out to multiple steps
fan-in back into an aggregation step

This is where the workflow engine adds value.
The control flow becomes visible in the workflow definition.
You can look at the graph to see which steps can occur and which transitions are allowed.

Executors and edges are powerful because they turn orchestration into a model.
But once orchestration becomes a model, you also pay the cost of maintaining that model.

Four Workflow-Related Patterns

Several workflow-related patterns show up quickly in real applications.
Some are orchestration patterns.
Others, such as human-in-the-loop, are process capabilities.

The important part is not the label.
The important part is whether the process benefits from being modeled explicitly.

The examples are intentionally simplified.
The point is the orchestration shape, not the exact API surface.

Sequential Workflows

A sequential workflow passes the output of one step to the next.

For example:

One agent summarizes a legal document.
Another agent translates the summary into French.
A final step formats the result for a user.

As a workflow, this is a pipeline.
Each step depends on the previous step.
In a simple pipeline, the result of one executor can become the input for the next executor. In Agent Framework sequential agent orchestration, the next agent may also receive conversation context depending on how the orchestration is configured.

That is a valid workflow shape.
But for two or three deterministic steps, normal C# may be clearer:

AgentResponse summary = await summarizerAgent.RunAsync(
    documentText,
    cancellationToken: cancellationToken);

AgentResponse translation = await translatorAgent.RunAsync(
    $"Translate this summary to French:\n\n{summary.Text}",
    cancellationToken: cancellationToken);

string formatted = formatter.Format(translation.Text);

There is nothing wrong with this.
It is readable from top to bottom.
It is easy to test.
It is easy to debug.

The workflow version starts to pay off when the sequence itself matters operationally:

You need to show progress for each step
You need to retry or resume from a later step
You need to audit which step produced which output
You expect the pipeline to grow
Non-trivial branches will appear between steps

Concurrent Workflows

A concurrent workflow sends the same input to multiple agents or steps at the same time.

For example, a legal document could be processed by three agents:

One checks legal risk
One checks spelling and grammar
One extracts key obligations

This can reduce latency because the work happens in parallel.
It also creates a useful structure when each branch has its own state, events, retry behavior, or result type.

But again, C# already has a good concurrency primitive:

Task<AgentResponse> riskTask = legalRiskAgent.RunAsync(
    documentText,
    cancellationToken: cancellationToken);

Task<AgentResponse> grammarTask = grammarAgent.RunAsync(
    documentText,
    cancellationToken: cancellationToken);

Task<AgentResponse> obligationsTask = obligationsAgent.RunAsync(
    documentText,
    cancellationToken: cancellationToken);

await Task.WhenAll(riskTask, grammarTask, obligationsTask);

AgentResponse risk = await riskTask;
AgentResponse grammar = await grammarTask;
AgentResponse obligations = await obligationsTask;

var result = new DocumentReviewResult(
    LegalRisk: risk.Text,
    GrammarNotes: grammar.Text,
    Obligations: obligations.Text);

For simple concurrent orchestration, Task.WhenAll is often easier to read and test than a workflow graph.

The operational concerns are the same either way:

Parallel agent calls multiply token usage
They can hit provider rate limits faster
They increase cost
They make partial failure handling more important
Concurrency should be bounded and intentional

The workflow engine does not make those concerns disappear.
It provides a structured way to model and observe concurrent branches when that structure matters.

Handoff Workflows

A handoff workflow allows one agent or step to decide which other agent should continue the task.

For example:

An intent agent receives a user request.
It decides whether the task belongs to a movie expert, music expert, legal expert, or support agent.
The workflow controls which handoffs are allowed.
The selected agent continues the process.

This is useful when the route can continue over multiple steps and allowed transitions matter.
The workflow can make it clear that the legal expert may hand off to compliance, but not directly to billing.
Or that support can escalate to engineering, but only after collecting certain information.

For simple routing, I would usually not start here.
The pattern from the manual routing article is often enough:

AgentResponse<IntentResult> intentResponse =
    await intentAgent.RunAsync<IntentResult>(
        $"""
        Classify the user's request.

        User request:
        {userMessage}
        """,
        cancellationToken: cancellationToken);

IntentResult route = intentResponse.Result;

string answer = route.Intent switch
{
    UserIntent.Movies => (await movieAgent.RunAsync(userMessage, cancellationToken: cancellationToken)).Text,
    UserIntent.Music => (await musicAgent.RunAsync(userMessage, cancellationToken: cancellationToken)).Text,
    UserIntent.Legal => (await legalAgent.RunAsync(userMessage, cancellationToken: cancellationToken)).Text,
    _ => "I can help with movies, music, or legal questions."
};

This keeps routing explicit in application code.
The classifier returns structured output.
The application validates it.
The switch expression owns the route.

That is boring in the best way.

Handoff workflows help when routing is no longer just a single switch:

Allowed transitions are part of the domain
Agents may hand off repeatedly
The path needs to be inspected later
Intermediate state must survive between handoffs
Handoffs need events, checkpoints, or human approval

Human-in-the-Loop Workflows

Human-in-the-loop is less about routing and more about process state.
It allows the system to pause and wait for human input.

For example:

An agent drafts an answer.
The workflow pauses for human approval.
A human edits or approves the answer.
The workflow continues with publishing or sending the result.

This is one of the strongest reasons to use a workflow engine.
The pause is not a UI detail.
It is part of the process.

Still, not every user interaction needs a workflow.

For a local chat UI, this may be enough:

AgentResponse draft = await agent.RunAsync(
    userMessage,
    cancellationToken: cancellationToken);

ApprovalDecision decision = await approvalUi.RequestApprovalAsync(
    draft.Text,
    cancellationToken);

if (!decision.Approved)
{
    return "Draft rejected.";
}

await publisher.PublishAsync(decision.EditedText, cancellationToken);

That is simple.
The user is present.
The interaction is immediate.
The state belongs naturally in the UI or controller flow.

Workflows become useful when the human interaction is part of a long-running business process:

approval chains
compliance checks
ticket escalation
delayed review
multi-day processes
persisted state
audit requirements

If the process may pause today and resume tomorrow, a workflow engine is a much better fit than pretending everything still lives inside one request handler.

The Guitar Order Example

Let's make the trade-off concrete.

A customer orders a guitar from an online music store.

The system should:

parse the customer's guitar order
check inventory
decide whether the guitar can be reserved
return either a confirmation, an alternative recommendation, or a human review request

The agents are not the hard part.
The design decision is where orchestration belongs.

The Workflow-Heavy Version

In a workflow-heavy design, you might model the process like this:

GuitarOrderParserExecutor
InventoryCheckExecutor
ReserveInventoryExecutor
AlternativeRecommendationExecutor
HumanReviewExecutor
OrderConfirmationExecutor
an edge from parsing to inventory
a conditional edge from inventory to alternative recommendations
a conditional edge from inventory to reservation
a conditional edge from reservation to human review
a conditional edge from reservation to confirmation
an edge from approved human review to confirmation
events emitted when parsing, inventory check, reservation, review, and final decision complete

Conceptually, the graph looks like this:

This can be a good design.

If the guitar order process is part of a larger business process, the workflow graph may be exactly what you want.
Maybe high-value guitars require manual review.
Maybe custom instruments need setup confirmation.
Maybe inventory reservation and payment authorization happen asynchronously.
Maybe fulfillment is delayed.
Maybe customer support needs to inspect where the order stopped.

In that world, the workflow is not over-engineering.
It is the process model.

The Normal C# Version

For the simple version, I would probably write something like this:

public async Task<GuitarOrderResult> HandleAsync(
    string userMessage,
    CancellationToken cancellationToken)
{
    AgentResponse<GuitarOrder> parsed =
        await guitarOrderParserAgent.RunAsync<GuitarOrder>(
            userMessage,
            cancellationToken: cancellationToken);

    InventoryResult inventory =
        await inventoryService.CheckAsync(parsed.Result, cancellationToken);

    if (!inventory.IsInStock)
    {
        AlternativeProduct? alternative =
            await recommendationService.FindAlternativeAsync(
                parsed.Result,
                cancellationToken);

        return GuitarOrderResult.AlternativeRecommendation(
            parsed.Result,
            alternative);
    }

    Reservation reservation =
        await inventoryService.ReserveAsync(parsed.Result, cancellationToken);

    if (reservation.RequiresManualReview)
    {
        return GuitarOrderResult.HumanReviewRequired(
            parsed.Result,
            reservation);
    }

    return GuitarOrderResult.Confirmed(
        parsed.Result,
        reservation);
}

In the simple C# version, the method can simply return a HumanReviewRequired result and let the surrounding application handle the next step.
In the workflow version, the process itself could pause, persist its state, wait for the review, and continue later.

Every developer can follow this flow from top to bottom.
There is no workflow setup to inspect.
There are no edges to mentally resolve.
The control flow is not hidden behind the workflow definition.

For this simple case, the C# version may be easier to understand six months later.

The same agents can be used in both designs.
The design decision is not whether agents are useful.
The design decision is where orchestration belongs.

That is the trap with workflow engines.
They can make complex processes easier to inspect, but they can also make simple processes harder to understand.

For small flows, workflow graphs can introduce more setup code, more indirection, more event handling, and more distance between cause and effect.

Ceremony is not architecture.

Decision Matrix: Workflow Engine vs. Normal C

Use this as a quick filter before reaching for a workflow graph.

Scenario	Start with C# when...	Use workflows when...
Sequential chain	The flow has two or three deterministic steps	Steps need progress events, checkpoints, retries, or resumption
Concurrent calls	`Task.WhenAll` is enough	Branches need independent state, observability, or fan-in logic
Routing / handoff	Structured output + `switch` is clear	Allowed transitions are part of the domain
Human input	The user is present in the UI	Approval is delayed, auditable, or long-running

The table is intentionally biased toward starting simple. A workflow engine should not be used because orchestration exists. It should be used because modeling orchestration improves the system.

When I Would Use Workflows

I reach for workflows when the orchestration is important enough to become a first-class part of the system.

That usually means one or more of these are true:

the process has many steps and branches
the process itself needs to be visible
the workflow needs to pause and resume
the state must be checkpointed or persisted
humans approve or modify intermediate results
the process may run for minutes, hours, or days
the orchestration path matters for auditing
teams need a shared model of the process
the graph is easier to reason about than scattered application code

If the process is part of the product behavior, model it deliberately.
If users, operators, or auditors care about the process, hiding it in a method call may not be enough.

When I Would Not Use Workflows

I avoid workflows when the graph adds more code than it removes.

That is often the case when:

there are only two or three steps
the process is linear
routing is just a simple switch
parallelism is just Task.WhenAll
user input belongs naturally in the UI flow
the workflow graph adds more setup than clarity
debugging the workflow is harder than reading the code

If normal C# makes the flow obvious, testable, and maintainable, that is not a workaround.
That is good engineering.

External Workflow Engines

Microsoft Agent Framework workflows are useful inside an agent application.
They do not automatically replace every existing workflow platform.

If the workflow is a company-level business process with many integrations, approvals, retries, timers, dashboards, and non-developer stakeholders, the agent framework should probably not become the central enterprise workflow platform.

Examples include:

Azure Logic Apps
Durable Functions
n8n
Make

In those systems, agents can be exposed as API steps or services.
The external workflow engine owns the broader business process.
The agent application owns the agent behavior.

Use the right workflow engine at the right level.

A Practical Rule of Thumb

Start with C#.
Move to workflows when the process needs to outlive the method call.

More specifically:

If the orchestration is local, short-lived, and deterministic, keep it in code.
If the orchestration is long-running, inspectable, resumable, and operationally relevant, model it as a workflow.

Another way to say it:

Use code when you need control flow.
Use workflows when control flow becomes product behavior.

Conclusion

The workflow engine is a powerful part of Microsoft Agent Framework.
It is a good fit when the process itself has architectural weight: state, checkpoints, events, approvals, resumption, and operational visibility.

It is not the default answer to every multi-agent design.
Simple orchestration still often belongs in normal C# code: method calls, switch statements, loops, Task.WhenAll, validation logic, and explicit application services.

The goal is not to use the most advanced abstraction.
The goal is to make the system easier to understand, operate, and change.

We can now orchestrate agents, route tasks, expose agents as tools, and decide when workflows are worth the complexity.
Next, the series moves to knowledge: how agents answer from documents, databases, PDFs, and internal systems through retrieval-augmented generation.

Agents as Tools in Microsoft Agent Framework

Lukas Walter — Thu, 04 Jun 2026 15:30:00 +0000

This is Part 11 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

In the previous article, we looked at manual multi-agent routing.
A small intent agent classified the request.
Then normal C# decided which specialist agent should run.

That pattern is useful when your application should retain control over the route.
But there is another pattern that is worth knowing: exposing an agent as a tool.

Instead of routing from C#, you give a coordinator agent access to other agents as function tools.
The coordinator can then decide when to delegate work to a focused inner agent.

This is not a magic cost reducer.
It is not a replacement for workflows.
It is a lightweight composition pattern for cases where one agent has become too broad, but a full workflow graph would be too much.

The Problem with One Tool-Heavy Agent

Let's first discuss why a single, tool-heavy agent is a problem.
Adding tools to an agent is easy.
That is also why agents tend to grow too quickly.

A first version might only answer questions.
Then it gets a few string utilities.
Then some number tools.
Then a documentation search tool.
Then a ticketing tool.
Then a deployment helper.

At some point, every request carries too much baggage.
The model receives:

broad instructions
many tool namesor small agents
many tool descriptions
parameter schemas for tools it does not need
rules for domains that are irrelevant to the current request

This creates the same issue we saw in manual routing.
The agent has more context to process, more tools to choose from, and more ways to choose the wrong behavior.

For small agents, this does not matter much.
For agents with many detailed tools, the overhead becomes visible quickly because tool definitions are part of the model context.

Agents as Tools

Agent Framework lets you convert an AIAgent into a function tool using AsAIFunction().
That tool can then be passed to another agent.

This assumes you are using an agent type that supports function tools.
In practice, check agent and provider support before designing around this pattern.

The outer agent sees the inner agent like any other tool.
The inner agent still has its own instructions, tools, model calls, and behavior.

Conceptually, the flow looks like this:

The important part is isolation.
The coordinator does not need to know every low-level tool behind every specialist agent.
It only needs to know which specialist agents are available and what each one is good at.

A Small Example

Imagine a simple assistant with two specialist areas:

string transformations
numeric calculations

You could put all tools on one agent.
For a small demo, that is fine.
But the structure becomes clearer when each specialist owns its own tools.

using System.ComponentModel;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Converts text to uppercase.")]
static string ToUppercase(
    [Description("The text to convert.")] string text)
{
    return text.ToUpperInvariant();
}

[Description("Reverses text.")]
static string ReverseText(
    [Description("The text to reverse.")] string text)
{
    return new string(text.Reverse().ToArray());
}

[Description("Multiplies two numbers.")]
static double Multiply(
    [Description("The first number.")] double left,
    [Description("The second number.")] double right)
{
    return left * right;
}

Now create the inner agents.

AIAgent stringAgent = chatClient.AsAIAgent(
    name: "string-agent",
    description: "Handles string transformations such as uppercase and reverse text.",
    instructions: """
    You transform strings by using the provided tools.
    Keep the answer short and return the transformed value clearly.
    """,
    tools:
    [
        AIFunctionFactory.Create(ToUppercase),
        AIFunctionFactory.Create(ReverseText)
    ]);

AIAgent numberAgent = chatClient.AsAIAgent(
    name: "number-agent",
    description: "Handles small deterministic numeric calculations.",
    instructions: """
    You perform numeric calculations by using the provided tools.
    Keep the answer short and include the calculated value.
    """,
    tools:
    [
        AIFunctionFactory.Create(Multiply)
    ]);

The name and description matter because they become part of the coordinator model's routing surface once the agents are exposed as tools.
A vague description gives the coordinator too little information to choose the right specialist reliably.

Now expose those agents as tools to the coordinator.

AIAgent coordinatorAgent = chatClient.AsAIAgent(
    name: "coordinator-agent",
    instructions: """
    You decide whether a request should be handled directly or delegated.

    Use the string agent for text transformation tasks.
    Use the number agent for deterministic numeric calculations.

    If no specialist agent fits, answer briefly without inventing tool results.
    """,
    tools:
    [
        stringAgent.AsAIFunction(),
        numberAgent.AsAIFunction()
    ]);

AgentResponse response = await coordinatorAgent.RunAsync(
    "Uppercase 'hello world' and multiply 12 by 4.");

The coordinator receives two tool options:

Call the string agent
Call the number agent

It does not receive the raw schemas for ToUppercase, ReverseText, and Multiply as direct tools.
Those belong to the specialist agents.

What Actually Saves Tokens

The token benefit comes from narrowing the visible tool surface.

Without delegation, one large agent receives every tool schema on calls to that agent:

With agents as tools, the coordinator sees a smaller set of higher-level tools:

That can reduce input tokens for the coordinator call.
But delegation also adds extra agent invocations.

If the coordinator calls one inner agent, you pay for the coordinator call and the inner agent call.
If it calls three inner agents, you pay for all of them.

This pattern pays off when:

Most requests only need one specialist area
Inner agents have many tools that should not be visible all the time
The coordinator can use a smaller model than the specialists
Specialist agents can stay focused and short

It may not pay off when:

Every request needs most of the inner agents anyway
The tool lists are already small
The coordinator needs long context just to decide what to do
Latency matters more than token cost

Measure it with your prompts, tools, models, and traffic shape.

Delegation Is Model-Driven

This is the main difference from the previous article.

With manual routing, the application decides:

With agents as tools, the coordinator model decides:

That makes agents as tools more flexible.
The coordinator can decide to call one specialist, multiple specialists, or none.
It can also combine results before answering the user.

But it is less explicit than a C# switch.
The model may skip a useful specialist.
It may call the wrong one.
It may delegate when a direct answer would have been enough.

Good agent descriptions help, but they do not make delegation deterministic.

Use manual routing when you need predictable application-owned control.
Use agents as tools when the coordinator should reason about whether delegation is useful.

Context Does Not Automatically Transfer

An inner agent is not just a continuation of the outer agent.
It runs as a tool call.
That means the inner agent has its own:

Instructions
Tools
Model invocation
Context providers
Session behavior

It does not automatically inherit the full outer conversation history or every piece of outer context.
The coordinator must pass the relevant task information through the tool call.

If you pass a shared AgentSession to AsAIFunction(), treat it carefully.
The resulting function is stateful, so reusing it concurrently across conversations can create unpredictable behavior.

This is a good boundary, but it can surprise you. Let's think about the coffee agent from my previous examples.

For example, if the user said their preferred coffee ratio five turns ago, the inner coffee agent may not know that unless the coordinator passes it in or the inner agent can load it through its own memory/context setup.

So, a practical rule is :

Do not assume shared context.
Deliberately pass the necessary task context, or give the inner agent its own context provider.

Keep Inner Agents Focused

The point of this pattern is not to hide complexity inside another agent.
The point is to create a smaller, clearer capability boundary.

A useful inner agent should have:

a narrow responsibility
a clear name
a concrete description
only the tools it needs
short instructions
predictable output expectations

If the inner agent becomes another general-purpose assistant, you have only moved the problem one level down.

For example, string-agent is a useful boundary.
It transforms strings.
It has string tools.
It does not need documentation search, ticket creation, or deployment access.

Keep in mind:

operations-agent-that-can-do-everything is not a useful boundary.
It is just the original overloaded agent with a different name.

Watch the Side Effects

An agent tool can hide several lower-level tool calls behind one coordinator-visible call.
That is useful for composition.
It also means you need observability.

The outer agent receives the inner agent's result.
It should not be your only audit surface.
If the inner agent can call tools, log those tool calls where they happen.
Use tracing or middleware so you can inspect:

which inner agent was called
what input it received
which tools it called
whether approval was required
what result it returned
how long each step took

Note: I will dive into observability in a later post, but for now I just want to mention that Aspire Dashboard includes a GenAI visualizer that is really helpful when debugging multi-agent setups. For background, see the OpenTelemetry article GenAI observability with OpenTelemetry and Aspire Dashboard.

The same safety rule from local tools still applies:

If an inner agent can spend money, change data, send messages, or trigger deployments, do not rely on the coordinator prompt as the safety boundary.
Put approval, authorization, validation, and logging behind the actual tool that performs the action.

The inner agent is a composition boundary.
It is not a security boundary by itself.

Agents as Tools vs. Workflows

Agents as tools are useful for lightweight delegation.
They are not the same as workflows.

Use agents as tools when the coordinator can decide what to call and the task can complete in normal tool-calling flow.

Use a workflow when the orchestration itself needs to be explicit.
For example:

fixed execution order
checkpoints
resumability
human approval between steps
typed edges between stages
long-running processes
clearer operational visibility

A coordinator agent can be enough for:

Read the user request.
Call the right specialist.
Combine the result.
Answer.

A workflow is a better fit when the process itself is the product.
For example, triage a support case, create a remediation plan, ask for approval, execute a change, and persist the result.

When to Use Agents as Tools

Use agents as tools when:

one agent is accumulating too many unrelated tools
specialist agents can own clear domains
the coordinator should decide whether delegation is needed
different specialists should use different tools, prompts, or models
the inner task can be represented as a tool call and final result
you can observe and test the delegation path

Do not use agents as tools when:

a simple C# function is enough
a C# switch gives better control
every request needs every specialist anyway
the inner agent needs hidden context that cannot be passed reliably
the side effects are too risky without explicit approval
the process needs workflow-level checkpoints and state

This pattern is best treated as a pragmatic middle step.
It sits between manual routing and full workflow orchestration.

Conclusion

Agents as tools let you compose focused agents without giving one agent every raw tool.
The coordinator sees a smaller set of specialist capabilities.
Each inner agent keeps its own instructions and tools.

That can improve focus by reducing the tool surface visible to the coordinator.
But it also adds model-driven delegation, extra invocations, context isolation, and observability requirements.

Use this pattern when delegation should be flexible and specialist boundaries are clear.
Use manual routing when application code should decide.
Use workflows when the orchestration needs explicit state, checkpoints, and control.

Next, we will move from lightweight delegation to Agent Framework workflows: when the workflow engine is worth using, and when normal C# is still the cleaner option.

Why CancellationToken Matters More in .NET AI Systems

Lukas Walter — Mon, 01 Jun 2026 15:30:00 +0000

CancellationToken is one of the most underrated AI engineering features in .NET.
Not because it is new.
Because AI workloads have a different runtime profile.

A normal application call might take milliseconds.
An LLM call might take seconds.
A streaming response might keep running while tokens are generated.
An embedding pipeline might process thousands of chunks.
A tool call might trigger another slow network request.
And sometimes, the user is already gone.
They closed the tab.
They navigated away.
The HTTP request timed out.
The background job was stopped.
The deployment is shutting down.

Without cancellation, your application may keep doing expensive work nobody needs anymore.
That means:

wasted tokens
wasted compute
unnecessary tool calls
slower shutdowns
noisy traces
worse resource usage

In .NET, this is not a special AI problem.
It is a normal engineering problem that becomes much more visible in AI systems.

Pass the CancellationToken.

From your ASP.NET Core endpoint.
From HttpContext.RequestAborted.
Into your agent call.
Into your IChatClient call.
Into your embedding generation.
Into your retrieval layer.
Into your database query.
Into your tool execution.

Especially when streaming responses with IAsyncEnumerable, because the UI might stop listening long before your backend stops generating.

AI engineering is not only about better prompts, better models, or better frameworks.
It is also about respecting the lifecycle of the request.

Why AI Workloads Expose This Problem

Cancellation exists in .NET because long-running work needs a cooperative way to stop.
That has always mattered.
But classic CRUD workloads often hide the problem.
If a request reads one row from a database and returns in 30 milliseconds, the cost of ignoring cancellation is small.
It is still wrong, but it is rarely dramatic.

AI workloads change that.
An LLM call can hold an outbound HTTP connection open for seconds.
A streaming chat endpoint can continue producing tokens even after the browser tab is closed.
A RAG request can do retrieval, reranking, prompt construction, and model generation before the user sees anything useful.
An ingestion job can generate embeddings for thousands of chunks.
An agent can call tools that call other APIs.

The runtime profile is wider, slower, and more expensive.
That is why cancellation stops being a small cleanup detail.
It becomes part of the cost and reliability model.

The Mental Model

A CancellationToken is not a timeout button.
It is not a thread abort.
It does not magically undo side effects.
It also does not guarantee that a remote provider stops work or billing instantly.
It is a cooperative signal.
The caller says: "This work is no longer needed."
The callee decides where it can stop safely.

That distinction matters in AI systems because work often crosses several boundaries:

HTTP request
retrieval
embedding or reranking
model call
streaming response
tool execution
logging and tracing

If the token disappears at any point, the rest of the pipeline may continue running.

The common failure is not that developers forgot cancellation exists.
The common failure is that cancellation only exists at the first method signature.

Start at the HTTP Boundary

In ASP.NET Core, a CancellationToken parameter on an endpoint is bound to the request-aborted token.
That is usually the first token you want.

app.MapPost("/ask", async (
    AskRequest request,
    IChatClient chatClient,
    CancellationToken cancellationToken) =>
{
    var messages = new[]
    {
        new ChatMessage(ChatRole.System, "Answer briefly and use the provided context."),
        new ChatMessage(ChatRole.User, request.Question)
    };

    var response = await chatClient.GetResponseAsync(
        messages,
        cancellationToken: cancellationToken);

    return Results.Ok(response.Text);
});

The important part is not the endpoint syntax.
The important part is that the token crosses the model boundary.

If the user disconnects while the model is generating, your application should not keep waiting for the answer just so it can throw it away.

In a larger application, I usually pass the token into an application service rather than calling the model directly in the endpoint.

app.MapPost("/ask", async (
    AskRequest request,
    AssistantService assistant,
    CancellationToken cancellationToken) =>
{
    var answer = await assistant.AnswerAsync(
        request.Question,
        cancellationToken);

    return Results.Ok(answer);
});

Then the service owns the AI workflow, but the request still owns the lifecycle.

public sealed class AssistantService(
    IRetrievalService retrieval,
    IChatClient chatClient)
{
    public async Task<string> AnswerAsync(
        string question,
        CancellationToken cancellationToken)
    {
        var context = await retrieval.SearchAsync(
            question,
            cancellationToken);

        var messages = BuildMessages(question, context);

        var response = await chatClient.GetResponseAsync(
            messages,
            cancellationToken: cancellationToken);

        return response.Text;
    }
}

That is the pattern:

accept the token at the boundary
pass it to every async operation
do not replace it with CancellationToken.None
do not stop passing it once the code enters the AI layer

Streaming Makes Cancellation More Important

Streaming is where ignored cancellation becomes easiest to miss.
The backend can keep generating tokens even after the browser, mobile app, or frontend stream reader is gone.
From the user's perspective, the conversation ended.
From the backend's perspective, the model may still be working.
That is wasted work.
For streaming endpoints, pass the token into the model call, and optionally into response writes when it helps the write loop exit cleanly.

app.MapGet("/ask/stream", async (
    string question,
    IChatClient chatClient,
    HttpResponse response,
    CancellationToken cancellationToken) =>
{
    response.ContentType = "text/plain; charset=utf-8";

    var messages = new[]
    {
        new ChatMessage(ChatRole.User, question)
    };

    await foreach (var update in chatClient
        .GetStreamingResponseAsync(
            messages,
            cancellationToken: cancellationToken))
    {
        if (string.IsNullOrEmpty(update.Text))
        {
            continue;
        }

        await response.WriteAsync(update.Text, cancellationToken);
        await response.Body.FlushAsync(cancellationToken);
    }
});

There are two useful details here.
First, the model streaming call receives the token.
Second, each response write receives the same token.
That matters because streaming is not one operation.
It is a sequence.

Each token chunk is another opportunity to stop.

If the user interface stops listening, the backend should notice.
If the request is aborted, the model stream should stop.
If the deployment is shutting down, the endpoint should not keep a long stream alive just because it already started.

Passing the token to WriteAsync and FlushAsync is fine, but the more important part is usually upstream cancellation.
Once the client disconnects, ASP.NET Core may already stop or fail response writes.
The expensive work is the model call, retrieval, tool execution, or embedding generation that keeps producing data for a response nobody will read.

If you consume a streaming API that does not expose a cancellation token parameter, use .WithCancellation(cancellationToken) at the enumeration site instead.
Do not pass the same token through both mechanisms unless the API documentation explicitly expects that pattern.

RAG Pipelines Need the Same Discipline

RAG systems often hide several expensive operations behind one "ask" endpoint.

A single user question might do this:

rewrite the query
generate an embedding
search a vector index
fetch source documents
rerank results
build the prompt
call the model
stream the answer

Cancellation needs to travel through that whole chain.

public sealed class RagAssistant(
    IQueryRewriter rewriter,
    IRetriever retriever,
    IChatClient chatClient)
{
    public async Task<string> AnswerAsync(
        string question,
        CancellationToken cancellationToken)
    {
        var rewrittenQuery = await rewriter.RewriteAsync(
            question,
            cancellationToken);

        var documents = await retriever.SearchAsync(
            rewrittenQuery,
            cancellationToken);

        var messages = BuildPrompt(question, documents);

        var response = await chatClient.GetResponseAsync(
            messages,
            cancellationToken: cancellationToken);

        return response.Text;
    }
}

This looks boring.
That is the point.

Cancellation in AI systems should not require a clever framework.
It should be part of the ordinary method contract.

If retrieval is backed by EF Core, pass the token there too.

public Task<List<DocumentChunk>> LoadChunksAsync(
    IReadOnlyCollection<string> chunkIds,
    CancellationToken cancellationToken)
{
    return db.DocumentChunks
        .Where(chunk => chunkIds.Contains(chunk.Id))
        .ToListAsync(cancellationToken);
}

If retrieval is backed by a vector database or search service, the same rule applies.
The outbound SDK call should receive the token.

Embedding Jobs Are Cancellation Hotspots

Embedding generation is another place where cancellation gets ignored.

It often runs outside the request path, so developers treat it as batch work that can simply run until it finishes.
Sometimes that is fine.
But ingestion jobs still need to stop cleanly during deployment, shutdown, or operational intervention.

If you process thousands of chunks, check cancellation between batches.

public async Task IndexDocumentsAsync(
    IEnumerable<DocumentChunk> chunks,
    IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator,
    IVectorIndex vectorIndex,
    CancellationToken cancellationToken)
{
    foreach (var batch in chunks.Chunk(64))
    {
        cancellationToken.ThrowIfCancellationRequested();

        var texts = batch
            .Select(chunk => chunk.Text)
            .ToArray();

        var embeddings = await embeddingGenerator.GenerateAsync(
            texts,
            cancellationToken: cancellationToken);

        await vectorIndex.UpsertAsync(
            batch,
            embeddings,
            cancellationToken);
    }
}

The batch boundary is a natural safe point.

You do not want to stop halfway through a local in-memory projection just because a token was canceled.
But you do want to stop before generating the next expensive batch of embeddings.

For ingestion pipelines, cancellation is also useful for shutdown behavior.
A background service that ignores its stopping token can make deployments slower and less predictable.

public sealed class EmbeddingWorker(
    EmbeddingQueue queue,
    DocumentIndexer indexer) : BackgroundService
{
    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        await foreach (var job in queue.ReadAllAsync(stoppingToken))
        {
            await indexer.IndexAsync(job, stoppingToken);
        }
    }
}

The stoppingToken is not decoration.
It is the host telling your worker that the process is trying to stop.

Tools Need Cancellation Too

Tool calling makes this more important, not less.

An agent tool is still application code.
It might query a database, call an internal API, invoke a search service, read files, or trigger another model call.
If the parent request is canceled, the tool should not keep doing unnecessary work.

[Description("Searches internal documentation for relevant snippets.")]
public static Task<IReadOnlyList<SearchResult>> SearchDocsAsync(
    string query,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var search = services.GetRequiredService<IDocumentSearch>();

    return search.SearchAsync(query, cancellationToken);
}

The model does not need to know about the token.
Your application does.

This is an important boundary.
Model-supplied arguments are untrusted input.
The CancellationToken comes from your runtime.
Do not let agent abstractions make you forget that tool execution still belongs to your application lifecycle.

This assumes your tool framework treats IServiceProvider and CancellationToken as runtime-supplied parameters, not model-supplied parameters.
If a framework exposes every method parameter to the model schema, do not expose application services or lifecycle tokens that way.

Timeouts Are Policy, Cancellation Is Plumbing

Cancellation tokens are often used to implement timeouts, but they are not the same thing.

A timeout is a policy decision.

For example:

this chat endpoint should stop after 30 seconds
this retrieval call should stop after 2 seconds
this embedding batch should stop after 5 minutes
this background worker should stop when the host shuts down

The token is how that decision travels through the code.

If you need a request cancellation token and an internal timeout, link them at the edge where the policy is visible.

app.MapPost("/ask", async (
    AskRequest request,
    AssistantService assistant,
    CancellationToken requestAborted) =>
{
    using var timeoutCts = new CancellationTokenSource(
        TimeSpan.FromSeconds(30));

    using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(
        requestAborted,
        timeoutCts.Token);

    try
    {
        var answer = await assistant.AnswerAsync(
            request.Question,
            linkedCts.Token);

        return Results.Ok(answer);
    }
    catch (OperationCanceledException) when (requestAborted.IsCancellationRequested)
    {
        // 499 Client Closed Request is a common convention,
        // not an ASP.NET Core named status constant.
        return Results.StatusCode(499);
    }
    catch (OperationCanceledException) when (timeoutCts.IsCancellationRequested)
    {
        return Results.StatusCode(StatusCodes.Status504GatewayTimeout);
    }
});

This keeps two cases separate:

the user went away
your system decided the operation took too long

Those should not be logged, alerted, or retried in the same way.

What Not To Do

The mistake I look for first is CancellationToken.None.

await chatClient.GetResponseAsync(
    messages,
    cancellationToken: CancellationToken.None);

That says: "Even if the caller is gone, keep going."

Sometimes that is intentional.
Most of the time, it is accidental.

Another mistake is accepting a token but only using it in the first call.

public async Task<string> AnswerAsync(
    string question,
    CancellationToken cancellationToken)
{
    var documents = await retriever.SearchAsync(question, cancellationToken);

    var response = await chatClient.GetResponseAsync(
        BuildPrompt(question, documents));

    return response.Text;
}

The retrieval call can cancel.
The model call cannot.

That is exactly the wrong place to lose the token, because the model call is often the slowest and most expensive part of the operation.

Logging Cancellation Like a Failure Creates Noise

Expected cancellation is not the same as failure.

If a user closes a browser tab while a streaming answer is being generated, that is not a model outage.
If the host is shutting down and a background embedding worker stops between batches, that is not an ingestion error.

Log cancellation separately.

try
{
    await assistant.AnswerAsync(question, cancellationToken);
}
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
{
    logger.LogInformation(
        "AI request canceled before completion.");

    throw;
}

The throw is intentional.
The method can add local context, but the boundary should decide how cancellation maps to the transport response, trace status, or job state.

For AI workloads, this matters because traces can get noisy quickly.
If every user-aborted stream looks like an application error, your observability gets worse instead of better.

A Checklist for .NET AI Code

When I review AI code in .NET, I check this:

Does the ASP.NET Core endpoint accept a CancellationToken?
Is HttpContext.RequestAborted used when the token is not injected directly?
Does the token reach the agent or IChatClient call?
Does streaming use cancellation while consuming IAsyncEnumerable?
Does the token reach embedding generation?
Does retrieval pass the token into search, vector, and database calls?
Do tools accept and pass the token?
Do background services use stoppingToken?
Are timeout policies explicit and close to the boundary?
Are linked token sources disposed?
Is CancellationToken.None used only where the reason is intentional?
Are expected cancellations logged differently from real failures?

Most of this is not AI-specific syntax.
It is ordinary .NET discipline applied to AI runtime behavior.

When To Use Cancellation Tokens

Use cancellation tokens in AI systems when:

a user request may be aborted
a streaming response may be disconnected
a model call may run longer than the user is willing to wait
retrieval or reranking has a request-level deadline
embedding generation runs in batches
tools call databases, APIs, or other slow dependencies
background workers need to stop cleanly during deployment
retries should stop when the parent operation is no longer relevant

When Not To Rely On Cancellation Tokens

Do not use cancellation tokens as:

a substitute for idempotency
a substitute for transactions
a replacement for retry and circuit-breaker policy
a guarantee that remote providers stopped billing instantly
a way to pretend side effects can be undone
a reason to swallow OperationCanceledException and return success

Cancellation is not the whole reliability story.
It is the lifecycle signal that lets the rest of the story behave correctly.

Final Thoughts

The forgotten AI feature in .NET is not flashy.
It is probably already in your method signature: CancellationToken.
In small CRUD paths, ignoring it might only waste a few milliseconds.
In AI systems, ignoring it can waste model calls, tokens, tool executions, embedding batches, and shutdown time.

Better prompts and better models matter.
But so does respecting the lifecycle of the request.
Pass the token.

Official References

Use the IChatClient interface: https://learn.microsoft.com/en-us/dotnet/ai/ichatclient
Cancellation in managed threads: https://learn.microsoft.com/dotnet/standard/threading/cancellation-in-managed-threads
CancellationToken: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken
HttpContext.RequestAborted: https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.http.httpcontext.requestaborted

Manual Multi-Agent Routing in .NET

Lukas Walter — Thu, 28 May 2026 15:30:00 +0000

This is Part 10 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

So far, our agent can answer questions, stream responses, remember history, reduce context, use tools, return structured output, connect to MCP and load Agent Skills.
That is already a lot.
And that is exactly where the next problem starts.

It is tempting to keep adding instructions and tools to one large agent.
Make it a coding assistant.
Also make it a music expert.
Also make it answer questions about coffee.
Also give it support tools, documentation tools and internal process rules.

At some point, the agent becomes a jack of all trades.
The prompt grows.
The tool list grows.
The model has more irrelevant instructions to ignore.
And you pay for unnecessary input tokens on every request, even when the user only asks a simple question.

One practical way out is manual routing.
Instead of giving one agent every responsibility, we split the system into smaller specialized agents and put a cheap intent agent in front of them.
The intent agent does not answer the user.
It only decides where the request should go.

The Problem with One Large Agent

A single large agent looks simple at first. You just have one entry point for everything. But the simplicity is misleading.
If the same agent knows about coffee, music, support tickets, code review and internal documentation, each request carries baggage.
A question about a guitar amp still pays for coffee instructions.
A coffee question still carries music instructions.
A small talk message still sees tool descriptions it will never need.

This creates three problems:

More input tokens per request
More room for the model to pick the wrong behavior
More difficult prompts to maintain and test

The goal is not to create a fancy multi-agent architecture.
The goal is to keep each model call focused.

The Intent Agent

The intent agent is a dispatcher.
It sits at the front of the system and classifies the user request.
For this example, we keep the domain intentionally small:

Coffee questions go to a coffee expert agent
Music questions go to a music expert agent
Everything else gets a controlled fallback

The intent agent has one strict rule:

It classifies the request.
It does not answer the request.

That rule matters.
If the router starts answering directly, it becomes another general-purpose assistant.
Then the system has two problems instead of one.

Because the intent agent only classifies, it can usually use a smaller and cheaper model than the specialist agents.
You usually do not need deep reasoning just to choose a route.
You need a reliable category.

Use Structured Output for the Routing Decision

Do not let the intent agent return plain text like this:

This is probably a music question.

That would force your application to parse generated text.
String parsing is a weak boundary.
We already looked at this in the structured output article.

For routing, define a small C# contract instead:

public enum UserIntent
{
    Coffee,
    Music,
    Other
}

public sealed class IntentResult
{
    public UserIntent Intent { get; set; }
    public double Confidence { get; set; }
    public string Reason { get; set; } = string.Empty;
}

Now the router returns data your application can use directly.

using Microsoft.Agents.AI;

AIAgent intentAgent = smallChatClient.AsAIAgent(
    name: "intent-router",
    instructions: """
    You classify user requests for routing.

    Return Coffee when the user asks about brewing methods, beans, grind size,
    ratios, extraction, espresso or coffee gear.

    Return Music when the user asks about songs, albums, artists, instruments,
    music theory, or tone recommendations.

    Return Other when the request does not clearly belong to Coffee or Music.

    Do not answer the user's question.
    Only classify the request.
    """);

Then call it with RunAsync<T>:

string userMessage = "How do I get a dirty Hendrix tone on my Strat?";

AgentResponse<IntentResult> intentResponse =
    await intentAgent.RunAsync<IntentResult>(
        $"""
        Classify this request.

        User request:
        {userMessage}
        """);

IntentResult route = intentResponse.Result;

The useful part is the boundary.
Your application does not receive a sentence that it still has to interpret.
It receives an IntentResult.

Structured output support still depends on the agent type, provider, model and chat client.
With ChatClientAgent and compatible chat clients, RunAsync<T> is the cleanest option when the output type is known at compile time.
If your provider does not support this reliably, use an explicit JSON schema via response format or add a retry and validation layer.

C# Takes the Wheel

Once you have an IntentResult, stop asking the model to orchestrate.
Use normal C#.

AIAgent coffeeAgent = coffeeChatClient.AsAIAgent(
    name: "coffee-expert",
    instructions: """
    You answer coffee questions.
    Be practical and specific about brewing, beans, ratios and equipment.
    """);

AIAgent musicAgent = musicChatClient.AsAIAgent(
    name: "music-expert",
    instructions: """
    You answer music questions.
    Be practical and specific about instruments, tone, artists and recordings.
    """);

string finalAnswer = route.Intent switch
{
    UserIntent.Coffee =>
        (await coffeeAgent.RunAsync(userMessage)).Text,

    UserIntent.Music =>
        (await musicAgent.RunAsync(userMessage)).Text,

    _ =>
        "I can help with coffee or music questions. Please rephrase the request."
};

This is the core pattern:

The intent agent classifies.
C# routes.
The specialist agent answers.

For Other, no second model call is required.
You can return a fixed message, ask a clarification question, show supported topics, or route to a generic fallback agent if that makes sense for your application.

The important point is control.
The model does not decide which expensive agent gets called.
Your application does.

Add Confidence Before Routing Expensive Work

Do not blindly trust the router.
The router is still an LLM call.
It can be wrong.
It can be uncertain.
It can over-classify vague requests.

That is why the IntentResult includes a confidence score.
But treat that confidence as a routing signal, not as truth.

Model-generated confidence is not automatically calibrated.
A result with 0.9 does not necessarily mean the route is correct 90% of the time.
It only means the router expressed high confidence.

You can still use it as a practical gate:

if (route.Confidence < 0.75)
{
    return "Is this about coffee or music?";
}

string finalAnswer = route.Intent switch
{
    UserIntent.Coffee =>
        (await coffeeAgent.RunAsync(userMessage)).Text,

    UserIntent.Music =>
        (await musicAgent.RunAsync(userMessage)).Text,

    _ =>
        "I can help with coffee or music questions."
};

The exact threshold depends on your application.
For a casual assistant, a wrong route may not matter much.
For support automation, routing errors can waste time or trigger the wrong downstream process.

Measure this with real examples.
Do not tune the threshold from intuition alone.

Create a small labeled dataset of representative user requests.
Run the intent agent against it.
Track how often each intent is classified correctly.
Then decide where the confidence threshold should sit.

Confidence is useful.
But only after you have checked how it behaves in your actual domain.

Make Routing Observable

Manual routing also gives you a clean evaluation point.
Because the router returns a typed result before any specialist agent runs, you can log the routing decision separately from the final answer.
For example:

logger.LogInformation(
    "Intent routed. Intent={Intent}, Confidence={Confidence}, SelectedAgent={SelectedAgent}, FallbackUsed={FallbackUsed}",
    route.Intent,
    route.Confidence,
    selectedAgent,
    fallbackUsed);

Useful fields include:

userMessage
predictedIntent
confidence
selectedAgent
fallbackUsed

In a real system, you may not want to log the full user message directly.
Depending on your privacy and compliance requirements, you might log a request id, a redacted message or a hashed reference instead.

The important part is that routing becomes measurable.
You can now answer questions like:

Which intents are confused most often?
How often does the fallback trigger?
Which confidence ranges produce the most wrong routes?
Are some user request types consistently misclassified?
Did a model upgrade improve or damage routing quality?

This is one of the underrated benefits of manual routing.
You are not only saving tokens.
You are creating a small, testable control point in front of the rest of the system.

Why This Saves Tokens

Manual routing helps because each agent receives only the context it needs.
But keep in mind, routing is not free.
It adds one model call before the specialist call.

This only pays off when the routing call is cheaper than the irrelevant context you avoid.
If your specialist prompts are tiny, the extra router call may not be worth it.
But once prompts, tools and model sizes start to diverge, routing becomes useful quickly.

The intent agent can stay small:

short instructions
no domain tools
no long specialist prompt
cheap model
structured output only

The specialist agents can stay focused:

coffee instructions only for coffee questions
music instructions only for music questions
domain tools only where they are useful
stronger models only when the request deserves them

This does not make token limits disappear.
It changes which instructions, tools and context are sent to which model call.

Instead of this:

Every request
  -> coffee prompt + music prompt + all tools + all rules

You get this:

Every request
  -> small routing prompt

Only music requests
  -> music prompt + music tools

Only coffee requests
  -> coffee prompt + coffee tools

That is the real win.
You avoid paying for irrelevant context on every request.

Manual Routing vs. Workflow Engine

This article uses plain C# routing on purpose.
You could model routing as a workflow later.
Agent Framework has a workflow engine for explicit orchestration, checkpoints, handoffs and human-in-the-loop scenarios.
But this example does not need that yet.
The flow is simple:

Classify intent
Switch on the result
Call one specialist
Return the answer

A C# switch is easier to read, easier to test and easier to debug than a workflow graph for this case.
This is a useful design rule:

Use the smallest orchestration mechanism that gives you enough control.

For simple routing, that is often normal C#.

When to Use Manual Intent Routing

Use manual intent routing when:

You have clearly separated domains
One large prompt is becoming too expensive or unfocused
Different requests need different tools
Different requests deserve different model sizes
You want predictable routing logic in application code
You can evaluate routing quality with realistic examples

Do not use manual intent routing when:

A single small agent is already enough
The categories are vague and constantly overlapping
A wrong route would be expensive and you have no validation
The router becomes as complex as the system it replaces
You actually need checkpoints, long-running execution or human approval

This pattern is not a universal architecture.
It is a cheap and practical first step into multi-agent systems.

Conclusion

Manual multi-agent routing is simple.
Use a small intent agent to classify the request.
Return a typed IntentResult.
Let C# route to the right specialist agent.

This keeps the expensive agents focused and avoids sending every instruction and every tool to every model call.
It also gives your application a clean control point for fallbacks, confidence thresholds, logging and tests.

The main limitation is that routing quality becomes part of your system quality.
You need examples, thresholds and fallback behavior.
But that is still easier to reason about than one overloaded agent that tries to be everything at once.

Next, we can take this idea further.
Instead of routing to agents from C#, we can expose agents as tools and let one coordinator delegate work deliberately.
That gives more flexibility, but also brings back token, cost and control tradeoffs.

Extending .NET Agents with MCP and Agent Skills

Lukas Walter — Mon, 18 May 2026 13:30:00 +0000

This is Part 9 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

In the previous articles, we moved from simple agents to tools, dependency injection, and structured output.
Now, the agent can already do useful work inside an application.
But it still depends on the capabilities you explicitly wire into that application.
That is fine for domain logic you own.
It's less attractive when the capability already exists somewhere else: a file system, a documentation server, an internal workflow system, or a set of reusable team procedures.

Two extension models become interesting:

MCP tools connect an agent to external capabilities through the Model Context Protocol.
Agent Skills package reusable instructions, resources, and scripts that an agent can load only when needed.

Both models extend agent capabilities, though they address different needs.
They solve different problems.

MCP Is for External Capabilities

Model Context Protocol is useful when the agent needs to interact with a system outside your application boundary.
Instead of writing a custom C# wrapper for every external API, you connect to an MCP server and expose the tools from that server to the agent.
The server owns the integration logic.
Your application decides whether that server is allowed into the agent runtime.

MCP can expose more than tools, including resources and prompts, depending on the server and client.
This article focuses on MCP tools because they are the most direct fit for agent tool calling in this part of the series.
Conceptually, the flow looks like this:

Microsoft Agent Framework can work with the official MCP C# SDK.
A typical setup starts by creating an MCP client, listing the tools exposed by the server, and passing those tools to the agent.
For example, imagine a local read-only documentation MCP server that exposes project docs and an engineering handbook.
The exact command depends on the MCP server you use or build.
The important part is that the server is configured as read-only before its tools are exposed to the model.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

await using var mcpClient = await McpClientFactory.CreateAsync(
    new StdioClientTransport(new()
    {
        Name = "EngineeringDocs",
        Command = "dotnet",
        Arguments =
        [
            "run",
            "--project",
            "./tools/DocsMcpServer",
            "--",
            "--root", "./docs",
            "--root", "./engineering-handbook",
            "--read-only"
        ]
    }));

var mcpTools = await mcpClient.ListToolsAsync();

AIAgent agent = chatClient.AsAIAgent(
    instructions: """
    You answer questions about this project's engineering documentation.
    Use the documentation tools when current project guidance is needed.
    """,
    tools: [.. mcpTools.Cast<AITool>()]);

The DocsMcpServer name in this example is intentionally generic.
It could be your own small MCP server, an approved internal server, or a stable server package your team has reviewed.
The point is the MCP boundary.

The agent does not know how to read the documentation store directly.
It sees a set of tool definitions exposed by the MCP server.
When the model chooses one of those tools, your application routes the call through the MCP client.

MCP avoids hand-written custom API wrappers for every external system, but it does not remove application code.
You still own client setup, authentication, tool discovery, tool selection, logging, and safety boundaries.

MCP Is Still a Trust Boundary

MCP makes integrations easier.
It does not make them automatically safe.
An MCP server can expose powerful operations:

searching document stores
reading internal handbooks
creating tickets
changing files
querying databases
calling internal APIs
accessing local files
executing commands, depending on the server

So treat an MCP server like any other integration dependency.
Do not connect random servers to production agents, and do not assume that the protocol itself is the safety layer.
At minimum, check:

Who maintains the server
What tools does it expose
What credentials it receives
What data leaves your application
Whether tool calls are logged
Whether write operations need approval
Whether the server runs locally, remotely, or inside a sandbox

Authentication also belongs outside the prompt.
Do not put API keys, personal access tokens, or OAuth tokens into agent instructions.
Use the authentication mechanism expected by the MCP server and transport.
For remote HTTP servers, prefer per-run headers or runtime credential providers when available, so secrets are not baked into a shared client or accidentally persisted.

Keep the MCP Tool Surface Small

MCP servers can expose many tools.
That does not mean every agent should receive all of them.
A large tool surface creates three practical problems:

More tool descriptions are sent to the model, increasing token usage.
The model has more opportunities to choose the wrong tool.
Your review surface grows because every exposed tool becomes callable through the agent.

The same rule from local function tools applies here:

Expose the narrowest capability set that solves the task.

Prefer filtering before the tools ever reach the model.
Client-side filtering is useful, but it should not be the only safety boundary.
If the MCP server supports read-only mode, toolsets, scopes, explicit tool configuration, or server-side restrictions, use those first.
That keeps dangerous operations entirely out of the advertised tool list.

For example, a documentation assistant may need tools that search docs, read files under approved directories, or return links to handbook pages.
It should not receive tools that write files, shell out to the host, or read arbitrary paths outside the configured documentation roots.

Client-side allow-listing can be a second boundary after the server has already been configured safely.
Use explicit configuration or metadata when possible.

This name-based example is illustrative only:

var allowedToolNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{
    "search_docs",
    "read_doc",
    "list_doc_sections"
};

var selectedTools = mcpTools
    .Where(tool => allowedToolNames.Contains(tool.Name))
    .Cast<AITool>()
    .ToArray();

AIAgent docsAgent = chatClient.AsAIAgent(
    instructions: "Use only the approved documentation tools.",
    tools: selectedTools);

Do not treat naming conventions as a production security model.
They are too easy to get wrong.
In a real system, prefer server-side restrictions, explicit allow-lists, scopes, policy configuration, and audit logs.
Expose tools intentionally to ensure agent access stays controlled.

Agent Skills Are for Reusable Knowledge and Procedures

MCP is a good fit when the agent needs to call an external system.
Agent Skills are a better fit when the agent needs reusable knowledge or a repeatable procedure.

Agent Framework can support file-based skills and other authoring styles, such as code-defined or class-based skills.
This article focuses on the file-based Agent Skills format because it maps well to reusable instructions, reference material, and scripts.

In the file-based Agent Skills format, a skill is a folder with a SKILL.md file and optional resources.
For example:

skills/
  incident-triage/
    SKILL.md
    references/
      severity-levels.md
      escalation-policy.md
    scripts/
      summarize-logs.py
  pull-request-review/
    SKILL.md

The SKILL.md file contains front matter and instructions:

---
name: incident-triage
description: "Guides incident triage, severity classification, escalation, and concise incident summaries."
---

# Incident Triage

Use this skill when the user asks for help with a production incident,
alert investigation, severity classification, escalation, or incident summary.

When triaging an incident:

1. Identify affected services, users, and time window.
2. Classify severity using `references/severity-levels.md`.
3. Check escalation rules in `references/escalation-policy.md`.
4. Summarize known facts, unknowns, impact, and next actions.
5. Use `scripts/summarize-logs.py` only when log excerpts need deterministic preprocessing.

This is different from putting all of that text into the agent’s system prompt.
The skill can be advertised by name and description first.
The full instructions and reference files are loaded only when the task needs them.
That keeps the base prompt smaller while still giving the agent access to deeper domain knowledge.

Loading Skills in Agent Framework

Agent Framework exposes Agent Skills through an AgentSkillsProvider.
It acts as an AIContextProvider, so skills become part of the agent invocation pipeline rather than a one-off prompt trick.
A simple file-based setup looks like this:

using Microsoft.Agents.AI;

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"));

var agentOptions = new ChatClientAgentOptions
{
    ChatOptions = new()
    {
        Instructions = """
        You help engineers triage incidents and follow internal procedures.
        Use available skills when they are relevant.
        """
    },
    AIContextProviders = [skillsProvider]
};

AIAgent agent = chatClient.AsAIAgent(agentOptions);

The provider discovers skills from the configured directory and exposes skill-related tools to the agent.
The model can then load the right skill when a user request matches the skill description.

This gives you a useful separation:

The agent instructions define the general behavior.
Skills provide specialized procedures and checklists.
Reference files hold longer policy or domain material.
Scripts can automate deterministic helper steps when you explicitly enable them.

Scripts Need Even More Care

Skills can include scripts.
That is useful, but it changes the risk profile.
Reading a markdown reference file is one thing.
Executing a script is another.
If you enable file-based script execution, do it explicitly and treat scripts as code that runs in your environment.
For example, if your application provides a subprocess runner:

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"),
    SubprocessScriptRunner.RunAsync);

That makes script execution possible.
It does not make every script acceptable for production.

Before enabling scripts, decide:

Which script extensions are allowed
Whether scripts need human approval
What filesystem paths can they access
Whether they can use the network
How long can they run
Where stdout, stderr, and exit codes are logged
How arguments are validated before execution

For internal skills, store them in version control and review them as you would application code.
For third-party skills, treat them like dependencies that can inject instructions and run code.

MCP vs. Agent Skills

MCP is access to an external system or live state.
Agent Skills are reusable procedures, guidance, and packaged expertise.

Use MCP when	Use Agent Skills when
The agent needs to call an external system	The agent needs reusable instructions or procedures
The capability already exists behind an API, service, or local server	The capability is mostly knowledge, process, examples, or local resources
The tool result should come from current external state	The agent should load guidance only when relevant
Authentication, permissions, and transport matter	Packaging, reuse, and progressive disclosure matter

There is overlap.
You can use both.
For example, an HR assistant might use:

MCP tools to query the HR system
Agent Skills to load the company’s parental leave procedure
structured output to return a validated case summary
approval tools before submitting a request

A combination is often more useful than trying to make one abstraction do everything.

When to Use Them

Use MCP when:

The agent needs live data from another system
An existing MCP server already covers the integration
You can restrict credentials and tool permissions clearly
You need a standardized integration surface across agents

Do not use MCP when:

A simple C# function is enough
The server exposes broad write operations you cannot control
You cannot audit what data leaves your application
The integration would bypass your existing authorization model

Use Agent Skills when:

Domain knowledge is too large for the base prompt
Multiple agents or teams should reuse the same procedure
The agent should load detailed guidance only when needed
Instructions, examples, templates, and scripts should live together

Do not use Agent Skills when:

The content is really application state that should come from a database
The procedure changes on every request
The skill would hide risky automation inside a markdown folder
The same result is better expressed as normal tested C# code

Conclusion

MCP and Agent Skills both extend an agent, but in different directions.
MCP connects the agent to external capabilities.
Agent Skills give the agent reusable expertise and procedures.
The problem is not about giving the agent more power.
It is about deciding which power belongs in the runtime, which belongs in application code, which belongs in a skill, and which needs approval before it runs.

At this point in the series, we have an agent that can keep state, manage context, call tools, return structured output, connect through MCP, and load reusable skills.
The next step is orchestration.
Some tasks are too large or too explicit for a single agent call.
In the next article, we will look at multi-agent systems and workflows.

Structured Output in .NET Agents

Lukas Walter — Thu, 14 May 2026 13:30:00 +0000

This is Part 8 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

LLMs are good at generating text. But text is a weak boundary for application code.

Ask a model for e.g., a specific coffee recipe, and the response might look slightly different every time:

a markdown list
a numbered list
bold section titles
missing fields
additional explanations
a disclaimer at the end

That is fine for a chat interface.
It is not, when your application needs to save the result, display it on a UI, route a workflow, or pass the output into another system.

At that point, you do not want “some text”.
You want data with a known shape.

Raw LLM Text Is Hard to Automate

The problem with unstructured output is not that it looks messy.
The problem is that your application has to guess what the model meant.

For example, if the model returns a coffee recipe as plain text, your code may need to extract:

brew method
coffee dose
water amount
grind size
water temperature
brewing steps

That usually means parsing strings.
And string parsing breaks easily.

One response might look like this:

1. V60 recipe: Use 20g coffee and 320g water at 94°C. Grind medium-fine.

The next response might look like this:

### V60 Pour-Over

- Coffee: 20 grams
- Water: 320 grams
- Temperature: 94°C
- Grind: medium-fine

Both are readable for humans.
But for software, they are different formats.
This is why raw LLM text is a fragile integration boundary.

Define the Output Shape in C

Instead of asking the model to return free-form text, you can define the shape you expect in C#.

For example:

public sealed class BrewRecipeSuggestion
{
    public string BrewMethod { get; set; } = string.Empty;
    public double CoffeeGrams { get; set; }
    public double WaterGrams { get; set; }
    public string GrindSize { get; set; } = string.Empty;
    public double WaterTemperatureCelsius { get; set; }
    public List<string> Steps { get; set; } = [];
}

If you want multiple results, you can wrap the list in a response type:

public sealed class BrewRecipeResult
{
    public List<BrewRecipeSuggestion> Recipes { get; set; } = [];
}

Now your application has a contract.
The model is no longer just asked to “write an answer”.
It is requested that something be produced that can be represented as a known C# type.

Using `RunAsync<T>`

With .NET agents, this becomes much cleaner.
Instead of calling the agent and receiving plain text:

var response = await agent.RunAsync(
    "Give me three pour-over coffee recipes.");

You can request a typed result:

AgentResponse<BrewRecipeResult> response =
    await agent.RunAsync<BrewRecipeResult>(
        """
        Give me three pour-over coffee recipes.

        Include:
        - brew method
        - coffee dose in grams
        - water amount in grams
        - grind size
        - water temperature in Celsius
        - brewing steps
        """);

BrewRecipeResult result = response.Result;

The important difference is the boundary.
Your application does not receive a string that it still has to interpret.
It receives an AgentResponse<T>, and the typed result is available through response.Result.

That means you can work with the result directly:

foreach (var recipe in result.Recipes)
{
    Console.WriteLine(
        $"{recipe.BrewMethod}: {recipe.CoffeeGrams}g coffee, " +
        $"{recipe.WaterGrams}g water");
}

This is much easier to use in normal application code.
You can render it in a UI, store it in a database, pass it to another service,validate it and even test it.

What the Framework Does for You

When you call RunAsync<T>, the framework can use the target C# type to describe the expected response shape.
The model is guided toward returning data that matches that structure.
The framework then converts the response into the requested C# type.

Conceptually, the flow looks like this:

C# type
   ↓
Expected response shape
   ↓
Model response
   ↓
Deserialization
   ↓
Typed C# object

That removes a lot of boilerplate.
You do not have to manually inspect markdown, split strings, or have to search for labels in generated text.
You get a typed result that fits into the rest of your .NET code.

Still, keep one thing in mind:

Structured output support can vary by agent type, provider, model, and underlying chat client.
So this is not a reason to stop thinking about validation, fallbacks, and testing.

It is a better application boundary.
Not a replacement for engineering discipline.

What Structured Output Does Not Solve

Structured output solves the shape problem.
It does not solve the truth problem.

A model can return a valid BrewRecipeSuggestion object and still be wrong.

For example:

new BrewRecipeSuggestion
{
    BrewMethod = "V60",
    CoffeeGrams = 12,
    WaterGrams = 1000,
    GrindSize = "very fine",
    WaterTemperatureCelsius = 120,
    Steps =
    [
        "Add coffee.",
        "Pour all water at once.",
        "Wait 30 seconds."
    ]
}

This object may be structurally valid.

It has the expected fields.
It can be deserialized.

Your application can work with it as an object.
But that does not mean it is a good recipe. (The ratio is unrealistic.
The water temperature is impossible for normal brewing.
The steps are questionable.)

Structured output can tell you:

The response has the expected fields
The values can be deserialized
The application can work with the result as an object

It does not guarantee:

The facts are correct
The recommendation is useful
The values are reasonable
The user is allowed to perform the action
The result satisfies your business rules

So keep in mind: typed output should usually be the first gate, not the final gate.

A more robust flow looks like this:

Model output
   ↓
Deserialize into known type
   ↓
Validate required fields
   ↓
Validate ranges and enums
   ↓
Check business rules
   ↓
Accept, reject, retry, or escalate

In this coffee example, you might still check the generated recipe:

private static void Validate(BrewRecipeSuggestion recipe)
{
    if (string.IsNullOrWhiteSpace(recipe.BrewMethod))
    {
        throw new InvalidOperationException("Brew method is required.");
    }

    if (recipe.CoffeeGrams <= 0)
    {
        throw new InvalidOperationException("Coffee dose must be greater than zero.");
    }

    double ratio = recipe.WaterGrams / recipe.CoffeeGrams;

    if (ratio is < 12 or > 20)
    {
        throw new InvalidOperationException(
            "Brew ratio is outside the supported range.");
    }

    if (recipe.WaterTemperatureCelsius is < 85 or > 100)
    {
        throw new InvalidOperationException(
            "Water temperature must be between 85°C and 100°C.");
    }

    if (recipe.Steps.Count == 0)
    {
        throw new InvalidOperationException("At least one brewing step is required.");
    }
}

Structured output makes validation easier.
It does not remove the need for validation.

Practical Example: Intent Routing

One useful pattern is intent routing.

Imagine an assistant that can answer questions about coffee brewing and guitar tone.
A user might ask:

How do I get a dirty Hendrix tone on my Strat?

or:

Can you give me a V60 recipe for 18g of coffee?

You could first send the user request to a small routing agent.
That agent should not answer the question.
It should only classify the intent.

For example:

public enum AssistantIntent
{
    CoffeeBrewing,
    GuitarTone,
    Unknown
}

public sealed class IntentResult
{
    public AssistantIntent Intent { get; set; }
    public double Confidence { get; set; }
    public string Reason { get; set; } = string.Empty;
}

Then you can request a typed result:

string userMessage = "How do I get a dirty Hendrix tone on my Strat?";

AgentResponse<IntentResult> intentResponse =
    await intentAgent.RunAsync<IntentResult>(
        $"""
        Classify the user's request.

        Return only the intent.
        Do not answer the user's question.

        Supported intents:
        - CoffeeBrewing
        - GuitarTone
        - Unknown

        User request:
        {userMessage}
        """);

IntentResult intent = intentResponse.Result;

After that, your C# code stays simple:

var response = intent.Intent switch
{
    AssistantIntent.CoffeeBrewing => await coffeeAgent.RunAsync(userMessage),
    AssistantIntent.GuitarTone => await guitarAgent.RunAsync(userMessage),
    _ => await fallbackAgent.RunAsync(userMessage)
};

This is much cleaner than asking the model to return text like:

The user is probably asking about guitar tone.

and then trying to parse that sentence.

The routing decision becomes a typed value.
Your application code can switch on it.
You can log it, test it and add validation around it.

For example:

if (intent.Confidence is < 0 or > 1)
{
    throw new InvalidOperationException(
        "Intent confidence must be between 0 and 1.");
}

if (intent.Confidence < 0.7)
{
    response = await fallbackAgent.RunAsync(userMessage);
}

Again, the typed object does not make the model perfect.
But it gives your application a reliable shape to work with.

Where Structured Output Fits

Structured output is useful whenever the model response has to cross into application logic.

Common examples:

extracting fields from user input
classifying intent
routing workflows
generating UI-ready data
creating database records
preparing tool arguments
returning validation results
producing evaluation summaries
generating configuration-like output

The pattern is always the same:

Do not let free-form text leak into places where your application expects structured data.
Use a typed boundary.

Conclusion

Structured output is one of the most important patterns when combining LLMs with traditional software systems.
Not because it makes the model perfect.
But because it gives your application a clear contract.

Instead of parsing unstable text, your .NET code can work with known types, which makes the system easier to build, test, and reason about.

LLM output should not be treated as a string once it enters your application boundary.
It should become a typed object.
And from there, normal engineering practices apply again.

We now know that structured output defines how an agent answers.
But useful agents also need ways to access capabilities beyond the current prompt.

In the previous post, we looked at local C# function tools: methods exposed directly from your .NET application.

Next, we will move one step further and look at MCP tools and Agent Skills.
MCP tools expose capabilities from external systems through the Model Context Protocol.
Agent Skills package reusable instructions, domain knowledge, scripts, and procedures that can be loaded when needed.

Tools and Dependency Injection in Microsoft Agent Framework

Lukas Walter — Mon, 11 May 2026 13:30:00 +0000

This is Part 7 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

When words are not enough

So far, our agent can answer questions, stream responses, remember conversations, reduce chat history, and receive dynamic context.

But it still has one major limitation: it can only talk.

An LLM does not know your current application state by default. It cannot query your database, calculate values from your domain model, or place an order unless your application exposes that capability.

This is where tools come in.

A tool is a controlled C# function that the model can request during a run. The model does not execute arbitrary code. It can only call the functions you explicitly provide.

The flow looks like this:

The user asks something that requires application logic.
The model requests a tool call instead of producing a final answer.
The framework invokes the matching C# method.
The result is passed back to the model.
The model uses that result to answer the user.

A small tool

Let's stay with the barista agent from the previous article.

One useful tool is a brew recipe calculator. This does not need a database or external service. It is deterministic domain logic.

using System.ComponentModel;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

public sealed record BrewRecipe(
    double CoffeeGrams,
    double WaterGrams,
    string Ratio);

[Description("Calculates water amount for a pour-over coffee recipe.")]
public static BrewRecipe CalculatePourOverRecipe(
    [Description("Coffee dose in grams.")] 
    double coffeeGrams,
    [Description("Water per gram of coffee. Use 16 for a 1:16 ratio.")]
    double waterPerGram)
{
    return new BrewRecipe(
        CoffeeGrams: coffeeGrams,
        WaterGrams: Math.Round(coffeeGrams * waterPerGram, 1),
        Ratio: $"1:{waterPerGram}");
}

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are a barista assistant.",
    tools: [AIFunctionFactory.Create(CalculatePourOverRecipe)]);

The Description attributes are important. They become part of the function schema that the model sees when deciding whether and how to call the tool.

But keep in mind, that they also cost tokens. Keep them short and concrete. The goal is not to document your whole domain. The goal is to help the model make the correct choice.

Now, a prompt like this can trigger the tool:

var response = await agent.RunAsync(
    "I want to brew 18 grams of coffee at 1:16. How much water should I use?");

The model can call CalculatePourOverRecipe, receive the BrewRecipe, and then explain the result in normal language.

Registering multiple tools

One tool is easy to register manually.
More tools get noisy quickly:

Calculate a pour-over recipe
Calculate espresso yield
Convert a ratio into grams
Suggest a grind adjustment

Reflection can reduce boilerplate, but do not register every public method on a class. That would turn every method into an AI-callable method.
Use an explicit marker attribute or a whitelist.

[AttributeUsage(AttributeTargets.Method)]
public sealed class BaristaToolAttribute : Attribute
{
}

var brewTools = new BrewTools();

IList<AITool> tools = typeof(BrewTools)
    .GetMethods(BindingFlags.Instance | BindingFlags.Public)
    .Where(method => method.GetCustomAttribute<BaristaToolAttribute>() is not null)
    .Select(method => (AITool)AIFunctionFactory.Create(method, brewTools))
    .ToList();

This keeps registration convenient without exposing the whole class as an execution surface.

Tools with dependency injection

Calculation tools are useful, but real applications usually need services.

For example, the barista agent might need to check which beans are currently available. That data belongs within your application boundary, perhaps in a repository, an API client, or a database context.

To bridge this gap, you simply add an IServiceProvider parameter to your tool's method. The framework automatically resolves this dependency locally at runtime, completely hiding it from the AI model's tool schema.

[Description("Finds available coffee beans by roast level and flavor note.")]
public static Task<IReadOnlyList<CoffeeBean>> FindBeansAsync(
    [Description("Roast level, for example light, medium, or dark.")]
    string roast,
    [Description("Flavor note, for example chocolate, citrus, or nutty.")]
    string flavorNote,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var inventory = services.GetRequiredService<ICoffeeInventory>();

    return inventory.FindBeansAsync(
        roast,
        flavorNote,
        cancellationToken);
}

Then pass the service provider when creating the agent:

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You help users choose coffee beans based on taste and brew method.",
    tools: [AIFunctionFactory.Create(FindBeansAsync)],
    services: app.Services);

The model only supplies roast and flavorNote. The inventory service still comes from your application.
This distinction is important because model-supplied arguments are untrusted input. Services resolved from DI are trusted application dependencies.

Side effects need approval

Reading inventory is one thing. Placing an order is different.

Tools that spend money, delete data, send messages, or affect users should not run silently. For those cases, wrap the function in an approval-required tool.

[Description("Orders coffee beans from the supplier. Use only after explicit confirmation.")]
public static Task<string> OrderBeansAsync(
    string productCode,
    int bags,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var orders = services.GetRequiredService<ICoffeeOrderService>();
    return orders.PlaceOrderAsync(productCode, bags, cancellationToken);
}

AIFunction orderBeans = AIFunctionFactory.Create(OrderBeansAsync);
AIFunction approvalRequiredOrderBeans = new ApprovalRequiredAIFunction(orderBeans);

With approval enabled, the agent can return a FunctionApprovalRequestContent instead of running the tool immediately. Your application then shows the function name and arguments to the user and sends the approval or rejection back into the same session.

The exact support depends on the provider and client type. Function tools are broadly supported, but approval is not universal across every provider.

Middleware and monitoring

Approval is for high-risk actions.
Middleware is for cross-cutting concerns such as logging, validation, metrics, or blocking suspicious arguments.

Function calling middleware lets you inspect the function name and arguments before the method runs:

async ValueTask<object?> LogToolCallAsync(
    AIAgent agent,
    FunctionInvocationContext context,
    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
    CancellationToken cancellationToken)
{
    Console.WriteLine($"Tool call: {context.Function.Name}");
    return await next(context, cancellationToken);
}

Do not treat logging as authorization. Middleware is useful for observing and validating calls, but normal application permissions still need to exist behind the tool. Additionally, for standard logging and metrics, consider using the framework's native .UseOpenTelemetry() extension rather than writing custom logging middleware from scratch.

When to use tools

Use tools when:

The agent needs current application state
The answer depends on deterministic business logic
The result must come from your database, API, or domain model
The action is narrow, describable, and easy to validate

Do not use tools when:

A normal model answer is enough
The function would become a broad "do anything" escape hatch
The action cannot be validated before execution
The tool would bypass existing authorization or business rules
The side effect is too risky to run without approval

Tools should expose controlled capabilities, not bypass application design.

Conclusion

Tools turn an agent from a text generator into part of an application workflow.

For simple logic, AIFunctionFactory.Create is enough. For application behavior, pass services into the agent and keep dependencies behind your existing DI boundary. For state-changing actions, add approval and monitoring before letting the agent execute anything important.

Our agent can now use tools and request approval before executing them. But sometimes we do not want a conversational answer at all. We want a reliable C# object that can be validated, stored, or passed to the next workflow step.

In the next article, we will look at Structured Output.

RAG with EF Core and pgvector

Lukas Walter — Thu, 07 May 2026 13:30:00 +0000

You can read the original post over on lukaswalter.dev.

Developers often start RAG apps using tutorials that recommend dedicated vector databases.

Step 1: Sign up for a vector database like Pinecone or Qdrant.

This adds a costly SaaS service to your architecture or requires you to manage it yourself.

And if you are building line-of-business applications in .NET, dedicated vector databases often introduce another problem: Data Synchronization.

If core entities like Products, Customers, or SupportTickets exist in a relational database and vector embeddings reside in a specialized vector DB, you face a distributed systems challenge. What if a product is deleted or its description updated? Synchronizing datastores becomes daunting.

A pragmatic solution? Store your vectors alongside your relational data.

Using PostgreSQL, the pgvector extension transforms your relational database into a powerful vector search engine. Better yet, it integrates seamlessly with Entity Framework Core.

You can build a RAG application without adding any new infrastructure.

Step 1: Install the Required Packages

Start by adding the pgvector EF Core integration package.
Run the following commands in your project:

dotnet add package Pgvector.EntityFrameworkCore

Note: The pgvector extension must be available in your PostgreSQL installation and enabled in the database you use. If you use the pgvector/pgvector Docker image, the extension is already installed, but it still needs to be enabled per database.

You can enable it manually with:

CREATE EXTENSION IF NOT EXISTS vector;

Or let EF Core handle it through:

modelBuilder.HasPostgresExtension("vector");

Step 2: Define Your Entity

Suppose you’re developing an internal knowledge base. With a Document entity, enhance storage by adding a Vector property for embeddings generated by an embedding model, for example OpenAI’s text-embedding-3-small, which produces 1536-dimensional vectors by default.

using Pgvector;
using System.ComponentModel.DataAnnotations.Schema;

public class Document
{
    public int Id { get; set; }

    public string Title { get; set; }

    public string Content { get; set; }

    // 1536 is the default dimension for OpenAI text-embedding-3-small.
    // Match this dimension to the embedding model you actually use.
    [Column(TypeName = "vector(1536)")]
    public Vector Embedding { get; set; }

    // We can still have standard relational data!
    public int TenantId { get; set; } 
}

Note: text-embedding-3-small produces 1536-dimensional embeddings by default.
text-embedding-3-large produces 3072-dimensional embeddings by default. pgvector can store vectors larger than 2000 dimensions, but HNSW/IVFFlat indexes for the regular vector type support up to 2000 dimensions. If you use text-embedding-3-large, either request fewer dimensions from the embedding API or evaluate halfvec/HalfVector for indexed search.

Step 3: Configure the DbContext

Configure Entity Framework Core to activate the vector extension in PostgreSQL. Add an HNSW (Hierarchical Navigable Small World) index to the embedding column.
For small datasets, exact search without an index can be fine. As the number of vectors grows, an approximate index such as HNSW often becomes important for latency. Just remember that HNSW trades some recall for speed.

pgvector can handle larger datasets efficiently, but HNSW is not magic. It is an approximate nearest-neighbor index with trade-offs between recall, speed, memory usage, and build time.

For HNSW indexes, tune m and ef_construction during index creation. At query time, tune hnsw.ef_search if you need better recall. Higher values usually improve recall, but increase query cost. For filtered vector search, also index your relational filter columns, for example TenantId, and test the query plan with realistic data.

using Microsoft.EntityFrameworkCore;
using Pgvector.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public DbSet<Document> Documents { get; set; }

    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasPostgresExtension("vector");

        modelBuilder.Entity<Document>()
            .HasIndex(d => d.TenantId);

        modelBuilder.Entity<Document>()
            .HasIndex(d => d.Embedding)
            .HasMethod("hnsw")
            .HasOperators("vector_cosine_ops")
            .HasStorageParameter("m", 16)
            .HasStorageParameter("ef_construction", 64);
    }
}

Make sure you register the vector types in your Program.cs when configuring the DbContext:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(
        builder.Configuration.GetConnectionString("DefaultConnection"),
        o => o.UseVector() // <-- Don't forget this!
    ));

Step 4: Querying with LINQ

Because our vectors live in the same database as our relational data, we can combine semantic vector search with traditional SQL filtering in a single LINQ query.

Dedicated vector databases also support metadata filtering. Qdrant and Pinecone, for example, both provide filtered vector search. The difference is not that filtering is impossible elsewhere. The difference is architectural: if your source of truth already lives in PostgreSQL, keeping vectors, metadata, deletes, updates, permissions, and document versions in sync across another datastore adds additional system complexity.

public async Task<List<Document>> SearchKnowledgeBaseAsync(int currentTenantId, string userQuestion)
{
    // 1. Turn the user's question into a vector using your preferred AI library 
    // (e.g., Microsoft.Extensions.AI)
    float[] embeddingArray = await _aiService.GenerateEmbeddingAsync(userQuestion);
    var queryVector = new Vector(embeddingArray);

    // 2. Combine vector search with relational filters
    var relevantDocs = await _dbContext.Documents
        // Relational filter: scope results to the current tenant
        .Where(d => d.TenantId == currentTenantId)
        // Vector Search: Order by semantic similarity using Cosine Distance
        .OrderBy(d => d.Embedding.CosineDistance(queryVector))
        .Take(5)
        .ToListAsync();

    return relevantDocs;
}

Combining Relational Filters and Vector Search

When you call ToListAsync(), EF Core translates the CosineDistance() method directly into pgvector’s native <=> operator.

PostgreSQL can combine relational filters and vector ordering in one query. For approximate HNSW indexes, filtered search still needs proper indexing and tuning, especially for selective tenant filters.

The Takeaway

You don’t always need a dedicated vector database to build useful RAG features.

If your application already uses PostgreSQL and your retrieval data is tightly coupled with relational business data, pgvector can be a very pragmatic starting point.

You keep embeddings, metadata, permissions, and source records close together. You can query them through EF Core. And you avoid introducing a second datastore until you actually need one.

Dedicated vector databases still have their place, especially at a larger scale or when vector search becomes a standalone platform concern. But for many .NET applications, PostgreSQL with pgvector is enough to start.

Runnable Sample

I also created a small runnable sample repository for this post.

Repository: GitHub Repo

The sample uses a deterministic embedding service so it can run locally without an OpenAI or Azure OpenAI API key.
That service is only there to make the demo reproducible. It is not meant to produce production-quality semantic embeddings. For real applications, replace it with embeddings from your actual embedding model, for example text-embedding-3-small.

Dynamic Agent Context with AIContextProvider

Lukas Walter — Wed, 06 May 2026 13:30:00 +0000

This is Part 6 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

When static prompts are no longer enough

Most agents are created with fixed system prompts and tools. But as we need more intelligent systems, we sometimes need to adapt them to the situation, user, or time.

The framework offers AIContextProviders for this purpose.

These provide context to AI agents and can be chained together to connect multiple sources.

Providers are executed in the order they are registered, allowing you to layer multiple context modifications in a predictable way. You can configure the sequence in your agent's setup, ensuring that context from earlier providers is available to those that run later in the chain. This lets you hook into the pipeline before and after the LLM call, helping avoid unexpected behavior by keeping the flow transparent.

The Architecture of Context Providers

To create a custom provider, we inherit from the AIContextProvider class. The Microsoft Agents framework handles all the complex routing and pipeline management behind the scenes, leaving us with just two key methods to override for our custom logic:

ProvideAIContextAsync (Pre-Call): This method is called just before the request is sent. Here we have full access to the current session, the previous instructions, and the pending message.
StoreAIContextAsync (Post-Call): This method fires after the LLM has generated the response, but before it is returned to the user. Here, we can analyze the final response or any errors that might have occurred.

Examples

Memory

Let's say we are building a barista agent for the coffee junkies among us.

We want the AI to remember the user's specific brewing habits and gear.
For example, when the user says, "I just bought a V60 pour-over" or "I really don't like acidic coffees."

ProvideAIContextAsync fetches user facts from the database and appends them as context to the instructions for the call. E.g., "User brews with a V60, prefers a 1:15 ratio, and loves dark, chocolatey roasts."

StoreAIContextAsync passes the user request to a cheap extractor agent, which finds new facts to save for future use, enabling the barista to learn over time.

public class BaristaMemoryProvider : AIContextProvider
{
    private const string UserIdStateKey = "UserId";
    private readonly ICoffeeDatabase _db;
    private readonly IExtractorAgent _extractor;
    public BaristaMemoryProvider(ICoffeeDatabase db, IExtractorAgent extractor)
    {
        _db = db;
        _extractor = extractor;
    }
    protected override async ValueTask<AIContext> ProvideAIContextAsync(
        AIContextProvider.InvokingContext context,
        CancellationToken cancellationToken = default)
    {
        string userId = GetUserId(context.Session);
        var userPrefs = await _db.GetPreferencesAsync(userId, cancellationToken);
        if (userPrefs is null)
        {
            return new AIContext();
        }
        return new AIContext
        {
            Instructions =
                $"User Coffee Profile: Brewer: {userPrefs.Brewer}, " +
                $"Ratio: {userPrefs.Ratio}, Roast: {userPrefs.RoastType}."
        };
    }
    protected override async ValueTask StoreAIContextAsync(
        AIContextProvider.InvokedContext context,
        CancellationToken cancellationToken = default)
    {
        var lastUserMessage = context.RequestMessages
            .LastOrDefault(m => m.Role == ChatRole.User)?
            .Text;
        if (string.IsNullOrWhiteSpace(lastUserMessage))
        {
            return;
        }
        var extractedFact = await _extractor.ExtractNewFactsAsync(lastUserMessage, cancellationToken);
        if (extractedFact is not null)
        {
            string userId = GetUserId(context.Session);
            await _db.SaveNewPreferenceAsync(userId, extractedFact, cancellationToken);
        }
    }
    private static string GetUserId(AgentSession? session) =>
        session?.StateBag.TryGetValue<string>(UserIdStateKey, out var userId) == true
            ? userId
            : "anonymous";
}

Optimize Tokens

Let's now imagine a virtual Guitar Tech agent. This agent is equipped with many tools (ScaleGenerator, TabFetcher, AmpEQDialer, PedalBoardRouter, Metronome, etc.).

Now we need to send the schema for all tools with every request to the LLM.
Even if the user just says, "Hey man". This inevitably wastes hundreds or thousands of tokens per call.

This time, we use ProvideAIContextAsync to quickly pass the incoming user message to a fast, efficient agent whose primary task is to evaluate user intent. (Is this request about music theory, finding tabs, or dialing in a tone?)

If the user asks, "How do I get a dirty Hendrix tone on my Strat?", the provider injects only the AmpEQDialer and PedalBoardRouter tools into the context just before the main LLM call.

The main agent receives a tailored and lean toolset. This approach saves input tokens and reduces the risk of the AI making unnecessary tool calls.

public class GuitarTechToolProvider : AIContextProvider
{
    private readonly IRoadieAgent _roadieRouter;
    private readonly IToolRegistry _tools;
    public GuitarTechToolProvider(IRoadieAgent roadieRouter, IToolRegistry tools)
    {
        _roadieRouter = roadieRouter;
        _tools = tools;
    }
    protected override async ValueTask<AIContext> ProvideAIContextAsync(
        AIContextProvider.InvokingContext context,
        CancellationToken cancellationToken = default)
    {
        var lastMsg = context.RequestMessages
            .LastOrDefault(m => m.Role == ChatRole.User)?
            .Text;
        var intent = await _roadieRouter.DetermineIntentAsync(lastMsg, cancellationToken);
        var selectedTools = new List<AITool>();
        switch (intent)
        {
            case Intent.ToneAndGear:
                selectedTools.Add(_tools.GetTool("AmpEQDialer"));
                selectedTools.Add(_tools.GetTool("PedalBoardRouter"));
                break;
            case Intent.MusicTheory:
                selectedTools.Add(_tools.GetTool("ScaleGenerator"));
                break;
        }
        return new AIContext
        {
            Tools = selectedTools
        };
    }
}

Guardrails & Validation

For this example, we will use an agent that helps us build Lego models. Let's ask it for a creative way to connect two Lego plates at a strange 45-degree angle. LLMs are eager to please and sometimes ignore existing rules. And though the agent might confidently suggest using superglue. Obviously, we need a strict safety net to avoid ruining our Lego set because of a wrong answer.

Via ProvideAIContextAsync, we inject a strict boundary condition right alongside the user's prompt: "Constraint: You are a purist Lego Master Builder. Only reference legal, official connection techniques. Do not suggest modifying bricks, cutting, or using adhesives."

But even with strict boundaries, the agent could give us the wrong answer.

StoreAIContextAsync grabs the generated response before it is returned to the user.
Again, we run the response through a fast, lightweight agent that looks for out-of-bounds keywords such as "glue", "stress", and "cut".

If the validator detects an illegal technique, we can log the error immediately, strip the offending paragraph from the answer, or throw an exception to trigger a silent, automatic retry.

public class LegoGuardrailProvider : AIContextProvider
{
    private readonly IValidatorAgent _validator;
    public LegoGuardrailProvider(IValidatorAgent validator)
    {
        _validator = validator;
    }
    protected override ValueTask<AIContext> ProvideAIContextAsync(
        AIContextProvider.InvokingContext context,
        CancellationToken cancellationToken = default)
    {
        return ValueTask.FromResult(new AIContext
        {
            Instructions = "Constraint: Only reference legal Lego connection techniques."
        });
    }
    protected override async ValueTask StoreAIContextAsync(
        AIContextProvider.InvokedContext context,
        CancellationToken cancellationToken = default)
    {
        var lastAssistantMsg = context.ResponseMessages?
            .LastOrDefault()?
            .Text;
        var validation = await _validator.CheckForIllegalTechniquesAsync(
            lastAssistantMsg,
            cancellationToken);
        if (!validation.IsSafe)
        {
            throw new AIValidationException($"Safety violation: {validation.Reason}");
        }
    }
}

Alternatives

In addition to the AIContextProvider, the framework also offers the MessageAIContextProvider. Instead of adjusting system instructions or tools in the background, this provider injects actual chat messages into the conversation.

You can register the MessageAIContextProvider as middleware. This is extremely helpful when working with agents we haven't created ourselves and whose parameters we cannot directly configure (such as remote agents connected via the A2A (Agent-to-Agent) protocol). By using it as middleware, we can still dynamically inject additional messages into them without needing access to their internal configuration.

Conclusion

Context Providers are really helpful in many situations. Whether you need dynamic on-the-fly prompts, an intelligent background memory, or massive token optimization through tool injection.

We now know how to tame our chat histories, dynamically inject memory, and optimize our token budgets. But what happens when words are no longer enough, and our AI needs to interact with the real world?

In the next part of this series, we will explore Tools and Dependency Injection, and learn how to teach your AI to execute actual actions!

Controlling Token Growth with Chat Reducers

Lukas Walter — Mon, 04 May 2026 13:30:00 +0000

This is Part 5 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

The Token Trap in Long Chats

As we have seen in previous articles, stateless LLMs require us to continuously send the entire previous chat history so the AI can retain context.

As each message is added to ongoing chats, input tokens accumulate. Even after many previous interactions, asking a simple question like “What is 1+1?” still results in the entire conversation history being sent.
This will come with its own problems, like a full context window and rising costs.
To address this, the framework introduces Chat Reducers.

Message Counting

The simplest form of a Chat Reducer is “Message Counting”.
Here, you define a target count. The reducer keeps the most recent messages up to that count, while preserving the first system message if present.

To use this with an agent, configure a ChatHistoryProvider, such as InMemoryChatHistoryProvider, in ChatClientAgentOptions and pass the reducer through InMemoryChatHistoryProviderOptions.

// 1. Define an IChatReducer that keeps the latest 10 non-system messages
IChatReducer messageCountReducer = new MessageCountingChatReducer(10);

// 2. Configure the agent options with an in-memory chat history provider
var agentOptions = new ChatClientAgentOptions
{
    ChatHistoryProvider = new InMemoryChatHistoryProvider(
        new InMemoryChatHistoryProviderOptions
        {
            ChatReducer = messageCountReducer
        })
};

// 3. Create your agent from an IChatClient
AIAgent agent = chatClient.AsAIAgent(agentOptions);

The major advantage is that the token count and latency drop drastically the moment the limit takes effect.

A limitation is that earlier context information is no longer available. If you share your name at the start of the conversation and refer to it after messages have been removed, the AI cannot recall it.

Summarization

A more sophisticated approach is the SummarizingChatReducer.
This method uses an IChatClient to summarize older messages during reduction.

To set it up, you define the target count and an optional threshold. The target count is the number of recent messages that should remain after the reduction. The threshold controls how many messages beyond that target count are allowed before summarization is triggered.

When the conversation grows beyond targetCount + threshold, the reducer summarizes older messages. This summary replaces the old messages, while the most recent chat messages remain unchanged.

A key feature for advanced scenarios is prompt customization. The summarization prompt or logic used can be tailored to fit your needs. This allows you to adapt the summary process via the SummarizationPrompt property. This way, you can adapt the logic to your application's domain, highlight specific information, or enforce a particular writing style, resulting in summaries that are more useful and relevant for your use case.

// 1. You need a base IChatClient to perform the summarization calls
IChatClient innerChatClient = chatClient; // e.g., Azure OpenAI, OpenAI, or Ollama
// 2. Configure the reducer
// This keeps 1 recent message after summarization.
// threshold is "messages allowed beyond targetCount", so 9 means summarization
// starts once the history grows beyond 10.
IChatReducer summaryReducer = new SummarizingChatReducer(
    chatClient: innerChatClient,
    targetCount: 1,
    threshold: 9)
{
    SummarizationPrompt =
        "Summarize the following conversation while keeping technical specs and user names."
};
// 3. Configure the agent options with the reducer
var summaryAgentOptions = new ChatClientAgentOptions
{
    ChatHistoryProvider = new InMemoryChatHistoryProvider(
        new InMemoryChatHistoryProviderOptions
        {
            ChatReducer = summaryReducer
        })
};
// 4. Create the agent
AIAgent smartAgent = chatClient.AsAIAgent(summaryAgentOptions);

A significant benefit is that details from earlier in the conversation, such as your name or instructions, are included in the summary, allowing the AI to retain relevant information.

The disadvantage is that generating this summary with the LLM also costs some tokens. Additionally, summarization introduces a slight performance impact, as the agent must pause and wait for the model to process and return the summary before proceeding. This can temporarily increase the latency for a user's next message each time summarization is triggered. In high-traffic scenarios, frequent summarizations may also affect overall throughput. You should consider these trade-offs and test the reducer settings under expected workloads to ensure that performance remains within acceptable limits.

Tip: To keep costs and latency low, you don't have to use your powerful main model for summarization. You can pass a smaller, faster model as the innerChatClient.

Note: The framework doesn't provide an automatic fallback if summarization fails. A robust implementation should include a retry policy (via the IChatClient pipeline) or a custom mechanism to retain recent messages, ensuring the conversation remains fluid even in the event of, e.g., an API error.

Practical Comparison

Which reducer you choose depends heavily on your specific use case.

It is always a balancing act between the value of retaining old messages, the cost of tokens, and the model's maximum context size.

Use pure truncation (Message Counting) for simple use cases, where old topics quickly become irrelevant.

Use Summarization for complex, in-depth agents, where the user might still want to refer back to earlier facts even after 15 minutes of chatting.

Feature	Message Counting (Truncation)	Summarization
Best For	Simple bots, high-volume support	Complex assistants, deep analysis
Context	Lost once it drops off the list	Retained in condensed form
Token Cost	Lowest (zero cost for reduction)	Moderate (costs tokens to summarize)
Complexity	Set and forget	Requires custom prompts & error handling

Conclusion

Chat Reducers let us control conversation length and token costs efficiently.

Next, we'll explore AIContextProviders, which allow agents to dynamically inject context and extract new memories, providing persistent memory while optimizing token usage.

State Management and Chat History

Lukas Walter — Fri, 01 May 2026 14:30:00 +0000

This is Part 4 of my series on the Microsoft Agent Framework. You can read the original post over on lukaswalter.dev.

Introduction: Why AIs are stateless

Large Language Models (LLMs) are stateless. Ask, “How many levels are in Super Mario 64?” and you’ll get an answer. Ask, “How many stars are there?” right after, and the AI often won’t recognize you mean the game. It may return an unrelated number.

Each LLM request is isolated. For AI to understand context, you must send the entire conversation history each time.

With every additional chat question, the number of input tokens rises. You pay for the entire historical text sent back and forth.

The Basic Approach: Agent Sessions

In-Memory Storage:

To solve this, the Agent Framework provides the concept of Agent Sessions.
Instead of just calling agent.runAsync("Question"), you create a session and include it with each call.
The framework then automatically appends the new messages to a list in the background and sends them with the next call.

// Creating an Agent Session to store short-term context
var session = await agent.GetNewSessionAsync(); 

// Passing the session with each request
var response1 = await agent.RunAsync("How many levels are in Super Mario 64?", session);
var response2 = await agent.RunAsync("How many stars are there?", session); 
// The AI now understands you are still talking about the game!

By default, storage is in-memory only. If the app closes or the server restarts, the AI’s memory is wiped.

The Solution for Long-Term Memory: The ChatHistoryProvider

To offer features like ChatGPT’s left sidebar, where past chats resume, persistence is needed. This is where ChatHistoryProvider helps.

The StateBag Concept

Each session has a StateBag, a flexible key-value store. Store a unique session ID (e.g., a GUID) as a reference for your database or file system. By keeping the ID separate from the chat history, you can securely reference and restore sessions.

Practical Implementation: Saving and Restoring

To build a provider, inherit from the ChatHistoryProvider class and override two main methods:

public class MyDatabaseChatHistoryProvider : ChatHistoryProvider
{
    // Step 1 - Saving
    public override async Task StoreChatHistoryAsync(ChatHistoryContext context)
    {
        // Retrieve our Session ID from the StateBag
        var sessionId = context.Session.StateBag["SessionId"].ToString();

        // Grab the newest messages from the context
        var newRequest = context.RequestMessages;
        var newResponse = context.ResponseMessages;

        // Serialize and save the context to disk or a database record
        await SaveMessagesToDatabaseAsync(sessionId, newRequest, newResponse);
    } 

    // Step 2 - Restoring
    public override async Task<IReadOnlyList<ChatMessage>> ProvideChatHistoryAsync(ChatHistoryContext context)
    {
        // Check if the StateBag already has a Session ID
        if (!context.Session.StateBag.TryGetValue("SessionId", out var sessionIdObj))
        {
            // It's a new session, create a unique ID and store it in the StateBag
            context.Session.StateBag["SessionId"] = Guid.NewGuid().ToString();
            return Array.Empty<ChatMessage>(); // No history to load yet
        }

        // If the ID exists, read the previous chat messages from your database
        var sessionId = sessionIdObj.ToString();
        var historicalMessages = await LoadMessagesFromDatabaseAsync(sessionId);

        return historicalMessages; 
    }
}

Step 1 - Saving (StoreChatHistoryAsync):

The framework calls this method after the AI responds, but before the user sees it. Here, you can serialize the context and store it. Like writing JSON to disk or a database record.

Step 2 - Restoring (ProvideChatHistoryAsync):

When a user returns and you pass a session with an existing StateBag ID, this method runs. It reads the saved file or database, deserializes the text into chat messages, and hands them to the agent. Crucially, it returns the deserialized messages to the agent so the AI has the context loaded before it processes the user's new prompt. The AI is caught up and ready to continue.

Conclusion

With ChatHistoryProvider, you control chat storage. The AI remembers the user, even after long breaks.

Now our AI remembers whole conversations. But if the history grows too large, hitting token limits and increasing costs, what then? Next, we’ll explore Chat Reducers—tools for summarizing or trimming old messages to save tokens.

DEV Community: Lukas Walter

Build and deploy an MCP server with .NET and Azure Container Apps

Prerequisites

Project structure

Create the projects

Register the MCP server

Add tools with attributes

Run the server locally

Call the MCP server from C

Add simple API-key protection

Inspect with MCP Inspector

Containerize the server

Deploy to Azure Container Apps

Cleanup

What I would change for a real system

Takeaway

Further reading

Microsoft Agent Framework Workflows: When to Use Them and When to Stay in C#

Why Workflows Exist

Executors and Edges

Four Workflow-Related Patterns

Sequential Workflows

Concurrent Workflows

Handoff Workflows

Human-in-the-Loop Workflows

The Guitar Order Example

The Workflow-Heavy Version

The Normal C# Version

Decision Matrix: Workflow Engine vs. Normal C

When I Would Use Workflows

When I Would Not Use Workflows

External Workflow Engines

A Practical Rule of Thumb

Conclusion

Further Reading

Agents as Tools in Microsoft Agent Framework

The Problem with One Tool-Heavy Agent

Agents as Tools

A Small Example

What Actually Saves Tokens

Delegation Is Model-Driven

Context Does Not Automatically Transfer

Keep Inner Agents Focused

Watch the Side Effects

Agents as Tools vs. Workflows

When to Use Agents as Tools

Conclusion

Further Reading

Why CancellationToken Matters More in .NET AI Systems

Why AI Workloads Expose This Problem

The Mental Model

Start at the HTTP Boundary

Streaming Makes Cancellation More Important

RAG Pipelines Need the Same Discipline

Embedding Jobs Are Cancellation Hotspots

Tools Need Cancellation Too

Timeouts Are Policy, Cancellation Is Plumbing

What Not To Do

Logging Cancellation Like a Failure Creates Noise

A Checklist for .NET AI Code

When To Use Cancellation Tokens

When Not To Rely On Cancellation Tokens

Final Thoughts

Official References

Manual Multi-Agent Routing in .NET

The Problem with One Large Agent

The Intent Agent

Use Structured Output for the Routing Decision

C# Takes the Wheel

Add Confidence Before Routing Expensive Work

Make Routing Observable

Why This Saves Tokens

Manual Routing vs. Workflow Engine

When to Use Manual Intent Routing

Conclusion

Further Reading

Extending .NET Agents with MCP and Agent Skills

MCP Is for External Capabilities

MCP Is Still a Trust Boundary

Keep the MCP Tool Surface Small

Using `RunAsync<T>`