Produção de Resultados Estruturados com Agentes

Esta etapa do tutorial mostra como produzir saída estruturada com um agente, onde o agente é criado no serviço de Conclusão de Chat do Azure OpenAI.

Pré-requisitos

Para obter pré-requisitos e instalar pacotes NuGet, consulte a etapa Criar e executar um agente simples neste tutorial.

Defina um tipo para a saída estruturada

Primeiro, defina um tipo que represente a estrutura do output que pretende do agente.

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

Criar o agente

Crie um ChatClientAgent usando o Azure OpenAI Chat Client.

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

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");

Saída estruturada com RunAsync<T>

O RunAsync<T> método está disponível na AIAgent classe base. Aceita um parâmetro genérico de tipo que especifica o tipo de saída estruturado. Esta abordagem é aplicável quando o tipo de saída estruturada é conhecido em tempo de compilação e é necessária uma instância de resultado tipada. Suporta primitivas, arrays e tipos complexos.

AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");

Console.WriteLine($"Name: {response.Result.Name}, Age: {response.Result.Age}, Occupation: {response.Result.Occupation}");

Saída estruturada com ResponseFormat

A saída estruturada pode ser configurada definindo a propriedade ResponseFormat em AgentRunOptions no momento da invocação ou no momento da inicialização do agente para agentes que a suportam, como ChatClientAgent e o Foundry Agent.

Esta abordagem é aplicável quando:

• O tipo de saída estruturado não é conhecido em tempo de compilação.
• O esquema é representado como JSON bruto.
• A saída estruturada só pode ser configurada no momento da criação do agente.
• Apenas o texto JSON bruto é necessário sem desserialização.
• É utilizada colaboração entre agentes.

Existem várias opções de ResponseFormat disponíveis:

• Uma propriedade integrada ChatResponseFormat.Text: a resposta será texto sem formatação.
• Uma propriedade interna ChatResponseFormat.Json : A resposta será um objeto JSON sem nenhum esquema específico.
• Uma instância personalizada ChatResponseFormatJson : A resposta será um objeto JSON que está em conformidade com um esquema específico.

// Instead of using List<string> directly, create a wrapper type:
public class MovieListWrapper
{
    public List<string> Movies { get; set; }
}

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

AgentRunOptions runOptions = new()
{
    ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
};

AgentResponse response = await agent.RunAsync("Please provide information about John Smith, who is a 35-year-old software engineer.", options: runOptions);

PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text, JsonSerializerOptions.Web)!;

Console.WriteLine($"Name: {personInfo.Name}, Age: {personInfo.Age}, Occupation: {personInfo.Occupation}");

Também ResponseFormat pode ser especificado usando uma cadeia de esquema JSON bruta, o que é útil quando não existe um tipo .NET correspondente disponível, como para agentes declarativos ou esquemas carregados a partir de configurações externas:

string jsonSchema = """
{
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "age": { "type": "integer" },
        "occupation": { "type": "string" }
    },
    "required": ["name", "age", "occupation"]
}
""";

AgentRunOptions runOptions = new()
{
    ResponseFormat = ChatResponseFormat.ForJsonSchema(JsonElement.Parse(jsonSchema), "PersonInfo", "Information about a person")
};

AgentResponse response = await agent.RunAsync("Please provide information about John Smith, who is a 35-year-old software engineer.", options: runOptions);

JsonElement result = JsonSerializer.Deserialize<JsonElement>(response.Text);

Console.WriteLine($"Name: {result.GetProperty("name").GetString()}, Age: {result.GetProperty("age").GetInt32()}, Occupation: {result.GetProperty("occupation").GetString()}");

Saída estruturada com streaming

Durante o streaming, a resposta do agente é transmitida como uma série de atualizações, e você só pode desserializar a resposta depois que todas as atualizações forem recebidas. Você deve reunir todas as atualizações em uma única resposta antes de desserializá-la.

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

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new DefaultAzureCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(new ChatClientAgentOptions()
        {
            Name = "HelpfulAssistant",
            Instructions = "You are a helpful assistant.",
            ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
        });

> [!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.

IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");

AgentResponse response = await updates.ToAgentResponseAsync();

PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text)!;

Console.WriteLine($"Name: {personInfo.Name}, Age: {personInfo.Age}, Occupation: {personInfo.Occupation}");

Saída estruturada com agentes sem capacidades de saída estruturada

Alguns agentes não suportam nativamente saída estruturada, seja porque não faz parte do protocolo ou porque os agentes usam modelos de linguagem sem capacidades de saída estruturada. Uma abordagem possível é criar um agente decorador personalizado que envolva qualquer AIAgent e utilize uma chamada de LLM adicional através de um cliente de bate-papo para converter a resposta do agente em JSON estruturado.

Para uma implementação de referência deste padrão que possa adaptar aos seus próprios requisitos, consulte o exemplo StructuredOutputAgent.

Exemplo de streaming

Esta etapa do tutorial mostra como produzir saída estruturada com um agente, onde o agente é criado no serviço de Conclusão de Chat do Azure OpenAI.

Pré-requisitos

Para obter pré-requisitos e instalar pacotes, consulte a etapa Criar e executar um agente simples neste tutorial.

Criar o agente com saída estruturada

O Agent é construído sobre qualquer implementação de cliente de chat que suporta saída estruturada. O Agent usa o response_format parâmetro para especificar o esquema de saída desejado.

Ao criar ou executar o agente, você pode fornecer um modelo Pydantic que define a estrutura da saída esperada.

Vários formatos de resposta são suportados com base nos recursos subjacentes do cliente de chat.

Este exemplo cria um agente que produz saída estruturada na forma de um objeto JSON que está em conformidade com um esquema de modelo Pydantic.

Primeiro, defina um modelo Pydantic que represente a estrutura da saída que você deseja do agente:

from pydantic import BaseModel

class PersonInfo(BaseModel):
    """Information about a person."""
    name: str | None = None
    age: int | None = None
    occupation: str | None = None

Agora você pode criar um agente usando o Cliente de Chat do Azure OpenAI:

from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

# Create the agent using Azure OpenAI Chat Client
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
    name="HelpfulAssistant",
    instructions="You are a helpful assistant that extracts person information from text."
)

Agora você pode executar o agente com algumas informações textuais e especificar o formato de saída estruturado usando o response_format parâmetro:

response = await agent.run(
    "Please provide information about John Smith, who is a 35-year-old software engineer.",
    response_format=PersonInfo
)

A resposta do agente conterá a saída estruturada na propriedade value, que pode ser diretamente acessada como uma instância do modelo Pydantic.

if response.value:
    person_info = response.value
    print(f"Name: {person_info.name}, Age: {person_info.age}, Occupation: {person_info.occupation}")
else:
    print("No structured data found in response")

Ao transmitir, agent.run(..., stream=True) devolve um ResponseStream. O finalizador incorporado do stream trata automaticamente da análise sintática estruturada da saída, para que possas iterar para atualizações em tempo real e depois ligar get_final_response() para obter o resultado analisado:

# Stream updates in real time, then get the structured result
stream = agent.run(query, stream=True, options={"response_format": PersonInfo})
async for update in stream:
    print(update.text, end="", flush=True)

# get_final_response() returns the AgentResponse with the parsed value
final_response = await stream.get_final_response()

if final_response.value:
    person_info = final_response.value
    print(f"Name: {person_info.name}, Age: {person_info.age}, Occupation: {person_info.occupation}")

Se não precisares de processar atualizações individuais de streaming, podes saltar a iteração por completo — get_final_response() irá consumir automaticamente o stream:

stream = agent.run(query, stream=True, options={"response_format": PersonInfo})
final_response = await stream.get_final_response()

if final_response.value:
    person_info = final_response.value
    print(f"Name: {person_info.name}, Age: {person_info.age}, Occupation: {person_info.occupation}")

Exemplo completo

# Copyright (c) Microsoft. All rights reserved.

import asyncio

from agent_framework.openai import OpenAIResponsesClient
from pydantic import BaseModel

"""
OpenAI Responses Client with Structured Output Example

This sample demonstrates using structured output capabilities with OpenAI Responses Client,
showing Pydantic model integration for type-safe response parsing and data extraction.
"""


class OutputStruct(BaseModel):
    """A structured output for testing purposes."""

    city: str
    description: str


async def non_streaming_example() -> None:
    print("=== Non-streaming example ===")

    agent = OpenAIResponsesClient().as_agent(
        name="CityAgent",
        instructions="You are a helpful agent that describes cities in a structured format.",
    )

    query = "Tell me about Paris, France"
    print(f"User: {query}")

    result = await agent.run(query, options={"response_format": OutputStruct})

    if structured_data := result.value:
        print("Structured Output Agent:")
        print(f"City: {structured_data.city}")
        print(f"Description: {structured_data.description}")
    else:
        print(f"Failed to parse response: {result.text}")


async def streaming_example() -> None:
    print("=== Streaming example ===")

    agent = OpenAIResponsesClient().as_agent(
        name="CityAgent",
        instructions="You are a helpful agent that describes cities in a structured format.",
    )

    query = "Tell me about Tokyo, Japan"
    print(f"User: {query}")

    # Stream updates in real time using ResponseStream
    stream = agent.run(query, stream=True, options={"response_format": OutputStruct})
    async for update in stream:
        if update.text:
            print(update.text, end="", flush=True)
    print()

    # get_final_response() returns the AgentResponse with structured output parsed
    result = await stream.get_final_response()

    if structured_data := result.value:
        print("Structured Output (from streaming with ResponseStream):")
        print(f"City: {structured_data.city}")
        print(f"Description: {structured_data.description}")
    else:
        print(f"Failed to parse response: {result.text}")


async def main() -> None:
    print("=== OpenAI Responses Agent with Structured Output ===")

    await non_streaming_example()
    await streaming_example()


if __name__ == "__main__":
    asyncio.run(main())