structured-output

Producing Structured Output with Agents

::: zone pivot="programming-language-csharp"

This tutorial step shows you how to produce structured output with an agent, where the agent is built on the Azure OpenAI Chat Completion service.

[!IMPORTANT] Not all agent types support structured output. This step uses a ChatClientAgent, which does support structured output.

Prerequisites

For prerequisites and installing NuGet packages, see the Create and run a simple agent step in this tutorial.

Create the agent with structured output

The ChatClientAgent is built on top of any xref:Microsoft.Extensions.AI.IChatClient implementation. The ChatClientAgent uses the support for structured output that's provided by the underlying chat client.

When creating the agent, you have the option to provide the default xref:Microsoft.Extensions.AI.ChatOptions instance to use for the underlying chat client. This ChatOptions instance allows you to pick a preferred xref:Microsoft.Extensions.AI.ChatResponseFormat.

Various options for ResponseFormat are available:

• A built-in xref:Microsoft.Extensions.AI.ChatResponseFormat.Text?displayProperty=nameWithType property: The response will be plain text.
• A built-in xref:Microsoft.Extensions.AI.ChatResponseFormat.Json?displayProperty=nameWithType property: The response will be a JSON object without any particular schema.
• A custom xref:Microsoft.Extensions.AI.ChatResponseFormatJson instance: The response will be a JSON object that conforms to a specific schema.

This example creates an agent that produces structured output in the form of a JSON object that conforms to a specific schema.

The easiest way to produce the schema is to define a type that represents the structure of the output you want from the agent, and then use the AIJsonUtilities.CreateJsonSchema method to create a schema from the type.

using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.AI;

public class PersonInfo
{
    public string? Name { get; set; }
    public int? Age { get; set; }
    public string? Occupation { get; set; }
}

JsonElement schema = AIJsonUtilities.CreateJsonSchema(typeof(PersonInfo));