DEV Community: Lukas Walter

Testing Microsoft Agent Framework Applications

Lukas Walter — Fri, 24 Jul 2026 15:30:00 +0000

This is Part 18 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 observability for agents.
The main idea was to make a run visible as a chain of model calls, tool calls, approvals, and workflow events.

Testing starts from the same idea.

An agent run is not one answer string.
It is a small application flow with several boundaries:

user input
-> prompt and context
-> model request
-> model response
-> tool selection
-> tool arguments
-> tool execution
-> structured result or final answer
-> routing or workflow state

If the only test is an end-to-end prompt against a live model, all of those boundaries are mixed together.
When the test fails, you do not know whether the problem is the prompt, the model, the tool schema, the router, the workflow, or the real dependency behind the tool.

The solution is not to pretend that an LLM is deterministic.
The solution is to test each boundary at the level where it is deterministic, then add a smaller number of evaluation-style tests for behavior that genuinely depends on the model.

This post covers:

fake model clients
tool contract tests
structured output tests
routing tests
workflow tests
eval-style regression checks

The examples use xUnit-style assertions, but the testing approach does not depend on xUnit.
The snippets focus on the relevant testing boundary and omit some application-specific factory and workflow setup.

Do not start with the live model

A live model test is useful.
It is also expensive, slow, sometimes flaky, and difficult to diagnose.

That makes it a poor replacement for normal unit and integration tests.

I use a testing pyramid for agent applications:

                    evals
          realistic model and user examples

              application integration tests
       agent + tools + storage + workflow boundaries

              deterministic component tests
        fake model client, tools, schemas, routing

The bottom layer should be the largest.
It should catch ordinary programming mistakes without contacting Azure OpenAI, OpenAI, Foundry, or another provider.

The middle layer proves that the pieces work together.
It can use a fake IChatClient, an in-memory repository, and a real workflow execution.

The top layer checks behavior that cannot be completely specified with ordinary assertions:

whether an answer is useful
whether a route is appropriate for an ambiguous request
whether a summary preserves important facts
whether an agent follows a policy in realistic conversations

That last layer is closer to evaluation than to unit testing.
It belongs in the test strategy, but it should not carry the whole strategy.

Put the model behind `IChatClient`

The most important test seam is the model client.

Microsoft Agent Framework builds on the Microsoft.Extensions.AI abstractions, including IChatClient.
That means an application can construct an agent with a real provider in production and a scripted client in tests.

The fake client does not need to simulate intelligence.
It only needs to return the response that the test scenario requires and record what the application sent to it.
I prefer this small fake over mocking IChatClient with Moq or NSubstitute.
Response streams and ChatResponse to ChatResponseUpdate conversions are tedious to configure correctly, while the fake exercises the real interface and conversion path.

Here is a small scripted client:

using Microsoft.Extensions.AI;

public sealed class ScriptedChatClient : IChatClient
{
    private readonly Queue<ChatResponse> responses;

    public ScriptedChatClient(params string[] responseTexts)
    {
        responses = new Queue<ChatResponse>(
            responseTexts.Select(text =>
                new ChatResponse(
                    new ChatMessage(ChatRole.Assistant, text))));
    }

    public List<IReadOnlyList<ChatMessage>> Requests { get; } = [];

    public Task<ChatResponse> GetResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        IReadOnlyList<ChatMessage> request = messages.ToList();
        Requests.Add(request);

        if (responses.Count == 0)
        {
            throw new InvalidOperationException(
                "The scripted client has no response left.");
        }

        return Task.FromResult(responses.Dequeue());
    }

    public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        [System.Runtime.CompilerServices.EnumeratorCancellation]
        CancellationToken cancellationToken = default)
    {
        ChatResponse response = await GetResponseAsync(
            messages,
            options,
            cancellationToken);

        foreach (ChatResponseUpdate update in response.ToChatResponseUpdates())
        {
            yield return update;
        }
    }

    public object? GetService(Type serviceType, object? serviceKey = null)
        => null;

    public void Dispose()
    {
    }
}

This is intentionally simple.
It gives the test three useful capabilities:

It never calls a model provider.
It fails when the application makes more model calls than the scenario expects.
It lets the test inspect the messages and options sent to the model boundary.

For a real test project, I would usually add a few more features:

scripted responses that include usage metadata
a response factory that can inspect the request
a separate queue for streaming updates
a flag that records whether the request asked for JSON schema output
cancellation support for timeout tests

Do not make the fake client clever enough to become a second model implementation.
The point is to control the scenario, not to reproduce provider behavior.

Test the agent boundary

Once the client is injectable, the agent can be built exactly as it is in the application.

For example, this factory keeps the model client outside the test itself:

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

public static class SupportAgentFactory
{
    public static AIAgent Create(IChatClient chatClient)
    {
        return chatClient.AsAIAgent(
            name: "support-agent",
            instructions: """
            You are a support assistant.
            Answer using the available support tools when current data is required.
            Do not invent ticket status.
            """);
    }
}

A basic test can now verify the agent's application boundary without a network call:

[Fact]
public async Task Agent_returns_scripted_answer()
{
    var client = new ScriptedChatClient(
        "The ticket is waiting for customer information.");

    AIAgent agent = SupportAgentFactory.Create(client);

    AgentResponse response = await agent.RunAsync(
        "What is the status of ticket 42?");

    Assert.Equal(
        "The ticket is waiting for customer information.",
        response.Text);

    Assert.Contains(
        client.Requests.Single(),
        message => message.Role == ChatRole.User
            && message.Text!.Contains("ticket 42", StringComparison.OrdinalIgnoreCase));
}

This test does not prove that a real model would answer the same way.
That is not what it is trying to prove.

It proves that:

the agent can be constructed with the configured client
the input reaches the model boundary
the response is returned through the application API

That is already valuable.

You can also use the recorded requests to test prompt construction, context providers, chat reducers, or session behavior.
For example, a test can assert that a tenant id is present in the request and that a reduced history does not exceed a known message count.

Avoid asserting the entire serialized prompt unless the prompt itself is the contract.
Small instruction changes should not break every test.
Assert the important invariant instead:

Assert.Contains(
    client.Requests.Single().Select(message => message.Text),
    text => text?.Contains("tenant-42", StringComparison.Ordinal) == true);

Tool tests have two different jobs

A tool has at least two contracts:

The C# contract that executes the function.
The AI contract that describes the function to the model.

Test both.

Test the function as normal application code

The function itself should have ordinary unit tests.
It should not require an LLM just because it is exposed as an AIFunction.

public sealed record TicketStatus(
    int TicketId,
    string State,
    bool NeedsCustomerReply);

public sealed class TicketService
{
    public Task<TicketStatus> GetStatusAsync(
        int ticketId,
        CancellationToken cancellationToken = default)
    {
        return Task.FromResult(
            new TicketStatus(
                TicketId: ticketId,
                State: "WaitingForCustomer",
                NeedsCustomerReply: true));
    }
}

Test the service directly:

[Fact]
public async Task Ticket_service_returns_current_status()
{
    var service = new TicketService();

    TicketStatus result = await service.GetStatusAsync(42);

    Assert.Equal(42, result.TicketId);
    Assert.Equal("WaitingForCustomer", result.State);
    Assert.True(result.NeedsCustomerReply);
}

This catches business logic errors, authorization mistakes, invalid mappings, and dependency failures.
It is much easier to diagnose than an end-to-end test that only says the agent gave a bad answer.

Test the generated AI contract

Now expose the method as a function.
Keep the service as trusted instance state rather than adding it to the model-controlled argument list:

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

public sealed class SupportTools(TicketService service)
{
    [Description("Gets the current status of a support ticket.")]
    public Task<TicketStatus> GetTicketStatusAsync(
        [Description("The numeric support ticket identifier.")]
        int ticketId,
        CancellationToken cancellationToken = default)
    {
        return service.GetStatusAsync(ticketId, cancellationToken);
    }
}

AIFunction tool = AIFunctionFactory.Create(
    (Func<int, CancellationToken, Task<TicketStatus>>)
        new SupportTools(new TicketService()).GetTicketStatusAsync,
    new AIFunctionFactoryOptions
    {
        Name = "get_ticket_status"
    });

The test should create the same AIFunction that the agent receives and inspect its declaration.
The TicketService instance is stored by SupportTools and captured by the delegate, so it does not appear in the AI-facing JSON schema.

[Fact]
public void Ticket_tool_exposes_a_narrow_contract()
{
    AIFunction tool = CreateTicketTool();

    Assert.Equal("get_ticket_status", tool.Name);
    Assert.Contains("support ticket", tool.Description,
        StringComparison.OrdinalIgnoreCase);
    Assert.Contains("ticketId", tool.JsonSchema.GetProperty("properties").EnumerateObject()
        .Select(property => property.Name));
    Assert.NotNull(tool.ReturnJsonSchema);
}

The important assertions are not necessarily the exact generated JSON string.
They are the properties that affect model behavior:

the tool has the intended name
the description says what it actually does
required parameters are present
parameters have the intended types
internal services are not exposed as model parameters
the result schema is present when the model needs it

The generated JSON schema is part of the prompt boundary.
A rename, a missing Description, or an accidentally exposed service parameter can change tool selection even when the C# function still compiles.

Test side effects separately from tool selection

A tool contract test does not prove that an agent will select the tool.
It proves that the tool is described correctly.

That distinction matters for side effects.

For a tool that sends an email, deletes data, deploys a release, or charges a card, add tests for:

authorization
validation of every argument
idempotency behavior
approval handling
cancellation
duplicate calls
failure and retry behavior

Then test that the tool is wrapped with the expected approval boundary.
The model can request the function, but the function should not execute just because the model requested it.

Structured output needs shape tests and meaning tests

Structured output gives application code a type instead of an unstructured string.
It does not make the model's values correct.

That gives us two test categories.

Test successful deserialization

The Microsoft.Extensions.AI structured-output extensions can request a typed ChatResponse<T> from an IChatClient.
With a fake client, the response can be controlled as JSON:

public sealed record IntentResult(
    string Intent,
    double Confidence,
    string Reason);

[Fact]
public async Task Structured_output_is_deserialized_into_the_expected_type()
{
    var client = new ScriptedChatClient(
        """
        {
          "intent": "billing",
          "confidence": 0.91,
          "reason": "The user asks about an invoice."
        }
        """);

    ChatResponse<IntentResult> response =
        await client.GetResponseAsync<IntentResult>(
            "Classify this request.",
            useJsonSchemaResponseFormat: false);

    IntentResult result = response.Result;

    Assert.Equal("billing", result.Intent);
    Assert.Equal(0.91, result.Confidence, precision: 2);
}

The useJsonSchemaResponseFormat: false argument keeps this test focused on deserialization.
A separate integration test can verify that the provider supports native JSON schema response formatting.

Also test malformed output:

[Fact]
public async Task Structured_output_test_fixture_can_expose_invalid_model_output()
{
    var client = new ScriptedChatClient(
        "{ \"intent\": \"billing\", \"confidence\": \"certain\" }");

    ChatResponse<IntentResult> response =
        await client.GetResponseAsync<IntentResult>(
            "Classify this request.",
            useJsonSchemaResponseFormat: false);

    Assert.False(response.TryGetResult(out _));
}

A model is not guaranteed to honor the requested schema.
Your application still needs a policy for a response that cannot be parsed:

retry with a repair request
return a controlled error
route to a human
use a safe fallback

The test should prove that the policy is applied.

Test business validation after deserialization

Do not stop at response.Result.

For the router, a valid IntentResult can still be unsafe:

var result = new IntentResult(
    Intent: "delete-production-data",
    Confidence: 0.99,
    Reason: "The user wants cleanup.");

The JSON is valid.
The intent is not one of the allowed routes.

Keep the next validation step in normal C#:

public enum UserIntent
{
    Support,
    Billing,
    Other
}

public sealed record ValidatedRoute(
    UserIntent Intent,
    double Confidence);

public static ValidatedRoute ValidateRoute(IntentResult result)
{
    if (!Enum.TryParse<UserIntent>(
            result.Intent,
            ignoreCase: true,
            out UserIntent intent))
    {
        return new ValidatedRoute(UserIntent.Other, 0);
    }

    double confidence = Math.Clamp(result.Confidence, 0, 1);
    return new ValidatedRoute(intent, confidence);
}

Test invalid enum values, missing fields, out-of-range confidence, and a low-confidence result.
These tests protect the application boundary even when the model produces a structurally valid object.

Routing tests should mostly be ordinary C# tests

The manual routing article used a small intent agent followed by a C# switch statement.
That division makes routing easier to test.

The model classifies.
The application routes.

The route function can be tested with a table of known decisions:

[Theory]
[InlineData(UserIntent.Support, "support-agent")]
[InlineData(UserIntent.Billing, "billing-agent")]
[InlineData(UserIntent.Other, "fallback")]
public void Route_uses_the_application_mapping(
    UserIntent intent,
    string expectedAgent)
{
    string actualAgent = intent switch
    {
        UserIntent.Support => "support-agent",
        UserIntent.Billing => "billing-agent",
        _ => "fallback"
    };

    Assert.Equal(expectedAgent, actualAgent);
}

The real application method might return a delegate, an agent, or a command object.
The testing principle stays the same: once the model has produced a validated route, routing should be deterministic.

You should also test route boundaries:

low confidence asks for clarification
unknown intent uses the safe fallback
a restricted tenant cannot select a privileged agent
a request requiring approval cannot bypass the approval path
the specialist receives the original user input and the minimum necessary context
the fallback does not accidentally invoke an expensive specialist

Then test the model-based classifier separately with scripted responses:

[Theory]
[InlineData("Where is my invoice?", "billing")]
[InlineData("The login link is broken.", "support")]
public async Task Classifier_uses_the_typed_model_result(
    string userMessage,
    string expectedIntent)
{
    var client = new ScriptedChatClient(
        $$"""
        {
          "intent": "{{expectedIntent}}",
          "confidence": 0.95,
          "reason": "Test fixture"
        }
        """);

    AIAgent classifier = CreateClassifier(client);
    AgentResponse<IntentResult> response =
        await classifier.RunAsync<IntentResult>(userMessage);

    Assert.Equal(expectedIntent, response.Result.Intent);
}

This checks the classifier integration.
It does not claim that the model will classify every real user message correctly.
That is what the eval set is for.

Workflow tests should assert events and outputs

A workflow is more than its final output.
The previous workflow articles covered explicit executors, edges, events, and human-in-the-loop pauses.
Those are all testable.

For a simple workflow, run it in-process and inspect the emitted events:

using Microsoft.Agents.AI.Workflows;

[Fact]
public async Task Workflow_emits_the_expected_steps_and_output()
{
    Workflow workflow = CreateReviewWorkflow(
        chatClient: new ScriptedChatClient(
            "The document is safe to publish.",
            "The final review is approved."));

    await using Run run = await InProcessExecution.Lockstep.RunAsync(
        workflow,
        new ReviewRequest("document-42"));

    Assert.Contains(
        run.OutgoingEvents,
        eventItem => eventItem is WorkflowOutputEvent output
            && output.Data?.ToString() == "The final review is approved.");

    Assert.DoesNotContain(
        run.OutgoingEvents,
        eventItem => eventItem is WorkflowErrorEvent);
}

The exact event types and workflow output depend on the workflow.
The useful assertions are usually:

the expected executor ran
the output has the expected type
a branch was or was not taken
an error event was emitted when a step failed
the workflow stopped at an approval request
resuming with the response continues from the pause instead of restarting everything

Lockstep execution is useful for tests because it makes event ordering deterministic.
That is especially helpful when the production workflow uses streaming execution and events arrive while the workflow is running.

For a workflow with a branch, assert the branch rather than only the final text:

Assert.Contains(
    run.OutgoingEvents,
    eventItem => eventItem is ExecutorCompletedEvent completed
        && completed.ExecutorId == "security-review");

Assert.DoesNotContain(
    run.OutgoingEvents,
    eventItem => eventItem is ExecutorCompletedEvent completed
        && completed.ExecutorId == "publish-document");

That test says something meaningful about the process.
An assertion such as Assert.Contains("safe", finalText) would be much weaker.

Test pauses and resumptions

A human approval workflow should have at least three tests:

The workflow requests approval before the side effect.
Rejection ends the flow without executing the side effect.
Approval resumes the flow and executes only after the decision.

Keep the side effect behind a spy or fake service:

public sealed class RecordingPublisher : IPublisher
{
    public List<string> PublishedDocuments { get; } = [];

    public Task PublishAsync(
        string documentId,
        CancellationToken cancellationToken = default)
    {
        PublishedDocuments.Add(documentId);
        return Task.CompletedTask;
    }
}

Then assert the important safety property:

Assert.Empty(publisher.PublishedDocuments);

after the rejected approval.

The model's text is not the approval boundary.
The workflow event and the application response are.

Eval-style regression checks are a separate layer

Some behavior cannot be tested with exact string assertions.

Suppose the support agent should:

answer from the ticket data
avoid inventing a resolution
ask for missing information
use the billing route for invoices
never expose another tenant's data

There may be many acceptable answers.
An exact string assertion would reject good changes and accept bad ones that happen to match the fixture.

Agent Framework now includes an evaluation framework for this layer.
It provides local evaluators for fast checks and integrations with model-based evaluators when you need a semantic quality judgment.

For this kind of behavior, create a small evaluation set and run it through the built-in APIs.

For example, a local evaluator can check required words and tool usage without another model call:

using Microsoft.Agents.AI;

var local = new LocalEvaluator(
    EvalChecks.KeywordCheck("ticket"),
    EvalChecks.ToolCalledCheck("get_ticket_status"));

AgentEvaluationResults results = await agent.EvaluateAsync(
    ["What is the current status of ticket 42?"],
    local);

results.AssertAllPassed();

For quality dimensions such as relevance, coherence, groundedness, or task adherence, use a configured evaluator such as the Azure AI Foundry evaluator or a Microsoft.Extensions.AI.Evaluation evaluator.
Those checks are still regression tests, but they have model and evaluator variance, so they should usually run in a separate CI or release-evaluation stage.

The framework can also evaluate workflows and report per-agent results, which is useful when the final answer looks acceptable but one specialist or route has degraded.

The evaluation set remains an application responsibility.
The framework provides the execution and result types, but you still need to define representative cases, expected routes, expected tool calls, safety constraints, and acceptable quality thresholds.

public sealed record AgentCase(
    string Name,
    string Input,
    string ExpectedRoute,
    string[] RequiredFacts,
    string[] ForbiddenPhrases);

static readonly AgentCase[] Cases =
[
    new(
        Name: "invoice question",
        Input: "Why was I charged twice for invoice 42?",
        ExpectedRoute: "billing",
        RequiredFacts: ["invoice"],
        ForbiddenPhrases: ["I refunded your payment"]),

    new(
        Name: "missing ticket context",
        Input: "Can you fix my issue?",
        ExpectedRoute: "support",
        RequiredFacts: ["ticket", "more information"],
        ForbiddenPhrases: ["ticket is fixed"])
];

Each case can be run against a pinned model and evaluated with a mix of checks:

deterministic route assertions
required and forbidden content checks
structured output validation
tool-call assertions
human review for a small sample
an evaluator model for semantic criteria

The evaluator should not be the only judge.
If a deterministic check can express the requirement, use the deterministic check.

For example, the route is usually an enum and can be compared exactly.
Whether an explanation is helpful may need a rubric.

public sealed record EvaluationResult(
    string CaseName,
    bool RoutePassed,
    bool RequiredFactsPassed,
    bool ForbiddenPhrasesPassed,
    double HelpfulnessScore,
    string Notes);

Store the result with enough metadata to compare runs later:

model identifier and deployment
Agent Framework and Microsoft.Extensions.AI package versions
prompt or instruction version
tool manifest version
evaluation-set version
timestamp
token usage and latency
pass/fail result and evaluator notes

Do not compare a new run with an old run while silently changing all of those inputs.
If the model, prompt, tools, or data changed, record the change.

What belongs in a regression gate?

Not every score should block a pull request.

I would use three levels:

pull request
-> deterministic tests
-> fake-client integration tests
-> small, stable eval smoke set

nightly or release candidate
-> larger eval set
-> live provider runs
-> human review for sampled cases

A pull request gate can reasonably fail when:

structured output no longer parses
a required tool disappears from the schema
a route changes for a locked fixture
a workflow stops emitting a required event
a forbidden action is invoked
token usage exceeds a deliberately chosen budget

A nightly eval can track softer changes such as helpfulness, completeness, or groundedness.

Do not turn a noisy evaluator score into a hard gate before you understand its variance.
Otherwise developers will learn to ignore the test suite.

Test the failure paths on purpose

Agent systems have failure modes that ordinary CRUD applications do not have.
Add explicit scenarios for them.

The model fails

Script the model client to throw a provider exception or return an empty response.
Assert the application returns a controlled error and does not execute a side effect.

The model returns invalid structured output

Return malformed JSON, missing required properties, an unknown enum, or a value outside the allowed range.
Assert the retry, fallback, or escalation policy.

The model requests the wrong tool

If you can construct a provider-neutral function-call fixture, use it to prove that an unsupported tool call is rejected.
Also verify that the tool layer validates arguments instead of trusting the model to be polite.

The tool fails

Throw a timeout, an authorization exception, and a domain validation exception from the fake service.
Assert what the agent sees and whether another model iteration is allowed.

The agent loops

Configure a scripted client with repeated tool requests or repeated repair responses.
Assert that the configured iteration cap ends the run.
An agent test that can hang forever is a test suite problem.

The user cancels

Cancel the token during a model call, tool call, or workflow run.
Assert that the cancellation reaches the dependency and that the application does not report a successful side effect.

The context is too large

Use a recording client to count messages or inspect approximate input size.
This catches a disabled reducer, an over-eager retriever, or a tool that returns too much data.

These tests are not about making the model predictable.
They are about making the application predictable when the model or one of its dependencies is not.

Keep test data inside the trust boundary

Agent tests often contain realistic tickets, documents, prompts, and tool arguments.
Treat those fixtures as application data.

Do not put production conversations into a repository just because they are useful examples.
Redact names, emails, tokens, internal URLs, credentials, and customer-specific identifiers.

For live evaluation runs, decide:

which data may leave the test environment
which provider and region receives it
whether prompts and outputs are retained
who can inspect the results
how long artifacts are stored
whether the evaluator itself sees sensitive content

The Agent Framework safety guidance treats model calls, chat history, context providers, and tools as separate trust boundaries.
Your test pipeline crosses the same boundaries.

A practical test plan

When I add a new agent feature, I usually start with this checklist:

1. Test the normal C# service or tool directly.
2. Test the generated AIFunction name, description, and schemas.
3. Test the agent with a scripted IChatClient.
4. Test structured output parsing and business validation.
5. Test routing with normal C# values and low-confidence cases.
6. Test workflow outputs, branches, errors, and approval pauses.
7. Add a small eval set for behavior that exact assertions cannot express.
8. Run a larger live evaluation outside the fast unit-test loop.

This ordering gives fast feedback first.
It also keeps failures local.

If a tool contract test fails, inspect the tool declaration.
If a routing test fails, inspect the switch or policy.
If a structured output test fails, inspect parsing and validation.
If an eval fails while all deterministic tests pass, inspect the prompt, model, data, or rubric.

That is a much better debugging experience than a single red test named Agent_should_answer_correctly.

When I would use this approach

I would use this layered approach when the agent has tools or external side effects, returns structured data, uses multiple routes or workflows, needs approval handling, or is moving beyond a prototype.
I would start with the fake client and tool tests even for a small prototype because they are cheap and keep the model boundary replaceable.

When I would not overbuild it

I would not begin with a large evaluation platform while the agent has no stable behavior, no meaningful tools or routes, or no agreed definition of a good answer.
Start with a scripted IChatClient, a few failure cases, and one or two realistic examples.
Add a larger evaluation set when the behavior is stable enough for the results to mean something.

Conclusion

An agent is not an untestable black box.
The model is one nondeterministic component inside a larger .NET application, while the application still owns deterministic boundaries such as tool behavior and schemas, structured output validation, routing, workflow events, approvals, and failure policies.

Use fake model clients for fast tests, ordinary C# tests for routing and business rules, workflow assertions for process behavior, and evals for quality that needs realistic language examples.
The goal is not to make every agent answer identical text.
It is to know which parts of the system are correct, which parts are model-dependent, and what changed when a test or evaluation fails.

The next article moves from agents that live mainly in code to agents managed as cloud resources in Microsoft Foundry.
We will compare local Agent Framework development with Foundry's persistent agents and threads, RBAC, governance, lifecycle management, and the enterprise trade-offs that come with adding a cloud control plane.

Generate Useful Test Data in .NET with Bogus

Lukas Walter — Wed, 22 Jul 2026 15:30:00 +0000

Most applications need more test data than a few hand-written objects can provide. A single unit test may need one customer, but an integration test often needs hundreds of customers, orders, timestamps, statuses, and relationships that look plausible together.

Bogus is a .NET library for generating that kind of fake data. You describe how an object should be created, and Bogus generates one object or a collection of objects from those rules.

The useful distinction is this: Bogus generates data. It does not replace mocks, assertions, contract tests, or production data-quality checks. It is a tool for creating controlled input for development and testing.

What Bogus does

Bogus provides two things:

Faker<T> describes how to build instances of a type.
Data sets such as Name, Address, Internet, Commerce, Date, and Random provide reusable generators.

The main API is fluent. A rule maps a property to either a fixed value or a callback that receives a Bogus faker instance:

var faker = new Faker<Customer>()
    .RuleFor(customer => customer.FirstName, f => f.Name.FirstName())
    .RuleFor(customer => customer.LastName, f => f.Name.LastName());

Customer customer = faker.Generate();
List<Customer> customers = faker.Generate(100);

Generate() creates one object. Generate(count) creates a collection. Each call evaluates the rules again, so the generated values normally differ.

Install Bogus

At the time of writing, NuGet lists version 35.6.5; pin the version in real projects when repeatability matters, and update it deliberately when upgrading dependencies.

dotnet add package Bogus --version 35.6.5

The package is usually most useful in test projects, development-only seeders, demo applications, and tools that need a large amount of sample data. Keep it out of production application paths unless generating sample data is an explicit product feature.

Start with a simple faker

Here is a small model for the examples in this post:

public enum CustomerStatus
{
    Trial,
    Active,
    Suspended
}

public sealed class Customer
{
    public int Id { get; set; }
    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public string Email { get; set; } = "";
    public string CountryCode { get; set; } = "";
    public CustomerStatus Status { get; set; }
    public DateTime CreatedAtUtc { get; set; }
}

Now define the data rules in one place:

using Bogus;

var nextCustomerId = 1;

var customerFaker = new Faker<Customer>("en")
    .StrictMode(true)
    .RuleFor(customer => customer.Id, _ => nextCustomerId++)
    .RuleFor(customer => customer.FirstName, f => f.Name.FirstName())
    .RuleFor(customer => customer.LastName, f => f.Name.LastName())
    .RuleFor(customer => customer.Email, f => f.Internet.ExampleEmail())
    .RuleFor(customer => customer.CountryCode, f => f.Address.CountryCode())
    .RuleFor(customer => customer.Status, f => f.PickRandom<CustomerStatus>())
    .RuleFor(customer => customer.CreatedAtUtc,
        f => f.Date.PastOffset(2).UtcDateTime);

Customer customer = customerFaker.Generate();
List<Customer> customers = customerFaker.Generate(100);

The counter makes this faker stateful. Avoid sharing stateful faker instances across parallel tests. Prefer creating a fresh faker per test or per fixture operation when rules close over counters such as nextCustomerId.

The f parameter is a Faker instance. It exposes the built-in data sets and randomization helpers. For example:

f.Name.FirstName()
f.Address.CountryCode()
f.Date.PastOffset(2)
f.Random.Int(1, 10)
f.PickRandom<CustomerStatus>()

StrictMode(true) is valuable for reusable test fixtures. It makes Bogus complain when a writable property has no rule, so adding a property to the model does not silently leave the fixture incomplete. You can omit it for quick prototypes, but explicit rules make larger fixtures easier to review.

Rules can depend on the object being generated

Some values should be related to other values on the same object. Use the overload that receives both the faker and the object under construction:

var customerFaker = new Faker<Customer>("en")
    .RuleFor(customer => customer.FirstName, f => f.Name.FirstName())
    .RuleFor(customer => customer.LastName, f => f.Name.LastName())
    .RuleFor(customer => customer.Email,
        (f, customer) => f.Internet.Email(
            customer.FirstName,
            customer.LastName));

This produces an email address that matches the generated name. For test systems that must never accidentally send mail, ExampleEmail() is a safer default because it uses a reserved example domain. If the system under test needs a particular email format, prefer a reserved non-resolving domain such as test.invalid and assert that the application treats it as test data.

You can also use a custom callback for domain-specific rules:

public sealed class Subscription
{
    public string Plan { get; set; } = "";
    public int Seats { get; set; }
}

var planNames = new[] { "Starter", "Team", "Enterprise" };

var subscriptionFaker = new Faker<Subscription>()
    .RuleFor(subscription => subscription.Plan,
        f => f.PickRandom(planNames))
    .RuleFor(subscription => subscription.Seats,
        (f, subscription) => subscription.Plan switch
        {
            "Starter" => f.Random.Int(1, 3),
            "Team" => f.Random.Int(4, 25),
            _ => f.Random.Int(26, 500)
        });

The important part is that the generated values follow the rules your application cares about. A random number between 1 and 500 is not automatically realistic for every plan.

Compose related objects

Real test scenarios rarely contain isolated objects. A customer may have orders, and an order should refer to an existing customer rather than a random integer that happens to look like an ID.

Generate the parent objects first, then use them when defining the child faker:

public sealed class Order
{
    public int Id { get; set; }
    public int CustomerId { get; set; }
    public decimal Total { get; set; }
    public DateTime CreatedAtUtc { get; set; }
}

var customers = customerFaker.Generate(25);
var nextOrderId = 1;

var orderFaker = new Faker<Order>()
    .StrictMode(true)
    .RuleFor(order => order.Id, _ => nextOrderId++)
    .RuleFor(order => order.CustomerId,
        f => f.PickRandom(customers).Id)
    .RuleFor(order => order.Total,
        f => f.Finance.Amount(10, 2_000))
    .RuleFor(order => order.CreatedAtUtc,
        f => f.Date.PastOffset(2).UtcDateTime);

var orders = orderFaker.Generate(100);

This pattern is often more useful than generating a large object graph in a single expression. Each faker has one responsibility, and the relationship between the generated collections is visible in the test setup.

For a development database, the same approach can be used in a dedicated seeding step:

var customers = customerFaker.Generate(1_000);
var orders = orderFaker.Generate(5_000);

db.Customers.AddRange(customers);
db.Orders.AddRange(orders);
await db.SaveChangesAsync();

Keep this code separate from production startup. A development seeder should be deliberate, repeatable, and impossible to run against a production connection by accident.

If the database owns identity values, let EF Core generate the keys or build child records after the parent keys are known. Explicit integer IDs can conflict with identity and primary-key configuration, depending on how the model is mapped.

Make generated data repeatable

Random data is useful for finding unexpected cases, but a failing test is much easier to investigate when the same input can be generated again. Bogus supports repeatable output through a randomizer seed:

using Bogus;

Randomizer.Seed = new Random(12345);

var customers = customerFaker.Generate(10);

Use a seed when you need to reproduce a failing scenario or keep a development dataset stable while debugging. Do not make tests depend on exact generated names or on the exact order of every random value. Test the properties that matter:

For unit tests, prefer local seeding with UseSeed when you want a specific generated object to be repeatable without coupling other tests to a global random sequence:

var customer = customerFaker
    .UseSeed(12345)
    .Generate();

Local seeding controls Bogus randomness, not external state captured by your rules. If a faker closes over counters such as nextCustomerId, create a fresh faker before generating the seeded object.

var customer = customerFaker.Generate();

Assert.NotEqual(0, customer.Id);
Assert.False(string.IsNullOrWhiteSpace(customer.Email));
Assert.Matches("^[A-Z]{2}$", customer.CountryCode);

Randomizer.Seed is global state. Set it deliberately, preferably at the boundary of a test or data-generation operation, and be aware that other tests using Bogus may be affected. Also remember that values generated outside Bogus, such as Guid.NewGuid() or DateTime.UtcNow, are not made deterministic by the Bogus seed.

Even with a seed, generated values can change when you upgrade Bogus or its locale data. Avoid asserting exact fake names unless that exact value is the behavior under test. For maximum unit-test stability, stay within the same major version and treat dependency upgrades as a reason to review deterministic fixtures.

For fully stable timestamp fixtures, use a fixed date range or inject a known reference time instead of relying on a Past value relative to now.

Use custom constructors when necessary

Some domain types cannot be created with a parameterless constructor. CustomInstantiator lets the faker create the object using the constructor you need:

public sealed class Account
{
    public Account(Guid id)
    {
        Id = id;
    }

    public Guid Id { get; }
    public string Name { get; set; } = "";
}

var accountFaker = new Faker<Account>()
    .CustomInstantiator(f => new Account(f.Random.Guid()))
    .RuleFor(account => account.Name, f => f.Company.CompanyName());

var account = accountFaker.Generate();

This keeps the fixture aligned with the production construction rules instead of weakening the domain model just to make test data easier to create.

Use locales when the scenario needs them

Bogus includes locale-specific data sets. Pass a locale to the faker when names, addresses, or other generated values need to resemble a particular region:

var germanCustomerFaker = new Faker<Customer>("de")
    .RuleFor(customer => customer.FirstName, f => f.Name.FirstName())
    .RuleFor(customer => customer.LastName, f => f.Name.LastName())
    .RuleFor(customer => customer.CountryCode, _ => "DE");

Locales improve the shape of sample data, but they do not make it valid for every business or regulatory scenario. If a postal code, tax number, phone number, or address must satisfy a specific country’s rules, add an explicit domain generator and validate it independently.

When Bogus is a good fit

Bogus is a strong fit when you need:

Unit-test inputs with varied values.
Integration-test datasets for APIs, databases, or message handlers.
Seed data for local development and demos.
Pagination, filtering, sorting, and search scenarios with enough rows to expose mistakes.
Load-test input prepared before the run, where values need to look like the domain model.
Reproducible examples that should not contain real customer data.

The biggest benefit is lower fixture maintenance. Instead of copying a large JSON document into every test, you can describe the few invariants that matter and generate the rest.

It also makes edge cases easier to express. A fixture can generate a normal customer by default, then override one rule for a specific scenario:

var suspendedCustomer = CustomerFixtures.Create()
    .RuleFor(customer => customer.Status, _ => CustomerStatus.Suspended)
    .RuleFor(customer => customer.Email, _ => "suspended-user@test.invalid")
    .Generate();

This reuses the default rules from the shared fixture pattern shown below, then overrides only the values relevant to the scenario. Use fixed values for the behavior under test and randomness for the fields that are incidental.

When Bogus is not the right tool

Do not use Bogus as a substitute for the following:

A mock library. Bogus creates objects and values. It does not configure a mocked service or verify an interaction.
A contract fixture. If a test documents an exact API payload, an explicit hand-written object is often clearer than generated data.
Production customer data. Fake values can look realistic, but they are not anonymized copies of real data and may still create operational risk if sent to external systems.
A domain validator. Bogus may generate a plausible value without satisfying all of your business rules. Test the validator with intentional valid and invalid cases.
A security or payment simulator. A generated card number, account number, or identity number is not permission to call a real provider. Keep integrations behind test doubles or provider sandboxes.
A replacement for boundary cases. Random generation may never produce the exact empty, maximum, duplicate, expired, or malformed value your test needs. Add explicit examples for those cases.

Randomness also makes a poor foundation for a test that should be completely obvious to the next person reading it. If the important input is three strings and one status, write those values directly.

A practical fixture shape

For a larger test suite, keep faker definitions in a dedicated factory or fixture class instead of rebuilding them inside every test:

public static class CustomerFixtures
{
    public static Faker<Customer> Create()
    {
        var nextId = 1;

        return new Faker<Customer>("en")
            .StrictMode(true)
            .RuleFor(customer => customer.Id, _ => nextId++)
            .RuleFor(customer => customer.FirstName, f => f.Name.FirstName())
            .RuleFor(customer => customer.LastName, f => f.Name.LastName())
            .RuleFor(customer => customer.Email, f => f.Internet.ExampleEmail())
            .RuleFor(customer => customer.CountryCode, f => f.Address.CountryCode())
            .RuleFor(customer => customer.Status, f => f.PickRandom<CustomerStatus>())
            .RuleFor(customer => customer.CreatedAtUtc,
                f => f.Date.PastOffset(2).UtcDateTime);
    }
}

Tests can then start with a clear default and override only what matters:

var customer = CustomerFixtures.Create()
    .RuleFor(c => c.Status, _ => CustomerStatus.Suspended)
    .Generate();

This is a good balance between convenience and control. The shared fixture owns the defaults; the test still makes its scenario-specific assumptions visible.

Benefits and tradeoffs

The benefits are practical:

Less repetitive setup code.
More variation than a small set of hand-written fixtures.
Better-looking local development data.
Explicit relationships between generated objects.
Optional repeatability when debugging.
Reusable rules across unit tests, integration tests, and seeders.

The tradeoffs matter too:

A fixture can become difficult to understand if it contains too many hidden rules.
Random output can make failures harder to reproduce if you do not capture a seed.
Generated data may be plausible without being valid for your business domain.
Large generated graphs can make tests slow and obscure the behavior under test.
Global seeding can introduce coupling between tests.

The solution is to keep fakers small, use explicit overrides for important behavior, capture seeds when diagnosing failures, and assert invariants instead of snapshots of random output.

Conclusion

Bogus is most useful when the problem is not “how do I mock this dependency?” but “how do I create enough controlled input to exercise this code?”

Start with a Faker<T>, add rules for the fields that matter, enable StrictMode for shared fixtures, compose related objects from existing generated values, and use a seed when you need to reproduce a failure.

Use it for test data, development data, demos, and load-test inputs. Do not use it as evidence that your business rules, external integrations, or security boundaries work. Those still need explicit tests.

References

Observability for Agents with OpenTelemetry, Aspire, and Application Insights

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

This is Part 17 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 AG-UI and the frontend boundary for agents.
The main point was that agent behavior should not be flattened into plain chat text.
Tool calls, approvals, state updates, and cancellations are separate events.

The same rule applies in production.

Do not treat an agent run as one opaque log line.
An agent run is a chain of model calls, tool calls, retries, approvals, state changes, and external dependencies.
If you cannot see that chain, you cannot debug cost, latency, failure, or unsafe behavior.

I want the trace to look more like this:

HTTP request
-> agent run
-> model call
-> tool call
-> model call
-> approval request
-> tool execution
-> final response

From that trace, I want to answer normal production questions:

Which model was called?
How many input and output tokens were used?
Which tool ran?
How long did each step take?
Did the tool fail or retry?
Did a human approve the side effect?
Was sensitive prompt or tool data captured?
Can I inspect the same flow locally before sending it to the cloud?

OpenTelemetry is the shared telemetry format.
Aspire gives me the local loop.
Application Insights is where the same signals become searchable in Azure, including the agent-focused views in Azure Monitor.

Start with the questions

Before adding packages, decide what the telemetry must explain.

For most agent systems, I would start with these questions:

Question	Signal
Is the agent slow?	Trace duration by run, model call, tool call, dependency call
Is the agent expensive?	Token usage by agent, model, route, tenant, or feature
Is the agent failing?	Exceptions, failed tool calls, failed model calls, finish reasons
Is the agent looping?	Model call count, tool call count, max-iteration exits
Is the agent using the wrong tool?	Tool name, tool risk, tool result class, approval decision
Is sensitive data being exported?	Explicit content-capture setting, redaction policy, sampling policy
Can support find one incident?	Conversation id, run id, trace id, approval id, user-safe correlation id

Notice what is not in the table:

Log the whole prompt and hope it helps later.

This can help in a development environment.
In production, it is often the wrong default.
Prompts, tool arguments, retrieved documents, and tool results may contain customer data, secrets, internal tickets, file contents, or personally identifiable information.

Observability does not mean storing everything.
Treat it like production data, with the same access and retention discipline you would apply anywhere else.

The basic OpenTelemetry setup

Agent Framework builds on Microsoft.Extensions.AI.
That matters because Microsoft.Extensions.AI provides an OpenTelemetry middleware for chat clients.
The extension method is UseOpenTelemetry on ChatClientBuilder.

Start with the chat client:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();

AzureOpenAIClient azureClient = new(
    new Uri(builder.Configuration["AZURE_OPENAI_ENDPOINT"]!),
    new DefaultAzureCredential());

IChatClient chatClient = azureClient
    .GetChatClient(builder.Configuration["AZURE_OPENAI_DEPLOYMENT"]!)
    .AsIChatClient()
    .AsBuilder()
    .UseOpenTelemetry(
        sourceName: builder.Environment.ApplicationName,
        configure: telemetry =>
        {
            telemetry.EnableSensitiveData =
                builder.Environment.IsDevelopment()
                && builder.Configuration.GetValue<bool>(
                    "AI:Telemetry:EnableSensitiveData");
        })
    .UseFunctionInvocation()
    .Build();

WebApplication app = builder.Build();

AIAgent agent = chatClient.AsAIAgent(
    name: "deployment-agent",
    instructions: """
    You help operators inspect deployment state and prepare safe release actions.
    Use tools when current deployment state is needed.
    Ask for approval before production changes.
    """,
    tools:
    [
        AIFunctionFactory.Create(CheckStagingStatusAsync),
        AIFunctionFactory.Create(DeployToProductionAsync)
    ],
    services: app.Services);

Two details matter here.

First, the sourceName is deliberate.
OpenTelemetry tracing only collects activity sources that the tracer provider listens to.
Aspire service defaults already add the application name as a trace source.
Using builder.Environment.ApplicationName keeps the chat client activity source aligned with the application telemetry source.

Second, sensitive data is disabled unless development configuration explicitly enables it.
By default, the OpenTelemetry chat client records metadata such as model information and token counts, but not raw prompts, raw outputs, tool arguments, or tool results.
That default is boring in the best possible way.

Note: The exact telemetry attributes follow the OpenTelemetry Generative AI semantic conventions. Those conventions are still moving, so verify attribute names against your package version before you bake them into dashboards or KQL queries.

Add the AI source to Service Defaults

If you use Aspire, your app probably has a ServiceDefaults project with a ConfigureOpenTelemetry method.
The starter template already configures ASP.NET Core, HttpClient, runtime metrics, OTLP export, and trace collection.

For agent telemetry, make sure the same source name used by UseOpenTelemetry is collected for both traces and metrics.

In the service defaults project, extend the OpenTelemetry setup:

using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

public static TBuilder ConfigureOpenTelemetry<TBuilder>(
    this TBuilder builder)
    where TBuilder : IHostApplicationBuilder
{
    builder.Logging.AddOpenTelemetry(logging =>
    {
        logging.IncludeFormattedMessage = true;
        logging.IncludeScopes = true;
    });

    builder.Services.AddOpenTelemetry()
        .WithMetrics(metrics =>
        {
            metrics
                .AddMeter(builder.Environment.ApplicationName)
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddRuntimeInstrumentation();
        })
        .WithTracing(tracing =>
        {
            tracing
                .AddSource(builder.Environment.ApplicationName)
                .AddAspNetCoreInstrumentation(options =>
                {
                    options.Filter = context =>
                        !context.Request.Path.StartsWithSegments("/health")
                        && !context.Request.Path.StartsWithSegments("/alive");
                })
                .AddHttpClientInstrumentation();

            if (builder.Environment.IsDevelopment())
            {
                tracing.SetSampler(new AlwaysOnSampler());
            }
        });

    builder.AddOpenTelemetryExporters();

    return builder;
}

These two lines matter:

.AddMeter(builder.Environment.ApplicationName)
.AddSource(builder.Environment.ApplicationName)

The chat client creates an ActivitySource and a Meter.
If your OpenTelemetry configuration does not listen to them, the code can be instrumented and still produce nothing in the dashboard.

What the chat client gives you

The OpenTelemetry chat client is the easiest part of the setup.
It sits in the IChatClient pipeline and observes calls made through that client.

On a normal agent run, it can record model metadata such as:

operation name
requested model
response model
provider name
server address
streaming flag
finish reason
response id
input token count
output token count
cached input token count, when available
reasoning output token count, when available
operation duration
time to first streamed chunk
time between streamed chunks

With that alone, you can answer the first set of production questions.

For example:

Why did this request take 34 seconds?
-> The first model call took 1.4 seconds.
-> The search tool took 29 seconds.
-> The final model call took 2.1 seconds.

Why did this request cost more than usual?
-> The input token count jumped after retrieval.
-> The agent included eight document chunks instead of two.
-> The route used a larger model than the normal path.

Why did streaming feel broken?
-> The model call started quickly.
-> Time to first chunk was 18 seconds.
-> The delay is provider-side or prompt-side, not frontend rendering.

A trace turns "the agent was slow" into something you can actually fix.

Token usage is an operational signal

Token usage is billing data, but it is also behavior data.

High input tokens can mean:

the chat reducer is not running
retrieval returned too much context
the agent is carrying stale state
the frontend is resending too much history
tool results are too verbose
an inner agent is dumping its full conversation into the outer agent

High output tokens can mean:

the agent is overexplaining
the instructions are too broad
structured output is not constrained
the model is stuck in a repair loop
the user asked for a large artifact

The OpenTelemetry middleware records token usage when the provider returns usage information.
You can also inspect usage directly from responses when you need a local guardrail:

AgentResponse response = await agent.RunAsync(
    "Check release-2026-07-08 and tell me whether it is ready.",
    session,
    cancellationToken: cancellationToken);

if (response.Usage is { } usage)
{
    logger.LogInformation(
        "Agent run used {InputTokens} input tokens and {OutputTokens} output tokens.",
        usage.InputTokenCount,
        usage.OutputTokenCount);
}

I would not turn that into the main production telemetry path.
Use OpenTelemetry for durable traces and metrics.
Use direct response usage checks for local assertions, tests, or immediate guardrails.

For example, an integration test can fail when a supposedly small route starts consuming a huge prompt:

response.Usage?.InputTokenCount.Should().BeLessThan(8_000);

That catches prompt and retrieval regressions before they turn into a cloud bill.

Tool calls need their own spans

Model telemetry is not enough.
Many agent failures happen outside the model:

a search index is slow
an MCP server is down
a deployment API rejects a change ticket
a database query times out
a tool result is too large
approval is granted but execution fails

If your tool is just normal C#, instrument it like normal C#.

using System.Diagnostics;
using Microsoft.Extensions.DependencyInjection;

public static class AgentTelemetry
{
    public static readonly ActivitySource ActivitySource =
        new("DeploymentAgent");
}

public static async Task<DeploymentStatus> CheckStagingStatusAsync(
    string releaseId,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    using Activity? activity = AgentTelemetry.ActivitySource.StartActivity(
        "tool deployment.check_staging",
        ActivityKind.Internal);

    activity?.SetTag("agent.name", "deployment-agent");
    activity?.SetTag("ai.tool.name", "CheckStagingStatusAsync");
    activity?.SetTag("ai.tool.risk", "read_only");
    activity?.SetTag("deployment.environment", "staging");

    var deployments = services.GetRequiredService<IDeploymentService>();

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

        activity?.SetTag("deployment.status", status.State);
        activity?.SetStatus(ActivityStatusCode.Ok);

        return status;
    }
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
        activity?.AddException(ex);
        throw;
    }
}

Then collect the tool source:

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing
            .AddSource(builder.Environment.ApplicationName)
            .AddSource("DeploymentAgent")
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation();
    });

Use low-cardinality tags for dashboards.
For example, deployment.environment=production is fine.
Raw releaseId, user messages, customer names, email addresses, and ticket descriptions need more care.

When you need correlation without raw values, log a stable hash or an internal id that your support process can resolve under access control.

Approval telemetry is separate from tool telemetry

In the human-in-the-loop article, the rule was:

The model requests the action.
The application decides whether the action continues.

Telemetry should preserve that split.

The approval request, human decision, and eventual tool execution are related, but they are not the same event.

I usually want these approval fields:

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

An approval log might look like this:

logger.LogInformation(
    "Agent tool approval decided. ApprovalId={ApprovalId} ToolName={ToolName} Decision={Decision} TraceId={TraceId}",
    approval.Id,
    approval.ToolName,
    decision.Approved ? "approved" : "rejected",
    Activity.Current?.TraceId.ToString());

Do not log full tool arguments by default.
For production, I usually prefer:

logger.LogInformation(
    "Approval request created. ApprovalId={ApprovalId} ToolName={ToolName} ArgumentsHash={ArgumentsHash}",
    approval.Id,
    approval.ToolName,
    argumentsHash);

The user interface can show exact arguments at approval time.
That does not mean the telemetry backend should keep those arguments forever.

Sensitive data is a feature flag, not a casual toggle

The OpenTelemetry chat client has an EnableSensitiveData setting.
There is also an environment variable:

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

When enabled, telemetry can include raw inputs and outputs such as:

system instructions
user messages
assistant messages
tool definitions
tool call arguments
tool call results
additional request and response properties

This helps during local debugging.
It can also become a data-retention problem in production.

I would treat it as an explicit environment policy:

.UseOpenTelemetry(
    sourceName: builder.Environment.ApplicationName,
    configure: telemetry =>
    {
        telemetry.EnableSensitiveData =
            builder.Environment.IsDevelopment()
            && builder.Configuration.GetValue<bool>(
                "AI:Telemetry:EnableSensitiveData");
    })

Make the configuration explicit:

{
  "AI": {
    "Telemetry": {
      "EnableSensitiveData": false
    }
  }
}

For production, decide this with security, privacy, and compliance input.
If you enable prompt capture, also decide:

which environments may capture it
who can query it
how long it is retained
whether sampling applies
which fields are redacted before export
whether customer data can cross region or tenant boundaries
whether tool results include secrets or confidential documents

The default should be metadata only.
Turn on content capture only when the debugging value justifies the data risk.

Redact before export when possible

OpenTelemetry processors can modify telemetry before it leaves the process.
For agent systems, this matters because sensitive content often appears in attributes, logs, or exception messages.

A minimal custom processor can remove known high-risk attributes:

using System.Diagnostics;
using OpenTelemetry;

public sealed class AgentRedactionProcessor : BaseProcessor<Activity>
{
    private static readonly HashSet<string> SensitiveTags =
    [
        "gen_ai.input.messages",
        "gen_ai.output.messages",
        "gen_ai.system.instructions",
        "gen_ai.tool.definitions"
    ];

    public override void OnEnd(Activity activity)
    {
        foreach (string tagName in SensitiveTags)
        {
            activity.SetTag(tagName, null);
        }
    }
}

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing
            .AddSource(builder.Environment.ApplicationName)
            .AddProcessor(new AgentRedactionProcessor())
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation();
    });

This is just a sketch.
Real redaction usually needs to happen earlier, closer to the application boundary.
I prefer this order:

avoid collecting raw data
-> redact known sensitive fields
-> sample high-volume telemetry
-> restrict access in the telemetry backend
-> set retention intentionally

Do not rely on one processor as your entire privacy story.

Local debugging with Aspire

Aspire is a good local loop for agent observability.

With an AppHost and service defaults, you can run the agent backend locally and inspect:

resources
environment variables
logs
traces
metrics
outbound HTTP calls
failed dependencies
model-call spans
tool-call spans, if you added them

What I like about this setup is that the local flow uses OTLP.
Your app emits OpenTelemetry data.
The Aspire dashboard receives it.
You can inspect the same telemetry before sending it to Azure Monitor.

A minimal AppHost might look like this:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.DeploymentAgent_Api>("deployment-agent-api")
    .WithEnvironment("AI__Telemetry__EnableSensitiveData", "true");

builder.Build().Run();

Then run the AppHost:

dotnet run --project src/DeploymentAgent.AppHost

In the dashboard, inspect one request end to end:

POST /chat
-> deployment-agent model call
-> CheckStagingStatusAsync tool span
-> deployment API HTTP dependency
-> deployment-agent model call
-> approval request log

This is what I want to see locally.
If you only see ASP.NET Core request spans, the app is observable as a web API but not yet observable as an agent.

If spans are missing, check the boring parts first:

UseOpenTelemetry is in the IChatClient pipeline before creating the agent.
sourceName matches an AddSource(...) entry.
The chat client's meter name is added with AddMeter(...) if you want token metrics.
Custom tool ActivitySource names are added with AddSource(...).
OTEL_EXPORTER_OTLP_ENDPOINT is set by Aspire or by your local environment.
The provider actually returns usage information if token counts are missing.

Also remember that the Aspire dashboard can display sensitive configuration and telemetry.
If you enable prompt capture locally, treat the dashboard as sensitive too.

Cloud monitoring with Application Insights

For Azure Monitor and Application Insights, the usual .NET path is the Azure Monitor OpenTelemetry distro.
For ASP.NET Core applications, install:

dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

Then enable Azure Monitor export:

using Azure.Monitor.OpenTelemetry.AspNetCore;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();

if (!string.IsNullOrWhiteSpace(
        builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]))
{
    builder.Services.AddOpenTelemetry()
        .UseAzureMonitor();
}

In production, set the connection string through configuration, not as a hard-coded value:

APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...;IngestionEndpoint=...

The Aspire service defaults template already includes a commented Azure Monitor exporter section.
I usually wire it there so the same service defaults project controls local OTLP export and cloud export.

Once telemetry reaches Application Insights, you can use the normal views:

Application map
Transaction search
End-to-end transaction details
Failures
Performance
Logs
Metrics
Workbooks
Alerts

In a workspace-based Application Insights setup, the underlying trace and log data is queryable in the connected Log Analytics workspace.
That is where the KQL queries for custom dashboards, incident review, and agent-specific investigations usually live.

For AI systems, Application Insights also has an Agents view.
It is built around OpenTelemetry Generative AI semantics and is meant to help inspect agent runs, model usage, tool calls, errors, token usage, and cost-related behavior.

Still, keep normal application telemetry.
Agent observability should sit beside request, dependency, database, queue, cache, and runtime telemetry.
The agent is part of the application, not a separate universe.

What to alert on

Start with boring alerts.

For agents, I would usually begin with:

model call failure rate
tool call failure rate
high run duration
high model duration
high tool duration
high input token count
high output token count
repeated max-iteration exits
approval rejection spike
approval timeout spike
missing telemetry from an expected agent service

Avoid alerting on every weird model response.
That belongs in evaluation and product analytics more than infrastructure alerting.

I split it this way:

Concern	Better tool
Service is down	Application Insights alert
Model calls are failing	Application Insights alert
Tool latency is high	Application Insights alert
Token usage suddenly doubled	Metric alert or workbook
Answer quality regressed	Evaluation pipeline
Agent chose a poor plan	Trace review plus evaluation
User disliked the answer	Product analytics plus evaluation

For token spikes, tie the alert back to the meter you configured earlier with AddMeter(...).
If the OpenTelemetry pipeline exports the chat client token metrics to Azure Monitor, you can use Azure Monitor metric alerts for the fast signal and a workbook or KQL query for the investigation view.

Observability tells you what happened.
Evaluation tells you whether the behavior was good.
You need both.

Production checklist

For a production agent, I would want this before launch:

Every service has service.name or an equivalent cloud role name.
The agent has a stable name.
UseOpenTelemetry is configured on the chat client.
The chat client source is collected by tracing.
The chat client meter is collected by metrics.
Tool spans exist for important application tools.
Tool spans include low-cardinality tags such as tool name, risk, and result class.
Approval decisions are logged with correlation ids.
Raw prompt and tool content capture is disabled by default.
Any enabled content capture has a documented retention and access policy.
The Aspire dashboard shows a full local agent run.
Application Insights receives traces, metrics, and logs in the target environment.
A failed tool call can be found from a trace id.
A high-token request can be found and explained.
Alerts exist for failure rate, latency, and missing telemetry.

A decent first version is small:

UseOpenTelemetry on the chat client
AddSource and AddMeter for the AI source
custom spans around important tools
metadata-only telemetry by default
Aspire locally
Application Insights in Azure

This is enough to stop saying "the agent acted weird" and start looking at the actual execution path.

When I would use this

I would add this setup when:

the agent calls real tools
the agent runs in a web API or worker service
token cost matters
support needs to debug user incidents
approval flows need auditability
the agent has multiple model calls per request
retrieval or tool latency affects user experience
the system is moving from demo to production

The earlier you add it, the easier it is.
Retrofitting observability after a production incident usually means you first have to guess where the system is opaque.

When I would not start here

I would not start with full production telemetry when:

the agent is still a throwaway prototype
prompts contain data you are not allowed to store
no one has decided telemetry retention and access rules
the team has no baseline for normal token usage
the agent has no stable tool boundaries yet
the main problem is answer quality, not runtime behavior

In those cases, start smaller.
Log request ids, model names, token usage, and tool names locally.
Use Aspire for development.
Add cloud export once the boundaries are stable enough to monitor intentionally.

Conclusion

Agent observability is more than "turn on logs".
You need traces for the execution path, metrics for volume and cost, logs for decisions, and a clear policy for sensitive data.

For .NET agents, I usually start here:

Microsoft.Extensions.AI UseOpenTelemetry
-> Agent Framework agent
-> Aspire dashboard locally
-> Application Insights in Azure

Then fill the gaps that the model-call telemetry cannot know about:

custom tool spans
approval logs
application-specific correlation ids
redaction and retention rules
alerts that match real operational failure modes

Do not store every thought-like artifact an agent produces.
Store enough evidence to explain failures, cost, latency, and side effects without guessing.

The follow-up article moves from observing agent behavior to testing it.
I will look at how to test Microsoft Agent Framework applications without treating the model as an untestable black box: fake model clients, tool contract tests, structured output tests, routing tests, workflow tests, and eval-style regression checks.

Run Python in-process from .NET with CSnakes

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

So I definitely don't do everything using C# and .NET. I also use Python, but sometimes I just do not want another tiny Python service.

I want one Python library inside an otherwise normal .NET app. No container boundary. No HTTP wrapper. No extra deployment for something that is really just a function call.

CSnakes is interesting for that case. It runs Python in the same process and generates C# bindings from typed Python functions. The Python code stays in Python, but the .NET side can call it through a normal-looking method.

That makes it a good fit for quick demos, proofs of concept, internal tools, or the one feature where Python has exactly the library you need.

The shape

Install the packages:

dotnet add package CSnakes.Runtime
dotnet add package Microsoft.Extensions.Hosting

The project file shape is still small. Add the package references and include your Python files as analyzer additional files. That is how the source generator finds them:

<ItemGroup>
  <PackageReference Include="CSnakes.Runtime" Version="1.2.1" />
  <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.9" />
</ItemGroup>

<ItemGroup>
  <AdditionalFiles Include="python/*.py" SourceItemType="Python">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </AdditionalFiles>
  <None Include="requirements.txt" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Then wire up Python at startup:

using CSnakes.Runtime;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
var pythonHome = Path.Join(AppContext.BaseDirectory, "python");

builder.Services
    .WithPython()
    .WithHome(pythonHome)
    .FromRedistributable();

var app = builder.Build();
var env = app.Services.GetRequiredService<IPythonEnvironment>();

FromRedistributable() can download and use an isolated Python runtime. If your environment already standardizes on Conda or system Python, CSnakes can use those too.

A small example

Imagine a .NET app that needs one fuzzy matching function from Python. That is small enough that a separate API would feel silly.

Add a Python dependency in requirements.txt:

rapidfuzz

For a real app, pin the package version. Treat it like any other dependency you care about.

We can update our startup code to use CSnakes' uv integration to handle this automatically:

var requirements = Path.Join(AppContext.BaseDirectory, "requirements.txt");

builder.Services
    .WithPython()
    .WithHome(pythonHome)
    .FromRedistributable()
    .WithVirtualEnvironment(Path.Join(AppContext.BaseDirectory, ".venv"))
    .WithUvInstaller(requirements);

The first run may need network access because CSnakes can download the redistributable Python runtime and uv installs the packages from requirements.txt.

Now add python/text_tools.py:

from rapidfuzz import fuzz

def match_score(left: str, right: str) -> float:
    return float(fuzz.token_set_ratio(left, right))

Because the function has type hints, CSnakes can generate a typed C# wrapper. Python's match_score shows up as MatchScore in C#.

var textTools = env.TextTools();

var score = textTools.MatchScore(
    "Azure OpenAI invoice processing",
    "invoice processing with Azure AI");

Console.WriteLine(score);

The .NET code does not shell out to python. It also does not serialize an HTTP request just to call one local function.

What to keep in mind

Keep the Python boundary boring.

I would expose a few typed functions like match_score, extract_features, or rank_candidates. I would not let half the domain model move into Python because it was convenient in the moment.

Also remember that this is in-process. That is the point, but it changes the failure model. A Python dependency problem is now your application startup problem. A heavy Python call can affect your .NET process. The Python environment needs the same care as the rest of your runtime.

Deployment is the other boundary to check early. CSnakes can work with Native AOT when you use the source-generated bindings shown above, but not every interop path is AOT friendly. Manual Python binding still runs into the usual AOT limits around reflection and dynamic type handling. A self-contained .NET publish also does not magically include Python, your packages, or the .venv directory. Those still need to be bundled with the app.

When to use it

I would reach for CSnakes when:

the .NET app only needs a small slice of Python
HTTP would add more ceremony than value
the Python function has clear typed inputs and outputs
the integration belongs inside the app, not beside it

I would still use a separate Python service when the Python side has its own scaling needs, GPU runtime, deployment lifecycle, or team ownership. In-process interop is useful, but it is not a replacement for a real service boundary when you actually need one.

Agent Frontends with AG-UI: Streaming, Tool Calls and Human Approval

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

This is Part 16 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 human-in-the-loop agents.
The main point was that approval is a system boundary.
The model can request an action, but the application must decide whether that action is allowed to run.

That immediately creates a frontend problem.

A real agent UI cannot only show a chat transcript.
It also has to show:

streamed text while the agent is still answering
tool calls before and after execution
long-running tool progress
approval requests with exact arguments
state updates that change the visible application
errors, retries, cancellations, and run status

AG-UI exists for this layer.
It gives agent backends and frontends a protocol for exposing agent behavior as events instead of forcing everything through plain assistant text.

A simple rule is:

Use chat for language. Use events for agent behavior.

Plain chat is the wrong frontend boundary

A text-only chat box is fine for a simple assistant.
The user sends a message.
The assistant streams a response.
The interaction ends.

That model breaks down once the agent can do real application work.

Imagine a deployment assistant:

User: Deploy release-2026-06-24 to production using CHG-1042.

The frontend should not wait silently until the final answer arrives.
It should be able to show:

Run started
Checking staging status...
Tool call: CheckStagingStatusAsync(release-2026-06-24)
Tool result: staging healthy
Approval required: DeployToProductionAsync(...)
User approved
Deploying...
Deployment complete
Run finished

Those are not all assistant messages.
Some are lifecycle events.
Some are tool events.
Some are approval requests.
Some are state changes.

If you flatten all of that into text, the frontend loses structure.
It cannot reliably render progress, approval forms, state panels, or tool-specific UI.
It has to parse generated prose, which is exactly the kind of boundary we have avoided throughout this series.

What AG-UI adds

AG-UI is a protocol for agent user interfaces.
In Agent Framework, the integration connects an agent backend to web clients over HTTP with Server-Sent Events.

The useful part is not only "streaming text".
We already had RunStreamingAsync for that.

The useful part is that the stream can carry richer agent events:

run lifecycle
text message chunks
tool calls
tool results
approval requests
state snapshots
state deltas
errors

That gives the frontend enough structure to render the agent as an application workflow instead of a typing indicator with a text box.

The Agent Framework AG-UI documentation currently describes support for several protocol features, including agentic chat, backend tool rendering, human-in-the-loop approval, generative UI, shared state, and predictive state updates.
The protocol is still evolving, so treat implementation details as something to verify against the current package version before shipping.

The backend shape in .NET

For a .NET application, the basic backend shape is an ASP.NET Core endpoint.

Install the AG-UI hosting package:

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease

Then expose an Agent Framework agent through MapAGUI.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.Extensions.AI;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddAGUI();

AzureOpenAIClient azureClient = new(
    new Uri(builder.Configuration["AZURE_OPENAI_ENDPOINT"]!),
    new DefaultAzureCredential());

IChatClient chatClient = azureClient.AsChatClient("gpt-5-mini");

AIAgent agent = chatClient.AsAIAgent(
    name: "deployment-agent",
    instructions: """
    You help operators inspect deployment state and prepare safe release actions.
    Explain tool usage clearly.
    Ask for approval before risky actions.
    """);

WebApplication app = builder.Build();

app.MapAGUI("/", agent);

await app.RunAsync();

AddAGUI registers the AG-UI services.
MapAGUI exposes the agent through an HTTP endpoint and streams responses using Server-Sent Events.

That endpoint is now the frontend boundary.
The browser does not need to know the provider SDK.
It talks to an AG-UI endpoint.

Conceptually:

React or web client
-> HTTP POST with messages
-> ASP.NET Core MapAGUI endpoint
-> Agent Framework agent
-> model, tools, approvals, state
-> Server-Sent Events back to the client

A .NET client can consume it as an agent

Agent Framework also has an AG-UI client package:

dotnet add package Microsoft.Agents.AI.AGUI --prerelease
dotnet add package Microsoft.Agents.AI --prerelease

The client side can create an AGUIChatClient, convert it to an agent, and consume streaming updates.

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

string serverUrl =
    Environment.GetEnvironmentVariable("AGUI_SERVER_URL")
    ?? "http://localhost:8888";

using HttpClient httpClient = new();

AGUIChatClient aguiClient = new(httpClient, serverUrl);

AIAgent remoteAgent = aguiClient.AsAIAgent(
    name: "agui-client",
    description: "Client-side proxy for the AG-UI agent endpoint.");

AgentSession session = await remoteAgent.CreateSessionAsync();

List<ChatMessage> messages =
[
    new(ChatRole.User, "Check release-2026-06-24 and tell me whether it is ready.")
];

await foreach (AgentResponseUpdate update in remoteAgent.RunStreamingAsync(
                   messages,
                   session))
{
    foreach (AIContent content in update.Contents)
    {
        if (content is TextContent text)
        {
            Console.Write(text.Text);
        }
    }
}

This is useful for console demos or service-to-service tests.
For a real web frontend, you might use a React client such as CopilotKit or your own AG-UI event consumer.

The important design point is the same either way:

Do not treat the endpoint as "an API that returns a string".
It is an event stream.

Stream text, but do not stop there

Streaming text is the minimum viable agent frontend feature.

It solves the waiting problem.
The user sees output while the model is still generating.

But once tools are involved, text streaming alone is not enough.
The frontend also needs to understand the run lifecycle.

At minimum, keep separate UI state for:

public enum AgentRunStatus
{
    Idle,
    Running,
    WaitingForApproval,
    RunningTool,
    Completed,
    Failed,
    Cancelled
}

Then update it from events rather than from generated text.

For example:

public sealed record AgentRunViewModel
{
    public AgentRunStatus Status { get; init; }
    public string? ConversationId { get; init; }
    public string? RunId { get; init; }
    public string AssistantText { get; init; } = string.Empty;
    public List<ToolCallViewModel> ToolCalls { get; init; } = [];
    public ApprovalRequestViewModel? PendingApproval { get; init; }
}

That separation matters.

The assistant text is content.
The run status is application state.
Tool calls are structured events.
Approvals are interactive decisions.

If everything is appended to one markdown string, the frontend cannot behave like a product UI.

Show backend tool progress

In AG-UI backend tool rendering, tools are defined and executed on the server.
The frontend receives tool call and tool result updates.

That is a good fit for actions that belong inside your application boundary:

search internal docs
check deployment status
calculate a quote
query inventory
create a support ticket
call an authorized backend service

A simple server-side tool looks like this:

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

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

    return deployments.CheckStatusAsync(
        releaseId,
        cancellationToken);
}

AITool[] tools =
[
    AIFunctionFactory.Create(CheckDeploymentStatusAsync)
];

AIAgent agent = chatClient.AsAIAgent(
    name: "deployment-agent",
    instructions: "Use tools when deployment state is needed.",
    tools: tools,
    services: app.Services);

app.MapAGUI("/", agent);

On the client side, handle tool call and tool result content separately from text.

await foreach (AgentResponseUpdate update in remoteAgent.RunStreamingAsync(
                   messages,
                   session,
                   cancellationToken: cancellationToken))
{
    foreach (AIContent content in update.Contents)
    {
        switch (content)
        {
            case TextContent text:
                AppendAssistantText(text.Text);
                break;

            case FunctionCallContent call:
                MarkToolStarted(
                    call.CallId,
                    call.Name,
                    call.Arguments);
                break;

            case FunctionResultContent result:
                MarkToolFinished(
                    result.CallId,
                    result.Result,
                    result.Exception);
                break;
        }
    }
}

The actual UI can then show tool progress in a side panel, status bar, timeline, or inline expandable detail.

The point is not to expose every internal detail to the user.
The point is to make the system understandable.

Good frontend text might be:

Checking staging deployment status...

Bad frontend text is:

The model is thinking.

The first tells the user what the system is doing.
The second tells them nothing operationally useful.

Backend tools and frontend tools are different

AG-UI can also support frontend tools.

A frontend tool is registered on the client and executes in the client environment.
The server can see the tool declaration and request the call, but the implementation runs on the client.

That is useful for client-local capabilities:

read browser-local preferences
access device location after user permission
inspect UI selection
copy something to clipboard
trigger a client-side view change
read state that only exists in the frontend

For example:

[Description("Gets the user's current client-side location after permission.")]
public static Task<string> GetUserLocationAsync(
    CancellationToken cancellationToken)
{
    // In a real frontend, this would call browser or device APIs.
    return Task.FromResult("Berlin, Germany");
}

AITool[] frontendTools =
[
    AIFunctionFactory.Create(GetUserLocationAsync)
];

AIAgent remoteAgent = aguiClient.AsAIAgent(
    name: "agui-client",
    description: "AG-UI client with frontend tools.",
    tools: frontendTools);

The server receives the frontend tool schema.
The model can request the tool.
The client executes it and returns the result.

Do not use frontend tools for privileged operations.

If the action changes server data, spends money, changes permissions, or calls internal systems, make it a backend tool with normal authentication, authorization, validation, and audit logging.

Frontend tools are for client capabilities.
Backend tools are for application capabilities.

Approval requests need real UI

The previous article covered ApprovalRequiredAIFunction on the backend.
AG-UI brings that approval request across the frontend boundary.

In the .NET pattern documented for Agent Framework, approval-required tools use ApprovalRequiredAIFunction.
Middleware converts FunctionApprovalRequestContent into an AG-UI client tool call, commonly named request_approval.
The client renders an approval UI and sends the decision back as a tool result.
Middleware then converts that response back into FunctionApprovalResponseContent so the agent can continue.

Conceptually:

agent requests risky function
-> FunctionApprovalRequestContent
-> AG-UI client tool call: request_approval
-> frontend shows approval UI
-> user approves or rejects
-> frontend returns tool result
-> FunctionApprovalResponseContent
-> agent continues

The frontend must show the actual operation.
Not just the model's explanation.

For a deployment approval, show:

Tool: DeployToProductionAsync
Release: release-2026-06-24
Environment: production
Change ticket: CHG-1042
Requested by: lukas@example.com
Expires: 2026-06-24 15:30 UTC

A view model might look like this:

public sealed record ApprovalRequestViewModel
{
    public required string ApprovalId { get; init; }
    public required string FunctionName { get; init; }
    public required IReadOnlyDictionary<string, object?> Arguments { get; init; }
    public required string RequestedBy { get; init; }
    public DateTimeOffset ExpiresAt { get; init; }
    public string? AgentExplanation { get; init; }
}

The frontend should not approve vague text such as:

The agent wants to proceed.

It should approve a specific function call with specific arguments.

This is where AG-UI matters.
Approval becomes an interactive event in the frontend, not a paragraph in the chat.

State updates are separate from messages

Some agent applications are not only conversations.
They have visible application state.

Examples:

a trip plan
a deployment checklist
a draft support reply
a generated recipe
a remediation plan
a document outline
a shopping cart

The agent may update that state while it works.

AG-UI state management exists so the client and server can keep a synchronized view of application state.
The Agent Framework docs describe state snapshots, bidirectional state synchronization, and predictive state updates.

For a deployment frontend, state might be:

public sealed class DeploymentReviewState
{
    public string ReleaseId { get; set; } = string.Empty;
    public string Environment { get; set; } = "production";
    public string CurrentStage { get; set; } = "not-started";
    public List<DeploymentCheck> Checks { get; set; } = [];
    public bool RequiresApproval { get; set; }
}

public sealed class DeploymentCheck
{
    public string Name { get; set; } = string.Empty;
    public string Status { get; set; } = "pending";
    public string? Details { get; set; }
}

Then the UI can render a real checklist instead of hoping the model produces a readable markdown list every time.

AG-UI state events let the frontend receive updates as structured data.
The exact implementation depends on the client stack and package version.
In the current .NET docs, one C# pattern emits DataContent with application/json; the AG-UI hosting layer converts that into state snapshot events.

Conceptually:

agent or middleware produces structured state
-> JSON state snapshot
-> AG-UI state event
-> frontend replaces or patches local state
-> UI rerenders structured panels

The key rule is:

Do not make the frontend parse state out of assistant text.

If the agent updates a checklist, send a checklist object.
If it updates a plan, send a plan object.
If it updates approval state, send approval state.

Predictive state updates need discipline

Predictive state updates are attractive because the frontend can update while the model is still generating tool arguments.
That can make generative UI feel much faster.

But optimistic state is still speculative.

The model may change its arguments while streaming.
The user may reject the approval.
The tool may fail validation.
The final backend state may differ from the predicted state.

So treat predictive updates as provisional.

For example:

public enum StateConfidence
{
    Predicted,
    Confirmed,
    Rejected
}

public sealed record UiStateEnvelope<T>(
    T Value,
    StateConfidence Confidence,
    string? SourceRunId);

A good UI can show predicted state differently from confirmed state.
For example:

dim predicted checklist items
show "drafting..." on generated sections
require approval before applying risky state changes
rollback predicted changes if the tool call is rejected

This matters most when predictive state combines with human approval.

If the frontend shows a deployment plan while the model streams tool arguments, that does not mean the plan has been approved or executed.
The UI needs separate states:

predicted
pending approval
approved
executed
failed

Do not let optimistic UI blur the boundary between "the model proposed this" and "the system did this".

AG-UI does not replace product design

AG-UI gives you a protocol.
It does not decide what your product should show.

You still need to design the interaction.

For each agent feature, decide:

What should be visible to the user?
What should stay in developer traces?
Which tool calls deserve inline status?
Which tool calls should be hidden behind a simple progress label?
Which actions require approval?
Which state updates are provisional?
Which errors need user action?
Which errors should only be logged?

For a deployment assistant, I would show:

current run status
deployment checklist state
meaningful tool progress
approval request details
final result

I would not show:

every token event
every internal message
raw prompt text
secrets or internal identifiers the user is not allowed to see
model reasoning traces

The frontend is a boundary too.
It should expose useful system behavior without leaking internal implementation details.

A practical event handling shape

A frontend can treat the AG-UI stream as an event reducer.

The backend emits events.
The frontend reduces those events into UI state.

For example:

public sealed record AgentFrontendState
{
    public AgentRunStatus RunStatus { get; init; } = AgentRunStatus.Idle;
    public string AssistantText { get; init; } = string.Empty;
    public List<ToolCallViewModel> ToolCalls { get; init; } = [];
    public ApprovalRequestViewModel? PendingApproval { get; init; }
    public DeploymentReviewState? DeploymentState { get; init; }
    public string? ErrorMessage { get; init; }
}

Then each event updates one part of state.

public static AgentFrontendState Reduce(
    AgentFrontendState state,
    AIContent content)
{
    return content switch
    {
        TextContent text =>
            state with
            {
                AssistantText = state.AssistantText + text.Text
            },

        FunctionCallContent call =>
            state with
            {
                RunStatus = AgentRunStatus.RunningTool,
                ToolCalls = AddToolCall(state.ToolCalls, call)
            },

        FunctionResultContent result =>
            state with
            {
                ToolCalls = CompleteToolCall(state.ToolCalls, result)
            },

        FunctionApprovalRequestContent approval =>
            state with
            {
                RunStatus = AgentRunStatus.WaitingForApproval,
                PendingApproval = ToApprovalViewModel(approval)
            },

        DataContent data when data.MediaType == "application/json" =>
            state with
            {
                DeploymentState = ParseDeploymentState(data)
            },

        _ => state
    };
}

This example uses Agent Framework content types because it fits the .NET client surface.
A browser client may work with raw AG-UI protocol event names instead.
The design is the same:

Events update structured UI state.
Text is only one part of that state.

Cancellation belongs in the frontend contract

Agent frontends also need cancellation.

Users close tabs.
They navigate away.
They reject an approval.
They realize the prompt was wrong.

The frontend should be able to cancel the current run and the backend should pass cancellation through the model call and tool calls.

In .NET, keep the CancellationToken flowing:

await foreach (AgentResponseUpdate update in remoteAgent.RunStreamingAsync(
                   messages,
                   session,
                   cancellationToken: cancellationToken))
{
    Render(update);
}

For backend tools:

public static Task<DeploymentStatus> CheckDeploymentStatusAsync(
    string releaseId,
    IServiceProvider services,
    CancellationToken cancellationToken)
{
    var deployments = services.GetRequiredService<IDeploymentService>();
    return deployments.CheckStatusAsync(releaseId, cancellationToken);
}

If the browser disconnects from the SSE stream, the server should not blindly keep doing expensive work unless the product explicitly requires background continuation.

This is especially important with tools.
A cancelled text generation is one thing.
A cancelled deployment workflow is another.
Make the cancellation behavior explicit per operation.

When I would use AG-UI

Use AG-UI when:

the frontend needs streaming text
users should see tool progress
approval requests need real UI
agent state should update visible components
frontend tools need to run in the client
backend tools should expose progress and results
multiple clients should talk to the same agent endpoint shape
you want a protocol boundary instead of custom ad-hoc streaming JSON

This is especially useful when the agent is part of an application, not just a chat demo.

Examples:

deployment assistant with approval and checklist state
support copilot that drafts replies and creates tickets
document review UI with extracted findings and reviewer actions
planning assistant that updates a structured itinerary
operations assistant that streams tool status while querying systems

When I would not use AG-UI

Do not add AG-UI just because an agent exists.

It may be unnecessary when:

the application only needs a simple text response
there are no tools, approvals, or shared state
a normal backend endpoint already gives enough structure
the UI is internal and short-lived
you do not want to take a dependency on a still-evolving protocol
the frontend team cannot support event-driven state handling yet

For a background job, webhook processor, batch summarizer, or simple API endpoint, direct Agent Framework usage may be cleaner.

Use RunAsync or RunStreamingAsync directly when the frontend does not need the extra protocol semantics.

Conclusion

Agent frontends need more than a plain chat box once agents start doing application work.

Streaming text solves only one part of the experience.
The frontend also needs structured events for tool progress, approval requests, state updates, errors, cancellation, and run lifecycle.

AG-UI gives Agent Framework applications a protocol boundary for that.
On the backend, MapAGUI exposes an agent as an HTTP and SSE endpoint.
On the client, AG-UI events can become structured UI state instead of being flattened into assistant text.

The design I would carry forward is:

render text as text
render tool calls as tool progress
render approvals as approval forms
render state as structured UI
keep frontend tools separate from backend tools
treat predictive state as provisional
keep cancellation and errors explicit

That turns the frontend from a passive transcript into part of the agent system.

In the next post, I will move from frontend behavior to production visibility.
Once the UI can show streaming, tools, approvals, and state, the backend also needs traces that explain what happened across model calls, tool execution, AG-UI events, and user decisions.

Use file-based C# apps for small utilities

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

File-based C# apps are a good fit when you need a small utility, repro, quick demo, proof of concept, migration helper, or one-off CLI task, but creating a full project feels heavier than the actual code.

With the .NET 10 SDK, a single .cs file can be built and run directly. It is not the same thing as old C# scripting. The SDK still compiles your C# code. It just generates the project shape for you behind the scenes.

A small example

Create a file called cleanup.cs:

if (args.Length == 0)
{
    Console.Error.WriteLine("Usage: dotnet run cleanup.cs -- <path>");
    return 1;
}

var path = args[0];

if (!Directory.Exists(path))
{
    Console.Error.WriteLine($"Directory not found: {path}");
    return 1;
}

var files = Directory.GetFiles(path, "*.tmp", SearchOption.AllDirectories);

foreach (var file in files)
{
    Console.WriteLine(file);
}

Console.WriteLine($"Found {files.Length} temporary files.");
return 0;

Run it:

dotnet run --file cleanup.cs -- ./artifacts

The -- matters. Everything after it is passed to your app instead of being interpreted by dotnet run.

The shorter form also works when you are not in a project directory:

dotnet run cleanup.cs -- ./artifacts

I would still use --file in repo scripts. If a project file exists in the current working directory, dotnet run cleanup.cs can run the project and pass cleanup.cs as an application argument. The explicit form avoids that.

Add packages in the file

File-based apps support #: directives at the top of the file. For example, this adds a NuGet package:

#:package System.CommandLine@2.0.0

using System.CommandLine;

var pathArgument = new Argument<DirectoryInfo>("path")
{
    Description = "Directory to scan."
};

var root = new RootCommand("Find temporary files.");
root.Arguments.Add(pathArgument);

root.SetAction(parseResult =>
{
    var path = parseResult.GetValue(pathArgument);
    if (path is null || !path.Exists)
    {
        Console.Error.WriteLine("Directory not found.");
        return 1;
    }

    var files = path.GetFiles("*.tmp", SearchOption.AllDirectories);
    foreach (var file in files)
    {
        Console.WriteLine(file.FullName);
    }

    return 0;
});

return root.Parse(args).Invoke();

The point is not System.CommandLine. The point is that the dependency lives with the utility. Someone can copy one file, run one command, and still get a compiled C# app.

What the SDK does behind the scenes

When you run a file-based app, the SDK creates a temporary project and build output. Later runs can reuse cached build output when the inputs have not changed.

That makes the workflow feel script-like:

dotnet run cleanup.cs -- ./logs

But the execution model is still normal .NET:

the code is compiled
NuGet restore can happen
MSBuild properties can apply
packages come from configured NuGet sources
the app can be built, published, packed as a .NET tool, or converted to a project

That matters when a utility grows from "quick helper" into "shared internal tool". You are not stuck in a separate scripting model.

Convert it when it grows

If the file gets too large, convert it to a normal project:

dotnet project convert cleanup.cs

The command creates a project directory next to the original file, copies the C# file, and creates a .csproj with equivalent settings from the file-based app directives.

So you can start with one file and move to a project when you need tests, more files, or more explicit build configuration.

Preview note: multi-file apps

In the current preview tooling, file-based apps are no longer limited to exactly one source file.

The SDK supports #:include for adding more files:

#:include helpers.cs
#:include models/*.cs

The included .cs files become part of the compilation. They can contain types, methods, namespaces, and other declarations. They should not contain additional top-level statements.

.NET documents this for .NET 11 Preview 3 and .NET SDK 10.0.300 or later. I would treat it as a good fit for small helpers, not as a reason to avoid projects forever. Once the app starts looking like a real codebase, dotnet project convert is still the cleaner move.

Sources

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.

DEV Community: Lukas Walter

Testing Microsoft Agent Framework Applications

Do not start with the live model

Put the model behind IChatClient

Test the agent boundary

Tool tests have two different jobs

Test the function as normal application code

Test the generated AI contract

Test side effects separately from tool selection

Structured output needs shape tests and meaning tests

Test successful deserialization

Test business validation after deserialization

Routing tests should mostly be ordinary C# tests

Workflow tests should assert events and outputs

Test pauses and resumptions

Eval-style regression checks are a separate layer

What belongs in a regression gate?

Test the failure paths on purpose

The model fails

The model returns invalid structured output

The model requests the wrong tool

The tool fails

The agent loops

The user cancels

The context is too large

Keep test data inside the trust boundary

A practical test plan

When I would use this approach

When I would not overbuild it

Conclusion

Further reading

Generate Useful Test Data in .NET with Bogus

What Bogus does

Install Bogus

Start with a simple faker

Rules can depend on the object being generated

Compose related objects

Make generated data repeatable

Use custom constructors when necessary

Use locales when the scenario needs them

When Bogus is a good fit

When Bogus is not the right tool

A practical fixture shape

Benefits and tradeoffs

Conclusion

References

Observability for Agents with OpenTelemetry, Aspire, and Application Insights

Start with the questions

The basic OpenTelemetry setup

Add the AI source to Service Defaults

What the chat client gives you

Token usage is an operational signal

Tool calls need their own spans

Approval telemetry is separate from tool telemetry

Sensitive data is a feature flag, not a casual toggle

Redact before export when possible

Local debugging with Aspire

Cloud monitoring with Application Insights

What to alert on

Production checklist

When I would use this

When I would not start here

Conclusion

Further reading

Run Python in-process from .NET with CSnakes

The shape

A small example

What to keep in mind

When to use it

Further reading

Agent Frontends with AG-UI: Streaming, Tool Calls and Human Approval

Plain chat is the wrong frontend boundary

What AG-UI adds

The backend shape in .NET

A .NET client can consume it as an agent

Stream text, but do not stop there

Show backend tool progress

Backend tools and frontend tools are different

Approval requests need real UI

State updates are separate from messages

Put the model behind `IChatClient`

Change `Program.cs`

Add `host.json`

Copy `host.json` on publish