Request a response with structured output

Article
2025-05-10

In this quickstart, you create a chat app that requests a response with structured output. A structured output response is a chat response that's of a type you specify instead of just plain text. The chat app you create in this quickstart analyzes sentiment of various product reviews, categorizing each review according to the values of a custom enumeration.

Note

The Microsoft.Extensions.AI library, which is used in this quickstart, is currently in Preview.

Prerequisites

.NET 8 or a later version
Visual Studio Code (optional)

Configure the AI service

To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the Create and deploy an Azure OpenAI Service resource article. In the "Deploy a model" step, select the gpt-4o model.

Create the chat app

Complete the following steps to create a console app that connects to the gpt-4o AI model.

In a terminal window, navigate to the directory where you want to create your app, and create a new console app with the dotnet new command:
```
dotnet new console -o SOChat
```

Navigate to the SOChat directory, and add the necessary packages to your app:

dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.AI --prerelease
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

Run the following commands to add app secrets for your Azure OpenAI endpoint, model name, and tenant ID:
```
dotnet user-secrets init
dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-azure-openai-endpoint>
dotnet user-secrets set AZURE_OPENAI_GPT_NAME gpt-4o
dotnet user-secrets set AZURE_TENANT_ID <your-tenant-id>
```
Note

Depending on your environment, the tenant ID might not be needed. In that case, remove it from the code that instantiates the DefaultAzureCredential.
Open the new app in your editor of choice.

Add the code

Define the enumeration that describes the different sentiments.

public enum Sentiment
{
    Positive,
    Negative,
    Neutral
}

Create the IChatClient that will communicate with the model.

IConfigurationRoot config = new ConfigurationBuilder()
    .AddUserSecrets<Program>()
    .Build();

string endpoint = config["AZURE_OPENAI_ENDPOINT"];
string model = config["AZURE_OPENAI_GPT_NAME"];
string tenantId = config["AZURE_TENANT_ID"];

// Get a chat client for the Azure OpenAI endpoint.
AzureOpenAIClient azureClient =
    new(
        new Uri(endpoint),
        new DefaultAzureCredential(new DefaultAzureCredentialOptions() { TenantId = tenantId }));
IChatClient chatClient = azureClient
    .GetChatClient(deploymentName: model)
    .AsIChatClient();

Note

DefaultAzureCredential searches for authentication credentials from your environment or local tooling. You'll need to assign the Azure AI Developer role to the account you used to sign in to Visual Studio or the Azure CLI. For more information, see Authenticate to Azure AI services with .NET.

Send a request to the model with a single product review, and then print the analyzed sentiment to the console. You declare the requested structured output type by passing it as the type argument to the ChatClientStructuredOutputExtensions.GetResponseAsync<T>(IChatClient, String, ChatOptions, Nullable<Boolean>, CancellationToken) extension method.
```
string review = "I'm happy with the product!";
var response = await chatClient.GetResponseAsync<Sentiment>($"What's the sentiment of this review? {review}");
Console.WriteLine($"Sentiment: {response.Result}");
```
This code produces output similar to:
```
Sentiment: Positive
```

Instead of just analyzing a single review, you can analyze a collection of reviews.

string[] inputs = [
    "Best purchase ever!",
    "Returned it immediately.",
    "Hello",
    "It works as advertised.",
    "The packaging was damaged but otherwise okay."
];

foreach (var i in inputs)
{
    var response2 = await chatClient.GetResponseAsync<Sentiment>($"What's the sentiment of this review? {i}");
    Console.WriteLine($"Review: {i} | Sentiment: {response2.Result}");
}

This code produces output similar to:

Review: Best purchase ever! | Sentiment: Positive
Review: Returned it immediately. | Sentiment: Negative
Review: Hello | Sentiment: Neutral
Review: It works as advertised. | Sentiment: Neutral
Review: The packaging was damaged but otherwise okay. | Sentiment: Neutral

And instead of requesting just the analyzed enumeration value, you can request the text response along with the analyzed value.

Define a record type to contain the text response and analyzed sentiment:

record SentimentRecord(string ResponseText, Sentiment ReviewSentiment);

Send the request using the record type as the type argument to GetResponseAsync<T>:

var review3 = "This product worked okay.";
var response3 = await chatClient.GetResponseAsync<SentimentRecord>($"What's the sentiment of this review? {review3}");

Console.WriteLine($"Response text: {response3.Result.ResponseText}");
Console.WriteLine($"Sentiment: {response3.Result.ReviewSentiment}");

This code produces output similar to:

Response text: Certainly, I have analyzed the sentiment of the review you provided.
Sentiment: Neutral

Clean up resources

If you no longer need them, delete the Azure OpenAI resource and GPT-4 model deployment.

In the Azure Portal, navigate to the Azure OpenAI resource.
Select the Azure OpenAI resource, and then select Delete.

Share via