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.

Criar o agente com saída estruturada

O ChatClientAgent é construído em cima de qualquer IChatClient implementação. O ChatClientAgent usa o suporte para saída estruturada que é fornecido 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. Esta ChatOptions instância permite-lhe escolher um ChatResponseFormat.

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.

Este exemplo cria um agente que produz 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 que você deseja do agente e, em seguida, usar o AIJsonUtilities.CreateJsonSchema método para criar um esquema a partir 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 AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .CreateAIAgent(new ChatClientAgentOptions()
        {
            Name = "HelpfulAssistant",
            Instructions = "You are a helpful assistant.",
            ChatOptions = chatOptions
        });

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

A resposta do agente pode então 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}");

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.

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

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 ChatAgent é construído sobre qualquer implementação de cliente de chat que suporta saída estruturada. O ChatAgent 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()).create_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")

Durante o streaming, a resposta do agente é transmitida como uma série de atualizações. Para obter a saída estruturada, você deve coletar todas as atualizações e, em seguida, acessar o valor de resposta final:

from agent_framework import AgentRunResponse

# Get structured response from streaming agent using AgentRunResponse.from_agent_response_generator
# This method collects all streaming updates and combines them into a single AgentRunResponse
final_response = await AgentRunResponse.from_agent_response_generator(
    agent.run_stream(query, response_format=PersonInfo),
    output_format_type=PersonInfo,
)

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