Structured Output in .NET Agents

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

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

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

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

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

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

Raw LLM Text Is Hard to Automate

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

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

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

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

One response might look like this:

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

The next response might look like this:

### V60 Pour-Over

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

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

Define the Output Shape in C

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

For example:

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

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

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

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

Using `RunAsync<T>`

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

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

You can request a typed result:

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

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

BrewRecipeResult result = response.Result;

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

That means you can work with the result directly:

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

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

What the Framework Does for You

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

Conceptually, the flow looks like this:

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

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

Still, keep one thing in mind:

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

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

What Structured Output Does Not Solve

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

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

For example:

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

This object may be structurally valid.

It has the expected fields.
It can be deserialized.

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

Structured output can tell you:

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

It does not guarantee:

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

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

A more robust flow looks like this:

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

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

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

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

    double ratio = recipe.WaterGrams / recipe.CoffeeGrams;

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

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

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

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

Practical Example: Intent Routing

One useful pattern is intent routing.

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

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

or:

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

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

For example:

public enum AssistantIntent
{
    CoffeeBrewing,
    GuitarTone,
    Unknown
}

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

Then you can request a typed result:

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

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

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

        Supported intents:
        - CoffeeBrewing
        - GuitarTone
        - Unknown

        User request:
        {userMessage}
        """);

IntentResult intent = intentResponse.Result;

After that, your C# code stays simple:

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

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

The user is probably asking about guitar tone.

and then trying to parse that sentence.

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

For example:

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

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

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

Where Structured Output Fits

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

Common examples:

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

The pattern is always the same:

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

Conclusion

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

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

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

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

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

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

推荐订阅源

DEV Community

Raw LLM Text Is Hard to Automate

Define the Output Shape in C

Using `RunAsync<T>`

What the Framework Does for You

What Structured Output Does Not Solve

Practical Example: Intent Routing

Where Structured Output Fits

Conclusion

Further Reading

推荐订阅源

DEV Community

Raw LLM Text Is Hard to Automate

Define the Output Shape in C

Using RunAsync<T>

What the Framework Does for You

What Structured Output Does Not Solve

Practical Example: Intent Routing

Where Structured Output Fits

Conclusion

Further Reading

Using `RunAsync<T>`