Compartilhar via

Produzindo saída estruturada com agentes

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

Importante

Nem todos os tipos de agente dão suporte à saída estruturada. Esta etapa usa um ChatClientAgent, que dá suporte à saída estruturada.

Pré-requisitos

Para pré-requisitos e instalação de pacotes NuGet, consulte a etapa Criar e executar um agente simples neste tutorial.

Criar o agente com saída estruturada

O ChatClientAgent é criado com base em qualquer implementação de IChatClient. O ChatClientAgent usa o suporte para a saída estruturada fornecida pelo cliente de chat subjacente.

Ao criar o agente, você tem a opção de fornecer a instância padrão ChatOptions a ser usada para o cliente de chat subjacente. Essa ChatOptions instância permite que você escolha uma ChatResponseFormat preferida.

Várias opções ResponseFormat estão disponíveis.

  • Uma propriedade interna 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.

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

A maneira mais fácil de produzir o esquema é definir um tipo que representa a estrutura da saída desejada do agente e, em seguida, usar o AIJsonUtilities.CreateJsonSchema método para criar um esquema do tipo.

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));

Em seguida, você pode criar uma ChatOptions instância que usa esse esquema para o formato de resposta.

using Microsoft.Extensions.AI;

ChatOptions chatOptions = new()
{
    ResponseFormat = ChatResponseFormat.ForJsonSchema(
        schema: schema,
        schemaName: "PersonInfo",
        schemaDescription: "Information about a person including their name, age, and occupation")
};

Essa ChatOptions instância pode ser usada ao criar o agente.

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

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 = chatOptions
        });

Aviso

DefaultAzureCredential é conveniente para o desenvolvimento, mas requer uma consideração cuidadosa na produção. Em produção, considere o uso de uma credencial específica (por exemplo, ManagedIdentityCredential) para evitar problemas de latência, investigação de credenciais não intencionais e possíveis riscos de segurança de mecanismos de fallback.

Agora você pode apenas executar o agente com algumas informações textuais que o agente pode usar para preencher a saída estruturada.

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

Em seguida, a resposta do agente pode ser desserializada na PersonInfo classe usando o Deserialize<T> método no objeto de resposta.

var personInfo = response.Deserialize<PersonInfo>(JsonSerializerOptions.Web);
Console.WriteLine($"Name: {personInfo.Name}, Age: {personInfo.Age}, Occupation: {personInfo.Occupation}");

Ao transmitir, 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 agrupar todas as atualizações em uma única resposta antes de desserializá-la.

var updates = agent.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");
personInfo = (await updates.ToAgentResponseAsync()).Deserialize<PersonInfo>(JsonSerializerOptions.Web);

Dica

Consulte os exemplos do .NET para obter exemplos executáveis completos.

Exemplo de streaming

Dica

Consulte os exemplos do .NET para obter exemplos executáveis completos.

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

Importante

Nem todos os tipos de agente dão suporte à saída estruturada. O Agent suporta a saída estruturada quando usado com clientes de chat compatíveis.

Pré-requisitos

Para pré-requisitos e instalação de pacotes, consulte a etapa Criar e executar um agente simples neste tutorial.

Criar o agente com saída estruturada

Ele Agent é construído sobre qualquer implementação de cliente de bate-papo que dê suporte à 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.

Há suporte para vários formatos de resposta com base nos recursos subjacentes do cliente de chat.

Este exemplo cria um agente que produz uma 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 desejada 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 acessada diretamente 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) retorna um ResponseStream. O finalizador interno do fluxo lida automaticamente com a análise de saída estruturada, para que você possa iterar para atualizações em tempo real e, em seguida, chamar 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 você não precisar processar atualizações de streaming individuais, poderá ignorar totalmente a iteração – get_final_response() consumirá automaticamente o fluxo:

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())

Próximas etapas

Respostas em segundo plano

  • Last updated on