DEV Community: Lukas Walter

Human-in-the-Loop Agents: When the AI Must Ask Before Acting

Lukas Walter — Thu, 02 Jul 2026 15:30:00 +0000

This is Part 15 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 multimodal agents and the boundary around uploaded files.
This post moves to a more uncomfortable boundary: actions.

The rule I care about here is simple:

The model can ask for a risky action.
It should not be the authority that decides whether that action is allowed to run.

Prompts can explain how the agent should behave, but approval is an application boundary.
If an agent can deploy to production, send an email, place an order, delete data, change permissions, or publish content, the system needs a real stop before the tool executes.

Microsoft Agent Framework gives you two useful building blocks for that:

approval-required function tools
workflow request and response handling

The first one is enough for many interactive agent flows.
The second one matters once approval can be delayed, audited, resumed, or folded into a larger process.

Approval is not a nicer prompt

A weak design usually starts here:

You are a careful assistant.
Always ask the user before doing anything dangerous.

That instruction is not worthless.
It can improve the agent's behavior.
It is still not a boundary.

The model can misunderstand the situation.
A later message can override the instruction.
Another agent can hide the tool call.
The UI can show a friendly summary while the actual function arguments say something else.

A stronger design looks like this:

agent wants to call tool
-> framework emits approval request
-> application shows exact tool name and arguments
-> human approves or rejects
-> application sends the decision back
-> tool executes only if approved

That is the boundary.
The model requests the action.
The application decides whether the action continues.

Start with the side effects

Before adding Agent Framework approval code, classify the tools.

Not every tool needs human review.
If every read-only lookup asks for approval, users will stop trusting the flow and developers will eventually disable it.
Approval should sit around real risk.

Tool type	Example	Approval default
Read-only lookup	Search docs, check deployment status, read inventory	Usually no
Drafting	Draft email, create deployment plan, prepare support reply	Usually no, unless auto-published
Reversible write	Create ticket, update draft record, reserve item temporarily	Sometimes
External side effect	Send email, deploy release, charge card, place order	Usually yes
Destructive action	Delete data, revoke access, overwrite production config	Yes, and maybe do not expose it

This classification belongs in application policy, not in the agent prompt.

For example:

public enum ToolRisk
{
    ReadOnly,
    DraftOnly,
    ReversibleWrite,
    ExternalSideEffect,
    Destructive
}

public sealed record ToolPolicy(
    string ToolName,
    ToolRisk Risk,
    bool RequiresApproval);

The agent can still receive instructions such as "explain before requesting deployment".
The code decides which tools are wrapped with approval.

A tool that must not run silently

Imagine a deployment assistant.
It can check staging status automatically.
It must not deploy to production without review.

The read-only tool is normal:

using System.ComponentModel;
using Microsoft.Extensions.DependencyInjection;

[Description("Checks the current staging deployment status for a release.")]
public static Task<DeploymentStatus> CheckStagingStatusAsync(
    [Description("Release identifier, for example release-2026-06-24.")] string releaseId,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var deployments = services.GetRequiredService<IDeploymentService>();

    return deployments.CheckStagingStatusAsync(
        releaseId,
        cancellationToken);
}

The side-effecting tool is different:

[Description("Deploys an approved release to production.")]
public static async Task<DeploymentResult> DeployToProductionAsync(
    [Description("Release identifier that should be deployed.")] string releaseId,
    [Description("Approved change ticket for this production deployment.")] string changeTicket,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var user = services.GetRequiredService<CurrentUser>();
    var authorization = services.GetRequiredService<IDeploymentAuthorization>();
    var deployments = services.GetRequiredService<IDeploymentService>();

    if (!await authorization.CanDeployToProductionAsync(
            user,
            releaseId,
            changeTicket,
            cancellationToken))
    {
        throw new UnauthorizedAccessException(
            "The current user is not allowed to deploy this release.");
    }

    return await deployments.DeployToProductionAsync(
        releaseId,
        changeTicket,
        cancellationToken);
}

Notice the authorization check inside the tool.

Human approval is not a replacement for permissions.
The reviewer can approve the action, but the user on whose behalf the action runs still needs permission to do it.

Wrap the risky tool with approval

In Agent Framework, function tools can be wrapped with ApprovalRequiredAIFunction.
That tells the runtime that the agent may request the function call, but the function should not execute until approval has been provided.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIFunction checkStaging =
    AIFunctionFactory.Create(CheckStagingStatusAsync);

AIFunction deployToProduction =
    AIFunctionFactory.Create(DeployToProductionAsync);

AIFunction approvalRequiredDeploy =
    new ApprovalRequiredAIFunction(deployToProduction);

AIAgent deploymentAgent = chatClient.AsAIAgent(
    name: "deployment-agent",
    instructions: """
    You help operators prepare production deployments.

    Always check staging status before requesting a production deployment.
    Explain the release id, target environment, and change ticket before
    requesting deployment.

    If the user does not provide a change ticket, ask for it.
    """,
    tools:
    [
        checkStaging,
        approvalRequiredDeploy
    ],
    services: app.Services);

The prompt still matters.
It shapes the explanation and the plan.

The wrapper matters more for execution.
The deployment tool now sits behind a runtime gate.

Handle approval requests after each run

When the agent tries to call an approval-required tool, the run may return an approval request instead of a final answer.
In C#, check the response messages for FunctionApprovalRequestContent.

AgentSession session = await deploymentAgent.CreateSessionAsync();

AgentResponse response = await deploymentAgent.RunAsync(
    "Deploy release-2026-06-24 to production using CHG-1042.",
    session,
    cancellationToken: cancellationToken);

List<FunctionApprovalRequestContent> approvalRequests =
    response.Messages
        .SelectMany(message => message.Contents)
        .OfType<FunctionApprovalRequestContent>()
        .ToList();

if (approvalRequests.Count > 0)
{
    FunctionApprovalRequestContent request = approvalRequests[0];

    Console.WriteLine(
        $"Approval required for {request.FunctionCall.Name}");
    Console.WriteLine(
        $"Arguments: {request.FunctionCall.Arguments}");
}

This sample reads approvalRequests[0] only to keep the first example small.
Do not turn that into a production assumption.
Modern models can request multiple tool calls in one turn, including multiple calls that require approval.
A real application should iterate through all pending approval requests, show them as a batch, and return one decision per request.

For a console sample, printing the function name and arguments is enough.
For a real application, convert the request into a domain approval record.

public sealed record PendingApproval(
    string ApprovalId,
    string SessionId,
    string FunctionName,
    string ArgumentsJson,
    string RequestedBy,
    DateTimeOffset RequestedAt,
    DateTimeOffset ExpiresAt);

Do not show only the model's prose to the reviewer.
Show the actual function call.

The approval UI should display at least:

tool name
exact arguments
target resource or environment
requesting user
generated explanation or plan
relevant retrieved evidence or status checks
expiration time
approve and reject actions

If the reviewer cannot see what will execute, the approval screen is theater.

Send the decision back to the same session

After the user approves or rejects the call, create a response from the original approval request and pass it back to the agent in the same session.

bool approved = true;

ChatMessage approvalMessage = new(
    ChatRole.User,
    [approvalRequests[0].CreateResponse(approved)]);

AgentResponse finalResponse = await deploymentAgent.RunAsync(
    approvalMessage,
    session,
    cancellationToken: cancellationToken);

Console.WriteLine(finalResponse.Text);

If approved is true, the tool may execute.
If approved is false, the agent can explain that the action was rejected and either stop or ask for a revised plan.

If your application allows parallel tool calls, do the same thing here: respond to all pending approval requests, not only the first one.

You should check for approval requests after every run.
One approved function call can lead to another function call that also requires approval.
The loop ends only when the agent returns a normal final response or the application stops the process.

const int maxApprovalRounds = 5;

for (int approvalRound = 0; approvalRound < maxApprovalRounds; approvalRound++)
{
    AgentResponse response = await deploymentAgent.RunAsync(
        input,
        session,
        cancellationToken: cancellationToken);

    if (ResponseContainsToolExecutionFailure(response))
    {
        throw new InvalidOperationException(
            "Tool execution failed. Stop the approval loop and surface the failure.");
    }

    List<FunctionApprovalRequestContent> approvals =
        response.Messages
            .SelectMany(message => message.Contents)
            .OfType<FunctionApprovalRequestContent>()
            .ToList();

    if (approvals.Count == 0)
    {
        return response.Text;
    }

    ApprovalPrompt[] prompts = approvals
        .Select(approval => new ApprovalPrompt(
            approval,
            approval.FunctionCall.Name,
            approval.FunctionCall.Arguments))
        .ToArray();

    IReadOnlyList<ApprovalDecision> decisions =
        await approvalUi.RequestDecisionsAsync(
            prompts,
            cancellationToken);

    input = new ChatMessage(
        ChatRole.User,
        decisions
            .Select(decision =>
                decision.Request.CreateResponse(decision.Approved))
            .ToArray());
}

throw new InvalidOperationException(
    $"The agent exceeded {maxApprovalRounds} approval rounds.");

The failure check is intentionally application-specific.
The control flow is the important part.

Do not leave approval handling as an unbounded while (true) that asks the model again after every tool exception.
If a tool failed because staging is down, inventory changed, a downstream API rejected the request, or the approval expired, stop the loop and show the failure to the user.
Do not let the model immediately request the same side effect again.

This pattern works well when the human is present and approval is immediate.
For example:

a chat UI asks "Approve deployment?"
an operator clicks approve
the same server process continues the agent run

Once approval can happen later, you need more state.

Approval state belongs outside the model

The model does not own approval state.
Your application does.

At minimum, persist:

approval id
conversation or session id
workflow run id, if using workflows
checkpoint id, if the run can be resumed later
requested tool name
requested arguments
requester
approver
decision
timestamp
expiration
final execution result
correlation id or trace id

The approval record should have a normal state machine:

public enum ApprovalStatus
{
    Pending,
    Approved,
    Rejected,
    Expired,
    Executed,
    Failed
}

That avoids vague states such as "the UI showed approved, but the tool never ran" or "the tool ran twice after a retry".

Use the approval id as an idempotency key when the tool performs the side effect.
Retries happen.
Users double-click.
Servers restart.
Workflow runs resume.

The side-effecting system should be able to say:

I already executed approval approval-123 for release release-2026-06-24.
Do not execute it again.

That is not an agent problem.
That is normal distributed systems work.

Revalidate before execution

Approval is a point-in-time decision.
The world can change between request and execution.

For a deployment assistant, staging may fail after the approval screen is shown.
For an order assistant, inventory or price may change.
For an email assistant, someone may edit the recipient list.

Do not treat approval as a permanent permission slip.

Revalidate inside the tool:

if (approval.ExpiresAt < DateTimeOffset.UtcNow)
{
    throw new InvalidOperationException("The approval has expired.");
}

DeploymentStatus status = await deployments.CheckStagingStatusAsync(
    releaseId,
    cancellationToken);

if (!status.IsHealthy)
{
    throw new InvalidOperationException(
        "Staging is no longer healthy. Production deployment stopped.");
}

For high-risk actions, approval should usually expire quickly.
The user should approve the exact action that will run, under current conditions.

When a workflow is the better implementation

Approval-required tools are fine for short interactive flows.

Use workflows when approval is part of a process that needs to pause, emit events, checkpoint, and resume later.

Examples:

production deployment review
support refund approval
access request approval
legal or compliance review
content publishing with editorial sign-off
multi-step remediation plan

In a workflow, human input is not a chat detail.
It is part of the process.

The shape looks like this:

parse request
-> check current state
-> draft action plan
-> request human approval
-> execute approved action
-> verify result
-> persist audit record

That belongs in a workflow because the pause has state.

Tool approval inside a workflow

Agent Framework workflows emit events while they run.
When an agent inside a workflow calls an approval-required tool, the workflow can pause and emit a RequestInfoEvent.
For tool approval, that request contains ToolApprovalRequestContent.

A simplified sequential workflow might look like this:

using Microsoft.Agents.AI.Workflows;

ChatClientAgent deployAgent = new(
    chatClient,
    """
    You prepare production deployments.
    Check staging first, then request production deployment when appropriate.
    """,
    "DeployAgent",
    "Prepares and requests production deployments",
    [
        AIFunctionFactory.Create(CheckStagingStatusAsync),
        new ApprovalRequiredAIFunction(
            AIFunctionFactory.Create(DeployToProductionAsync))
    ]);

ChatClientAgent verifyAgent = new(
    chatClient,
    "You verify deployment results and summarize operational status.",
    "VerifyAgent",
    "Verifies deployments");

Workflow workflow =
    AgentWorkflowBuilder.BuildSequential([deployAgent, verifyAgent]);

Then consume the workflow event stream:

List<ChatMessage> messages =
[
    new(ChatRole.User, "Deploy release-2026-06-24 to production using CHG-1042.")
];

await using StreamingRun run =
    await InProcessExecution.RunStreamingAsync(workflow, messages);

await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (WorkflowEvent evt in run.WatchStreamAsync())
{
    if (evt is RequestInfoEvent requestEvent &&
        requestEvent.Request.TryGetDataAs(
            out ToolApprovalRequestContent? approvalRequest))
    {
        bool approved = await approvalUi.RequestDecisionAsync(
            approvalRequest.FunctionCall.Name,
            approvalRequest.FunctionCall.Arguments,
            cancellationToken);

        await run.SendResponseAsync(
            requestEvent.Request.CreateResponse(
                approvalRequest.CreateResponse(approved)));
    }

    if (evt is WorkflowOutputEvent output)
    {
        Console.WriteLine(output.Data);
        break;
    }
}

That is the workflow version of the same boundary:

the agent requests the tool call
the workflow emits a request event
the application asks the human
the application sends the response back
the workflow continues

This is more code than the direct agent version.
Use it when the extra structure gives you something concrete.

Checkpoints matter for delayed approval

If approval happens five seconds later, an in-memory session may be enough.
If approval happens tomorrow, it is not.

Workflows support checkpoints.
A checkpoint captures workflow state at a point in execution, including pending messages, shared state, and pending requests.

That matters for human review because the process can stop at:

waiting for approval

and later continue from the same state.

The implementation shape is usually:

workflow emits approval request
-> application stores approval record
-> application stores checkpoint reference
-> process returns to caller
-> human approves later
-> application resumes workflow from checkpoint
-> workflow re-emits pending request
-> application sends approval response
-> workflow continues

Do not rebuild the process from the model's last answer.
Resume from workflow state.

Also treat checkpoint storage as private application infrastructure.
Checkpoint data may contain prompts, messages, pending tool calls, arguments, and intermediate outputs.
Do not store it somewhere that broader users or unrelated services can read.

Do not make approval the only guardrail

Human review is one boundary.
It is not the whole safety model.

For side-effecting tools, I would still keep these checks:

authentication before the agent runs
authorization inside the tool
argument validation before execution
business rule validation before execution
approval for risky actions
idempotency for retries
audit logging after execution
monitoring for unusual tool call patterns

The approval UI is not the place to hide missing application logic.

If a user is not allowed to deploy to production, the tool must reject the call even if someone clicks approve.
If the arguments are invalid, the tool must reject the call.
If the action already ran, the tool must not run it again.

The agent runtime is part of your application.
It should not bypass your application.

Human edits are not the same as approval

Sometimes the reviewer should not only approve or reject.
They should edit.

For example:

edit an outbound support email
change the deployment window
remove a recipient
adjust a public status message

Do not silently mutate the original tool call arguments and pretend the same approval still applies.

Treat edits as new input.
If the reviewer significantly changes the payload, reject or cancel the original approval request.
Then add the edited action back into the process as user-provided state, a user message, or a system/application note.
Do not create an "approved" response for the original tool call while secretly executing different arguments.

That distinction matters for the model's history.
The model remembers the tool call it requested.
If the application returns a successful tool result for a materially different call, the conversation history now lies about what happened.
That can confuse follow-up reasoning, especially when later steps depend on the original arguments.

For a draft email, a good flow is:

agent drafts email
-> agent requests send email with that body
-> human edits body
-> application stores edited body
-> application rejects the original send request
-> edited body is added as user-provided content or process state
-> agent or application creates a new send action for that exact body
-> human approves the exact action that will execute

For a deployment, a changed release id, environment, or change ticket should create a new approval request.
The human must approve the exact operation that will execute.

Make approval observable

Approval flows need logs that explain what happened.

Useful fields include:

approvalId
conversationId
workflowRunId
checkpointId
toolName
toolArgumentsHash
requestedBy
approvedBy
decision
decisionReason
createdAt
decidedAt
executedAt
executionResult
traceId

Avoid logging raw secrets or confidential payloads.
But log enough to answer operational questions:

What did the agent try to do?
Who approved it?
What exactly executed?
Did the tool run once or more than once?
Was the approval still valid at execution time?
Which workflow checkpoint resumed the process?

If you cannot answer those questions, the approval flow is not production-ready yet.

When I would use direct tool approval

Use direct approval-required tools when:

the user is present in the current interaction
approval happens immediately
the process can stay inside one agent session
the action is a single tool call
the surrounding application already owns the UI state
you do not need workflow-level checkpointing

Examples:

"Send this email?" in a chat UI
"Create this support ticket?" after the user reviews it
"Run this one deployment command?" while an operator is watching
"Place this order?" inside an authenticated session

Start here if the process is small.
The implementation is easier to read and easier to test.

When I would use workflows

Use workflows when:

approval may happen later
the process has multiple steps before or after approval
the pause must be checkpointed
the approval path needs auditability
multiple humans or systems may respond
the process should emit progress events
the workflow may resume after a restart
the process itself is product behavior

Examples:

deployment approval with verification after release
access request with manager and security review
refund approval with payment execution and audit
document publishing with editorial review
incident remediation with operator approval before changes

In those cases, the workflow is not ceremony.
It is the state model for the process.

When I would not use human approval

Do not add human approval just because an agent is involved.

Avoid it when:

the tool is read-only
the action is cheap and fully reversible
the user already explicitly clicked a normal product button
deterministic validation is enough
approval would only hide weak authorization logic
the reviewer cannot understand the action being approved

Bad approval flows create fatigue.
If users approve twenty harmless requests, they will approve the dangerous one too.

Use approval for meaningful risk.
Use validation, permissions, and deterministic code for everything else.

Conclusion

Human-in-the-loop agents are not about making the prompt more polite.
They are about putting a real boundary between model intent and application side effects.

For simple interactive cases, wrap risky tools with ApprovalRequiredAIFunction, inspect FunctionApprovalRequestContent, show the exact tool call to the user, and pass the approval response back into the same session.

For long-running or delayed review, use workflows.
Handle RequestInfoEvent, persist approval state, checkpoint the workflow, and resume from state instead of rebuilding the process from text.

The design I would carry forward is:

let the model request actions
let application policy decide which actions require approval
show humans the actual tool call, not only the model's summary
keep authorization and validation inside the tool
persist approval and workflow state outside the model
make side effects idempotent and auditable

That keeps the agent useful without giving it silent control over irreversible work.

The next post will move to the frontend boundary: AG-UI, streaming, tool progress, approval requests, state updates, and exposing agent behavior as more than a plain chat box.
After that, observability is the natural follow-up, because these flows need traces across model calls, tools, approvals, workflow events, and frontend state.

Deploy a .NET MCP server to Azure Functions

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

In the previous post, we built a small MCP server in .NET, exposed it over Streamable HTTP, containerized it, deployed it to Azure Container Apps, and called it from a C# client.

This follow-up keeps the same server and changes the host. The tools stay the same. The client stays almost the same. Instead of running the server as a container app, we run the existing ASP.NET Core MCP server on Azure Functions as a self-hosted custom handler.

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

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 point of this post is not to rewrite those tools as Azure Functions. The point is to keep the MCP server as an SDK-based ASP.NET Core app and let Azure Functions host it.

Prerequisites

You need:

.NET 10 SDK
Azure Functions Core Tools v4
Azure CLI 2.60.0 or later
An Azure subscription
Optional: Node.js if you want to test with the MCP Inspector

The Azure Functions self-hosted MCP server support is in public preview at the time of writing. The important constraints are:

The MCP server must be stateless.
The MCP server must use Streamable HTTP.
The Function App must use Flex Consumption.
Local execution must use func start.

That fits the sample from the Container Apps post because it already uses stateless Streamable HTTP:

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");

If your server depends on process-local sessions, in-memory subscriptions, or long-lived state, stop here and redesign that part first. Azure Functions can scale out and recycle instances. State that matters should live outside the process.

Start from the existing repository

Clone the repository from the previous post:

git clone https://github.com/ovnecron/mcp-azure-container-apps-demo.git
cd mcp-azure-container-apps-demo

I would do the Functions version on a separate branch:

git checkout -b azure-functions

The starting point looks like this:

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

The Container Apps version also has a Dockerfile. You can leave it in the repository if you want one branch to support both hosts, but Azure Functions will not use it in this walkthrough.

Why custom handlers

Azure Functions has two MCP paths:

Build tools with the Azure Functions MCP extension.
Host an existing SDK-based MCP server as a self-hosted custom handler.

The first path is useful when you want the Functions programming model from the start. You write Function methods and expose tools with the Functions MCP extension.

That is not what we need here.

The existing sample is already an ASP.NET Core MCP server using the official .NET MCP SDK. Rewriting the tools as Function methods would create a second implementation for no good reason.

With the self-hosted approach, the request path is:

MCP client
  -> Azure Functions host
  -> custom handler process
  -> ASP.NET Core MCP server
  -> /mcp

The Functions host starts the web server process and proxies HTTP requests to it. From the MCP client's point of view, the endpoint is still a remote Streamable HTTP MCP server.

Change `Program.cs`

Open src/McpAzureContainerAppsDemo.Server/Program.cs.

Add an explicit URL binding immediately after the builder is created:

var builder = WebApplication.CreateBuilder(args);

var customHandlerPort = Environment.GetEnvironmentVariable("FUNCTIONS_CUSTOMHANDLER_PORT") ?? "8080";
builder.WebHost.UseUrls($"http://0.0.0.0:{customHandlerPort}");

The port matters. The Functions host needs to know where the custom handler process is listening.

FUNCTIONS_CUSTOMHANDLER_PORT is the idiomatic way for an Azure Functions custom handler process to discover the port it should bind to. The fallback to 8080 keeps direct local runs predictable when that environment variable is not set.

This does not change the MCP tool registration:

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

And the endpoint stays the same:

app.MapMcp("/mcp");

That is the useful part of this migration. We are changing hosting, not tool implementation.

Add `host.json`

Create src/McpAzureContainerAppsDemo.Server/host.json:

{
  "version": "2.0",
  "configurationProfile": "mcp-custom-handler",
  "customHandler": {
    "description": {
      "defaultExecutablePath": "dotnet",
      "arguments": ["McpAzureContainerAppsDemo.Server.dll"]
    },
    "http": {
      "defaultAuthorizationLevel": "anonymous"
    },
    "port": "8080"
  }
}

This is the bridge between Azure Functions and the existing ASP.NET Core server.

The custom handler command is:

dotnet McpAzureContainerAppsDemo.Server.dll

The port value must match the URL binding in Program.cs.

In this sample, host.json declares 8080. The ASP.NET Core app reads FUNCTIONS_CUSTOMHANDLER_PORT when the Functions host provides it and falls back to the same 8080 value for local or direct runs.

The configurationProfile value of mcp-custom-handler is important. It configures the Functions host for the MCP custom-handler shape, including HTTP proxying and a catch-all route so requests such as /mcp pass through to the ASP.NET Core server.

The defaultAuthorizationLevel is anonymous here because this sample keeps the API-key middleware from the Container Apps post. That middleware protects /mcp when McpServer__ApiKey is configured and leaves /health open for smoke tests.

For a real system, I would not stop at a static API key. Use built-in authentication with Microsoft Entra ID, managed identity for downstream Azure services, and authorization rules that match what your tools can access.

Add local Functions settings

Create src/McpAzureContainerAppsDemo.Server/local.settings.json for local development:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "AzureWebJobsFeatureFlags": "EnableMcpCustomHandlerPreview",
    "McpServer__ApiKey": "local-dev-key"
  }
}

Do not commit real secrets in local.settings.json. For a public repository, commit a local.settings.json.example if you want to document the required keys, and keep the real file local.

The McpServer__ApiKey key is the same setting used in the Container Apps version. ASP.NET Core configuration maps it to McpServer:ApiKey, and the existing middleware checks the incoming X-Api-Key header.

Copy `host.json` on publish

Update src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj so host.json is copied into the build and publish output:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="ModelContextProtocol.AspNetCore" />
  </ItemGroup>

  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>

</Project>

host.json must be at the root of the Function App package. Azure Functions reads it to know how to start and proxy to the custom handler.

local.settings.json is only for local development and should not be published.

Run locally with Azure Functions Core Tools

Start the server through the Functions host:

cd src/McpAzureContainerAppsDemo.Server
func start

The Functions host listens on 7071 by default.

The ASP.NET Core custom handler listens on the custom handler port internally. With the sample settings, that is 8080. Clients connect to the Functions host:

http://localhost:7071/mcp

In another terminal, run the existing C# client from the repository root:

dotnet run --project src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj -- \
  --url http://localhost:7071/mcp \
  --api-key local-dev-key \
  --time-zone Europe/Berlin

You should see the same behavior as the Container Apps version:

the client lists the available tools
add returns a sum
server_time returns the server time for the requested time zone

You can also smoke test the normal HTTP endpoint:

curl http://localhost:7071/health

If this does not respond, check the Functions terminal first. Most local failures are a wrong DLL name in host.json, a port mismatch, or missing Azure Functions Core Tools support.

Test with MCP Inspector

You can inspect the tool schema with MCP Inspector:

npx @modelcontextprotocol/inspector

Use Streamable HTTP and connect to:

http://localhost:7071/mcp

Add the API key header:

X-Api-Key: local-dev-key

This verifies the MCP surface without relying on the C# client.

Publish the Function App package

Build a publish output from the repository root:

dotnet publish src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj \
  --configuration Release \
  --output .publish/mcp-functions

Check that the publish output contains both the DLL and host.json:

ls .publish/mcp-functions/McpAzureContainerAppsDemo.Server.dll
ls .publish/mcp-functions/host.json

Create a zip package from the contents of the publish directory.

On macOS or Linux:

cd .publish/mcp-functions
zip -r ../mcp-functions.zip .
cd ../..

On Windows PowerShell:

Compress-Archive `
  -Path .\.publish\mcp-functions\* `
  -DestinationPath .\.publish\mcp-functions.zip `
  -Force

The package must contain host.json at the zip root. Do not zip the parent folder itself. This is one of the most common causes of custom handler deployments that build successfully but fail at startup.

Create Azure resources

az login

az functionapp list-flexconsumption-locations \
  --query "sort_by(@, &name)[].{Region:name}" \
  --output table

Set variables:

export RESOURCE_GROUP=mcp-functions-demo-rg
export LOCATION=westeurope
export UNIQUE_SUFFIX=$RANDOM$RANDOM
export STORAGE_ACCOUNT=mcpfunc$UNIQUE_SUFFIX
export FUNCTION_APP_NAME=mcp-func-demo-$UNIQUE_SUFFIX
export MCP_API_KEY="$(openssl rand -base64 32)"

az provider register --namespace Microsoft.App

Create the resource group:

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

Create the storage account:

az storage account create \
  --name "$STORAGE_ACCOUNT" \
  --resource-group "$RESOURCE_GROUP" \
  --location "$LOCATION" \
  --sku Standard_LRS \
  --allow-blob-public-access false

Create the Function App on Flex Consumption:

az functionapp create \
  --resource-group "$RESOURCE_GROUP" \
  --name "$FUNCTION_APP_NAME" \
  --storage-account "$STORAGE_ACCOUNT" \
  --flexconsumption-location "$LOCATION" \
  --runtime dotnet-isolated \
  --runtime-version 10.0

The existing sample targets net10.0, so the Function App runtime version should match. If your Azure CLI does not accept 10.0, update the Azure CLI and check whether .NET 10 is available in the selected region.

Add the MCP preview feature flag and the sample API key:

Remember that local.settings.json does not deploy to Azure, so you must recreate those environment variables as Function App settings in the cloud.

az functionapp config appsettings set \
  --name "$FUNCTION_APP_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --settings \
    AzureWebJobsFeatureFlags=EnableMcpCustomHandlerPreview \
    McpServer__ApiKey="$MCP_API_KEY"

FUNCTIONS_WORKER_RUNTIME is set by the az functionapp create command because the app was created with --runtime dotnet-isolated.

Deploy the package

Deploy the zip package:

az functionapp deployment source config-zip \
  --resource-group "$RESOURCE_GROUP" \
  --name "$FUNCTION_APP_NAME" \
  --src .publish/mcp-functions.zip

After deployment, the MCP endpoint is:

https://<function-app-name>.azurewebsites.net/mcp

For this walkthrough, that becomes:

echo "https://$FUNCTION_APP_NAME.azurewebsites.net/mcp"

Smoke test the health endpoint:

curl "https://$FUNCTION_APP_NAME.azurewebsites.net/health"

Then call the deployed MCP server with the existing C# client:

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

If everything is wired correctly, the output should look like the local run. The hosting platform changed, but the MCP surface did not.

What changed compared to Container Apps

The Container Apps version needed a Dockerfile, container build, ingress target port, and Container Apps deployment command.

The Functions version needs:

host.json
local.settings.json for local development
an explicit ASP.NET Core port binding
project file entries to publish host.json
a Flex Consumption Function App
a zip deployment package

The MCP tools did not change.

The services did not change.

The C# client only changed the URL:

Container Apps:
https://<container-app-fqdn>/mcp

Azure Functions:
https://<function-app-name>.azurewebsites.net/mcp

That is the design goal. If your MCP server keeps protocol wiring thin and tool behavior in normal services, the hosting layer can change without rewriting the application.

Azure Container Apps vs Azure Functions

Neither host is automatically better.

Use Azure Container Apps when:

you want the MCP server to behave like a normal containerized web app
you want direct control over the image and container environment
you already use ACA environments, revisions, and ingress
the app is likely to grow beyond a small request-driven MCP surface

Use Azure Functions when:

the MCP server is stateless and uses Streamable HTTP
you want a serverless hosting model
your team already uses Function Apps and Functions deployment workflows
you want to use Functions platform features around authentication, managed identity, and operations

For this sample, both work. The useful lesson is that the same MCP server can move between hosts with a small hosting-layer change.

Troubleshooting checklist

If func start works but /mcp does not respond, check:

Does host.json point to McpAzureContainerAppsDemo.Server.dll?
Does host.json use port 8080?
Does Program.cs read FUNCTIONS_CUSTOMHANDLER_PORT and fall back to 8080?
Are you calling the Functions host URL, http://localhost:7071/mcp, not http://localhost:8080/mcp?
Is AzureWebJobsFeatureFlags=EnableMcpCustomHandlerPreview set locally?
If API-key protection is enabled, did you send X-Api-Key or pass --api-key to the client?
Is the MCP Inspector using Streamable HTTP?

If Azure deployment succeeds but the remote endpoint fails, check:

Does the zip contain host.json at the root?
Does the zip contain McpAzureContainerAppsDemo.Server.dll?
Is the Function App running on Flex Consumption?
Is the Function App runtime set to dotnet-isolated with a runtime version that can run the target framework?
Are AzureWebJobsFeatureFlags and McpServer__ApiKey set as app settings?
Do the Function App logs show a custom handler startup failure?

Most failures in this shape are not MCP tool bugs. They are usually host configuration, port mismatch, publish package shape, or missing auth headers.

Cleanup

Delete the resource group when you are done:

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

When to use this

Use this approach when you already have a stateless SDK-based MCP server in .NET and you want to host it remotely on Azure Functions without rewriting your tools into Function trigger methods.

It is a good fit for focused, request-driven tool servers where the MCP layer stays thin and the tool behavior lives in normal C# services.

When not to use this

Do not use this sample as-is when tools can read production data, mutate resources, or require user-level authorization. Replace the static API key with a stronger authentication and authorization model, use managed identity for downstream Azure access, add observability around tool calls, and test the deployed /mcp endpoint.

Microsoft Agent Framework Multimodal Agents: Images, PDFs, and Provider Differences

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

This is Part 14 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 RAG for agents.
The main point was that retrieval is not magic. It is an application capability that gives the agent selected context at the point where it needs it.

Multimodal inputs hit the same kind of boundary.

Agent Framework can pass non-text content such as images through the agent call.
That does not mean every provider, every model, and every file type behaves the same way.
The framework gives you a common message model.
The provider still decides what it can understand, how it accepts the content, how much it costs, and where the edge cases are.

My rule is simple: send the file to the model when seeing the file is the point.
Preprocess it yourself when the product depends on repeatability, scale, indexing, access control, or exact extraction.

Multimodal is message content

In Agent Framework, the basic idea is not complicated.
The user message can contain multiple content parts.
One part can be text.
Another part can be an image URI.
Another part can be binary data with a media type.

That shape comes from the Microsoft.Extensions.AI content model.
An agent does not only receive a string.
It can receive a ChatMessage with a list of AIContent items.

A minimal image example looks like this:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIAgent agent = chatClient.AsAIAgent(
    name: "VisionAgent",
    instructions: """
    You inspect images for engineering-relevant details.
    Be specific about what is visible.
    Say when something cannot be determined from the image.
    """);

ChatMessage message = new(ChatRole.User, [
    new TextContent("What operational issue is visible in this screenshot?"),
    new UriContent(
        "https://example.com/support-ticket-screenshot.png",
        "image/png")
]);

AgentResponse response = await agent.RunAsync(
    message,
    cancellationToken: cancellationToken);

For a local image, use DataContent instead of a public URL:

byte[] imageBytes = await File.ReadAllBytesAsync(
    "screenshots/deployment-error.png",
    cancellationToken);

ChatMessage message = new(ChatRole.User, [
    new TextContent("""
    Read the screenshot and extract:
    - the visible error message
    - the affected service name, if visible
    - the next diagnostic step

    Do not guess hidden text.
    """),
    new DataContent(imageBytes, "image/png")
]);

This is the clean part.
The application builds a message.
The agent runs.
The model analyzes the image.

The messy part starts when you ask whether the same code works across all providers, all models, all image sizes, all PDFs, and all deployment environments.
It does not.

Framework support is not model support

Agent Framework can represent multimodal content.
That is different from guaranteeing that the selected model can process it.

There are three separate questions:

Can the framework represent the content?
Can the provider adapter send that content to the provider?
Can the deployed model understand that content in the way your task requires?

The first answer may be yes while the second or third answer is no.

For example, UriContent can represent hosted content.
DataContent can represent binary content with a media type.
But a text-only model will still not understand an image.
A local provider may require base64 image arrays.
A hosted provider may support image URLs but not private intranet URLs.
A model may read a chart well enough for a summary but poorly enough for exact values.

Treat multimodal support as a capability of the whole route:

Agent Framework message
-> provider adapter
-> provider API
-> deployed model
-> safety filters and limits
-> response shape

If any part of that route does not support the modality, the abstraction cannot fix it.

What works natively

Images are the most straightforward native multimodal input.
For vision-capable models, the normal pattern is:

text instruction + image input -> text response

That is useful for:

screenshot triage
UI review
handwritten note transcription
simple chart explanation
document page inspection
comparing a small number of images
extracting visible fields from a known image type

In an agent application, this usually becomes a focused capability:

User uploads screenshot
-> application validates and stores it
-> agent receives the screenshot plus a specific question
-> agent explains what is visible
-> application logs the input, output, model, and prompt version

Keep the prompt specific.
Do not ask the model to "analyze this image" unless a broad description is actually the product.
Ask for the fields, risks, differences, or decisions you need.

For example:

Inspect this Azure deployment screenshot.

Return:
1. The visible resource name
2. The visible error or warning
3. Whether the screenshot contains enough information to identify the failing step
4. The next diagnostic command or portal area to check

If a value is not visible, write "not visible".

That instruction gives the model a narrow job.
It also gives the rest of your application something predictable to consume.

PDFs are different

PDFs are more than large images.
They are containers.

A PDF may contain:

embedded text
scanned page images
tables
charts
vector graphics
form fields
annotations
multiple columns
rotated pages
hidden or duplicated text layers

That means "read this PDF" can mean several different things.

For a born-digital PDF, text extraction may be enough.
For a scanned PDF, you need OCR or vision.
For a report with charts and diagrams, the visual layout may matter.
For an invoice, you may need exact field extraction and validation.
For a 300-page manual, you probably need ingestion, chunking, retrieval, and citations.

Some provider APIs can accept PDFs directly.
For example, OpenAI's file input flow can put both extracted text and page images into model context for compatible vision models.
Claude has PDF support where pages can be processed visually, with platform-specific behavior.
Gemini documents PDF processing explicitly and treats PDF pages as visual inputs with its own size, page, and token rules.

That support is useful.
It does not remove the need to design the document path.

Native PDF input is a good fit when:

the document is small enough for one request
the question is about the whole document or a few known pages
visual layout matters
you do not need to index the document for repeated search
you can tolerate provider-specific behavior

Manual preprocessing is usually better when:

you process many documents
documents must be searchable later
access control matters per document or per section
extraction must be repeatable
you need stable citations or page references
you need validation against business rules
you need to normalize tables, forms, or fields
cost and latency must be predictable

For production systems, I would rarely make "send the whole PDF to the agent" the default.
I would first decide what kind of document problem I actually have.

Provider differences matter

Provider differences show up in product behavior, not only in request syntax.

Provider docs change quickly. For this post, I checked the June 2026 docs and would still verify these points before shipping:

Area	What varies	Why it matters
Supported modalities	Text, image, PDF, audio, video, or only some of them	The same agent design may not work with another model
Input transport	URL, base64/data URI, uploaded file ID, provider file API, local model-specific fields	Your storage and upload flow depend on this
PDF handling	Text extraction only, visual page processing, or both	Charts, scans, and layout may be ignored in some modes
Limits	File size, image count, page count, request payload, resolution, context window	Large files may fail or become expensive
Resizing	Providers may resize images before model processing	Small text, coordinates, and fine UI details can become unreliable
Cost model	Images and PDF pages often count differently from text	A cheap text flow can become expensive with pages rendered as images
Structured output	JSON/schema/tool support may differ with multimodal inputs	Extraction pipelines need tests per provider
Data handling	Retention, region, third-party terms, and hosted URL access vary	Enterprise boundaries and compliance reviews depend on this

The mistake is hiding these differences too early.

A provider-neutral interface is useful for your application.
But if the interface pretends that every provider handles images and PDFs the same way, it will leak in production.

A better abstraction exposes the parts that matter:

public sealed record MultimodalModelCapabilities(
    bool SupportsImageInput,
    bool SupportsPdfInput,
    bool SupportsImageUrls,
    bool SupportsBinaryContent,
    int? MaxImagesPerRequest,
    long? MaxRequestBytes);

This does not need to be perfect.
It just needs to stop the rest of the application from assuming capabilities that are not there.

Keep the agent away from raw uploads

Do not let the agent decide what to do with arbitrary uploaded files directly.

The application should own the upload boundary:

upload
-> authenticate user
-> authorize document access
-> validate content type
-> scan or reject unsafe files
-> store original file
-> create derived artifacts
-> pass selected artifacts to the agent

Derived artifacts might include:

extracted text
OCR text
rendered page images
thumbnails
page count
document metadata
table extraction output
classification result
chunk IDs for retrieval

Then the agent receives only what it needs.

For example:

public sealed record PreparedAttachment(
    string AttachmentId,
    string MediaType,
    string? ExtractedText,
    IReadOnlyList<PreparedPageImage> PageImages);

public sealed record PreparedPageImage(
    int PageNumber,
    byte[] ImageBytes,
    string MediaType);

Now the application can decide:

send only page 3 because retrieval found it
send extracted text without images
send a rendered image because the page is scanned
reject the file because it is too large
require a specialist parser because it is an invoice

That boundary is boring, but it is the one you want.
The alternative is handing the model every uploaded file and hoping it does the right thing.

Native vision is not OCR infrastructure

Vision models can read text in images.
That does not make them a full OCR platform.

OCR and document processing systems usually give you things that a general multimodal model may not:

stable coordinates
confidence scores
table structures
key-value pairs
page-level metadata
repeatable extraction
deterministic post-processing
specialized document models
batch processing controls

If your product needs those properties, use a document processing pipeline first.
Then give the agent the normalized output.

For example:

invoice PDF
-> document parser extracts fields
-> application validates totals and tax IDs
-> agent explains exceptions to the user

The agent is useful at the explanation layer.
It is not the system of record for the invoice total.

The same applies to tables.
If you need exact row counts, amounts, IDs, or totals, parse the table with deterministic code where possible.
Use the agent to explain the result, handle ambiguous cases, or route exceptions.

Use tools for document operations

If multimodal work becomes more than a single model call, expose it as a tool.

For example:

public interface IDocumentInspection
{
    Task<DocumentInspectionResult> InspectAsync(
        string attachmentId,
        string question,
        UserDocumentScope scope,
        CancellationToken cancellationToken);
}

The agent does not need direct access to blob storage, PDF rendering, OCR, or every uploaded file.
It needs a controlled operation:

using System.ComponentModel;
using Microsoft.Extensions.DependencyInjection;

[Description("Inspects an uploaded document or image that the current user is allowed to access.")]
public static Task<DocumentInspectionResult> InspectDocumentAsync(
    [Description("The attachment ID shown in the current conversation.")]
    string attachmentId,
    [Description("The specific question to answer about the attachment.")]
    string question,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var userScope = services.GetRequiredService<UserDocumentScope>();
    var inspection = services.GetRequiredService<IDocumentInspection>();

    return inspection.InspectAsync(
        attachmentId,
        question,
        userScope,
        cancellationToken);
}

This keeps the same design rule from the earlier tool and RAG posts: expose controlled capabilities, not raw infrastructure.

The tool can choose the right path internally:

call a native multimodal model
extract text and call a text model
render selected pages and send images
call a document intelligence service
reject unsupported files
ask the user for a narrower page range

The agent asks for document inspection.
The application decides how document inspection works.

Logging matters more with files

Text prompts are already worth logging.
File inputs make logging more important.

For multimodal agent calls, log at least:

model and provider
prompt version
attachment ID
media type
file size
page count, if applicable
selected pages or images sent
preprocessing path used
provider request ID, if available
token usage or image/page usage
safety or content-filter result

Do not log raw confidential file contents by default.
Log identifiers, derived metadata, and enough trace data to reproduce the path with proper access.

Without this, debugging becomes guesswork:

The agent got the PDF wrong.

is not actionable.

You need to know whether:

the wrong page was selected
OCR failed
the model never received the chart
the provider used text extraction only
the image was resized too aggressively
the prompt asked for an exact value the image could not support
the model guessed instead of saying "not visible"

Multimodal bugs often come from the pipeline around the model.

When I would use native multimodal input

I would use native image or PDF input when:

the user asks about one image or a small set of images
the document is short
visual layout is part of the question
the task is exploratory or assistive
exact extraction is not the only success criterion
provider lock-in is acceptable for that feature
latency and cost are acceptable after testing with real files

Examples:

Explain what is wrong in this deployment screenshot.
Compare these two UI screenshots.
Summarize the visible changes in this architecture diagram.
Identify which page in this short PDF contains the approval signature.
Extract draft fields from a single scanned form for human review.

Native multimodal input is strongest when seeing the artifact is the point.

When I would preprocess manually

I would preprocess manually when:

documents are long
documents are processed repeatedly
results need citations
extraction needs validation
fields need to become database records
users have different access to different files
the same corpus is queried many times
cost needs to be predictable
provider portability matters

Examples:

Search across a policy library.
Extract invoice fields into an ERP workflow.
Answer questions over thousands of manuals.
Review contracts with section-level citations.
Compare document versions.
Validate forms against business rules.

In those cases, use a pipeline:

document
-> extract text and metadata
-> OCR or render pages only when needed
-> chunk and index
-> retrieve relevant sections
-> send selected text/images to the agent
-> validate and store structured results

The agent still matters.
It just should not own the entire document pipeline.

Conclusion

Multimodal agents are useful, but the abstraction boundary is easy to overestimate.

Agent Framework can pass images and other content through the agent message model.
The provider and model decide what actually works.
PDFs add another layer because they may be text documents, image documents, layout documents, or all three at once.

The design I would carry forward is:

use native multimodal input for small, visual, interactive tasks
preprocess files when you need repeatability, scale, search, validation, or access control
model provider capabilities explicitly
keep raw uploads behind application-owned boundaries
use tools for document operations instead of exposing storage directly
log what happened to the file, not only the final answer

That keeps the agent useful without turning it into a fragile file-processing backend.

In the next post, I will move from files to actions.
Human-in-the-loop agents are about the moment where the agent should stop and ask before it does something risky or hard to undo.
That includes approval flows, side effects, workflow state, and the part that is easy to miss: human review is a system boundary, not a nicer prompt.

Agent Framework RAG for Agents: Giving Your Agent the Right Context

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

This is Part 13 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 workflows.
Workflows make sense when the process itself needs structure: state, checkpoints, events, human approvals, and resumable execution.

This post is the bridge from Agent Framework into RAG.
I plan on doing a full RAG deep dive sometime later. The practical question for now is smaller:

How do I connect an Agent Framework agent to private application knowledge without stuffing every document into the prompt?

For agents, RAG is less about adding more text and more about giving the agent a controlled retrieval path.
The agent should fetch the right context at the point where it needs it.

Agents do not know your private data

Your company documents, product catalog, tickets, rules, policies, runbooks, and internal knowledge base live outside the model.
The model has generic knowledge. Your application has private knowledge.
Treat those as separate systems.

You can paste some private data into the prompt, and for a demo that may be enough.
But this falls apart quickly:

full documents are expensive to send repeatedly
long prompts are fragile
stale documents may sit next to current ones
users may not be allowed to see every source
long context still needs selection

The last point is easy to underestimate.
A larger context window lets you send more text.
It does not decide which text is correct, current, relevant, or permitted.

Do not give the agent all knowledge.
Give it the right context at the moment it needs it.

Retrieval owns that job.

The minimal RAG shape

The basic RAG loop is small:

user question
-> retrieve relevant chunks
-> pass chunks to the agent
-> agent answers using that context

For documents, the longer pipeline usually looks like this:

documents
-> chunks
-> embeddings
-> vector store
-> search
-> retrieved context
-> agent response

Documents are split into smaller chunks.
Those chunks are embedded into vectors.
The vectors and source metadata are stored.
When a user asks a question, the question is embedded too.
The search layer finds nearby chunks and returns only those chunks to the agent.

Stop there for now.

There are some hard parts here:
chunk boundaries, embedding model choice, hybrid search, reranking, freshness, access control, observability, and evals.
They are just not the point yet.

For now, keep the boundary clear:

RAG is the retrieval layer around the agent.
The agent is not the retrieval layer.

Agent Framework is not the RAG engine

Microsoft Agent Framework gives you the agent runtime.
It does not give you a finished ingestion pipeline, chunking strategy, embedding setup, vector store, ranking model, permission model, freshness process, or retrieval eval suite.

Agent Framework helps you decide how the agent receives and uses context:

you can retrieve context before calling the agent
you can inject retrieved context through an AI context provider
you can expose retrieval as a function tool
you can make retrieval one step in a workflow

The retrieval system still belongs to your application architecture.

It might use Azure AI Search, PostgreSQL with pgvector, SQL Server vector search, Cosmos DB, Qdrant, Redis, a normal search index, or an internal HTTP API.
The agent does not need to care.

The agent needs a focused capability.
Not direct database access.

Retrieval as an agent tool

For many agent apps, I would start by exposing retrieval as a tool.

The tool is narrow:

SearchKnowledgeAsync(
    string query,
    string? category,
    int limit)

The agent can call it when the answer depends on private knowledge.
Your application decides what the tool is allowed to search.

This matches the tool-design rule from earlier in the series:

Tools should expose controlled capabilities, not raw infrastructure.

A small version looks like this:

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

public sealed record KnowledgeSearchResult(
    string Title,
    string Source,
    string Snippet,
    double Score);

public interface IKnowledgeSearch
{
    Task<IReadOnlyList<KnowledgeSearchResult>> SearchAsync(
        string query,
        string? category,
        int limit,
        CancellationToken cancellationToken);
}

[Description("Searches approved internal knowledge articles, policies, and runbooks.")]
public static Task<IReadOnlyList<KnowledgeSearchResult>> SearchKnowledgeAsync(
    [Description("Focused search query. Rewrite the user's message into search terms.")]
    string query,
    [Description("Optional source category such as policy, runbook, product, support, or architecture.")]
    string? category,
    [Description("Maximum number of results to return. Use 3 to 5 for normal questions.")]
    int limit,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var search = services.GetRequiredService<IKnowledgeSearch>();

    return search.SearchAsync(
        query,
        category,
        Math.Clamp(limit, 1, 5),
        cancellationToken);
}

The model supplies query, category, and limit.
The application supplies IKnowledgeSearch.

Keep that split.

The model can ask for a search.
It does not get a connection string, a database client, or permission to browse every source.

Then attach the tool to the agent:

AIAgent supportAgent = chatClient.AsAIAgent(
    instructions: """
    You answer questions about the internal engineering platform.

    Use SearchKnowledgeAsync when the answer depends on private company
    documentation, runbooks, policies, known issues, or product rules.

    If the search results do not contain enough evidence, say that the indexed
    sources do not answer the question. Do not invent policy details, limits,
    prices, permissions, or operational steps.
    """,
    tools: [AIFunctionFactory.Create(SearchKnowledgeAsync)],
    services: app.Services);

The agent-side RAG flow is:

The user asks a question.
The agent decides it needs private knowledge.
The agent calls the retrieval tool with a focused query.
The application searches the allowed sources.
The agent receives a few results and answers from them.

At that point, retrieval is just another tool.
The pattern fits Agent Framework because tools already give you that controlled application boundary.

The user message is not always the search query

Users ask messy questions.

For example:

What were the most important changes in our cancellation policy last year?

A better retrieval query might be:

cancellation policy changes last year

Or, if you expose metadata filters:

await SearchKnowledgeAsync(
    query: "cancellation policy changes last year",
    category: "policy",
    limit: 5,
    services,
    cancellationToken);

The agent can help here.
It can translate a conversational request into a smaller retrieval query.

But do not overcomplicate this too early.
Start by logging the generated tool query and checking whether it actually finds better results than the raw user message.

Bad query rewriting is worse than no query rewriting.
It can remove the term that mattered.

Metadata filters keep retrieval inside the boundary

Vector similarity finds related text.
It does not know whether that text belongs to the right tenant, product, language, version, source system, or user permission scope.

You often need filters.

Common filters include:

tenant
user permissions
document type
product
category
language
date
version
source system

Some filters can be model supplied.
category is a reasonable example because the model can often infer whether a question is about a policy, runbook, product, or support article.

Some filters should not be model supplied.

Tenant, user ID, role, entitlement, and document permissions should come from your authenticated application context.
The model should not be allowed to say:

Search tenant = admin

and suddenly see admin-only documents.

A better application boundary looks like this:

public interface IKnowledgeSearch
{
    Task<IReadOnlyList<KnowledgeSearchResult>> SearchAsync(
        string query,
        string? category,
        int limit,
        UserKnowledgeScope scope,
        CancellationToken cancellationToken);
}

The tool can accept the search query and category.
Your application adds UserKnowledgeScope from the current user.

Similarity search finds related text.
Metadata filters keep the search inside the right boundary.

Manual retrieval is still valid

Exposing retrieval as a tool is not the only option.

For a pure documentation assistant, you may not want the model to decide whether to search.
You may want retrieval on every request.

Plain application code is enough:

IReadOnlyList<KnowledgeSearchResult> results =
    await knowledgeSearch.SearchAsync(
        query: userQuestion,
        category: null,
        limit: 5,
        cancellationToken);

string context = string.Join(
    "\n\n",
    results.Select(result => $"""
    Source: {result.Title}
    {result.Snippet}
    """));

AgentResponse response = await supportAgent.RunAsync($"""
    Answer the user's question using the retrieved context.
    If the context is not enough, say so.

    Retrieved context:
    {context}

    User question:
    {userQuestion}
    """,
    cancellationToken: cancellationToken);

You can also use Agent Framework context providers, such as TextSearchProvider, when that fits your setup.
The tradeoff is the same either way:

automatic retrieval is predictable
retrieval as a tool is more selective

If almost every request needs private knowledge, retrieve before the agent call.
If retrieval is one capability among several, expose it as a tool.

When RAG is the wrong tool

RAG is for finding relevant context.
Code is for exact operations.

If the user asks:

What are the top 5 products by revenue?

that should probably be SQL or an analytics API, not vector search.

The same applies to:

exact lookups
IDs
prices
current status
rankings
totals
permissions
deterministic business rules

Vector search is good at finding related text.
It is not a calculator, database constraint, authorization system, or reporting engine.

If the answer must be exact, use normal code behind a tool.

For example:

[Description("Returns the top products by revenue for an authorized reporting period.")]
public static Task<IReadOnlyList<ProductRevenue>> GetTopProductsByRevenueAsync(
    DateOnly from,
    DateOnly to,
    int limit,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var reporting = services.GetRequiredService<IRevenueReporting>();

    return reporting.GetTopProductsByRevenueAsync(
        from,
        to,
        Math.Clamp(limit, 1, 20),
        cancellationToken);
}

This still gives the agent a tool.
It is just not RAG.

When I would use this

Use retrieval with an Agent Framework agent when:

the answer depends on private documents or records
the model's generic knowledge is not enough
stuffing the prompt would be expensive or noisy
the agent can benefit from searching only when needed
the application can enforce source permissions behind the tool

Start with a narrow search tool.
Log the query the agent sends.
Log the sources returned.
Check whether the answer actually used those sources.

That gives you enough signal to see where the retrieval design is weak.

When I would not use this

Do not use RAG when the task needs deterministic data access or computation.

Use normal code for current state, totals, rankings, exact IDs, prices, permissions, and business rules.

Do not use RAG as a way to bypass application boundaries.
If a user cannot access a document in the product, the retrieval tool should not return it to the agent.

Also avoid building the full ingestion and retrieval platform before you have a real use case.
Start with one domain, a small corpus, and a handful of questions you can verify.

Conclusion

Agent Framework gives you a clean place to put retrieval into the agent loop.
It does not make RAG automatic.

The design I would carry forward is simple:

keep private knowledge outside the base prompt
expose retrieval as a focused capability
let the application enforce permissions and filters
give the agent only the context it needs
use code, not RAG, for exact operations

As I said before, I will do a deep dive into RAG later on. So in the next Agent Framework post we will move to multimodal agents: images, PDFs, and provider differences.
The agent boundary gets messy there in a different way.
Some providers can work with images or document inputs natively, some need different message formats, and some scenarios are still better handled by manual preprocessing before the agent sees anything.

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.

DEV Community: Lukas Walter

Human-in-the-Loop Agents: When the AI Must Ask Before Acting

Approval is not a nicer prompt

Start with the side effects

A tool that must not run silently

Wrap the risky tool with approval

Handle approval requests after each run

Send the decision back to the same session

Approval state belongs outside the model

Revalidate before execution

When a workflow is the better implementation

Tool approval inside a workflow

Checkpoints matter for delayed approval

Do not make approval the only guardrail

Human edits are not the same as approval

Make approval observable

When I would use direct tool approval

When I would use workflows

When I would not use human approval

Conclusion

Further reading

Deploy a .NET MCP server to Azure Functions

Prerequisites

Start from the existing repository

Why custom handlers

Change Program.cs

Add host.json

Add local Functions settings

Copy host.json on publish

Run locally with Azure Functions Core Tools

Test with MCP Inspector

Publish the Function App package

Create Azure resources

Deploy the package

What changed compared to Container Apps

Azure Container Apps vs Azure Functions

Troubleshooting checklist

Cleanup

When to use this

When not to use this

Further reading

Microsoft Agent Framework Multimodal Agents: Images, PDFs, and Provider Differences

Multimodal is message content

Framework support is not model support

What works natively

PDFs are different

Provider differences matter

Keep the agent away from raw uploads

Native vision is not OCR infrastructure

Use tools for document operations

Logging matters more with files

When I would use native multimodal input

When I would preprocess manually

Conclusion

Further reading

Agent Framework RAG for Agents: Giving Your Agent the Right Context

Agents do not know your private data

The minimal RAG shape

Agent Framework is not the RAG engine

Retrieval as an agent tool

The user message is not always the search query

Metadata filters keep retrieval inside the boundary

Manual retrieval is still valid

When RAG is the wrong tool

When I would use this

When I would not use this

Conclusion

Further reading

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

Change `Program.cs`

Add `host.json`

Copy `host.json` on publish