structured-outputs

Producing Structured Outputs with Agents

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

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

[!IMPORTANT] Not all agent types support structured outputs natively. The ChatClientAgent supports structured outputs when used with compatible chat clients.

Prerequisites

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

Define a type for structured outputs

First, define a type that represents the structure of the output you want from the agent.

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

Create the agent

Create a ChatClientAgent using the Azure AI Projects Client.

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "HelpfulAssistant",
            instructions: "You are a helpful assistant.");

[!WARNING] DefaultAzureCredential is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.

Structured outputs with RunAsync<T>

The RunAsync<T> method is available on the AIAgent base class. It accepts a generic type parameter that specifies the structured outputs type. This approach is applicable when the structured outputs type is known at compile time and a typed result instance is needed. It supports primitives, arrays, and complex types.