Generación de resultados estructurados con agentes

En este paso del tutorial se muestra cómo generar una salida estructurada con un agente, donde el agente se basa en el servicio de finalización de chat de Azure OpenAI.

Prerrequisitos

Para conocer los requisitos previos e instalar paquetes NuGet, consulte el paso Creación y ejecución de un agente sencillo en este tutorial.

Creación del agente con salida estructurada

ChatClientAgent se construye sobre cualquier implementación de IChatClient. ChatClientAgent utiliza el soporte para salida estructurada proporcionado por el cliente de chat subyacente.

Al crear el agente, tiene la opción de proporcionar la instancia predeterminada ChatOptions que se usará para el cliente de chat subyacente. Esta ChatOptions instancia le permite elegir una opción preferida ChatResponseFormat.

Hay disponibles varias opciones para ResponseFormat :

• Una propiedad integrada ChatResponseFormat.Text : la respuesta será texto sin formato.
• Una propiedad integrada ChatResponseFormat.Json : la respuesta será un objeto JSON sin ningún esquema determinado.
• Una instancia personalizada ChatResponseFormatJson : la respuesta será un objeto JSON que se ajuste a un esquema específico.

En este ejemplo se crea un agente que genera una salida estructurada en forma de un objeto JSON que se ajusta a un esquema específico.

La manera más fácil de generar el esquema es definir un tipo que represente la estructura de la salida que desee del agente y, a continuación, usar el AIJsonUtilities.CreateJsonSchema método para crear un esquema a partir del 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));

A continuación, puede crear una ChatOptions instancia que use este esquema para el formato de respuesta.

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

Esta ChatOptions instancia se puede usar al crear el 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
        });

Ahora puedes simplemente ejecutar el agente con información textual que el agente puede usar para rellenar la salida estructurada.

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

A continuación, la respuesta del agente se puede deserializar en la PersonInfo clase mediante el Deserialize<T> método en el objeto de respuesta.

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

Cuando se realiza una transmisión, la respuesta del agente se envía como una serie de actualizaciones, y solo se puede deserializar la respuesta una vez que se hayan recibido todas las actualizaciones. Debe ensamblar todas las actualizaciones en una única respuesta antes de deserializarla.

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

En este paso del tutorial se muestra cómo generar una salida estructurada con un agente, donde el agente se basa en el servicio de finalización de chat de Azure OpenAI.

Prerrequisitos

Para conocer los requisitos previos e instalar paquetes, consulte el paso Crear y ejecutar un agente sencillo en este tutorial.

Creación del agente con salida estructurada

ChatAgent se construye sobre cualquier implementación de cliente de chat que admita la salida estructurada. ChatAgent usa el response_format parámetro para especificar el esquema de salida deseado.

Al crear o ejecutar el agente, puede proporcionar un modelo Pydantic que defina la estructura de la salida esperada.

Se admiten varios formatos de respuesta en función de las funcionalidades subyacentes del cliente de chat.

En este ejemplo se crea un agente que genera una salida estructurada en forma de un objeto JSON que se ajusta a un esquema de modelo Pydantic.

En primer lugar, defina un modelo Pydantic que represente la estructura de la salida que desea del agente:

from pydantic import BaseModel

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

Ahora puede crear un agente mediante el cliente de chat de 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."
)

Ahora puede ejecutar el agente con información textual y especificar el formato de salida estructurado mediante el 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
)

La respuesta del agente contendrá la salida estructurada en la propiedad value, a la que se puede acceder directamente como instancia de 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")

Cuando se transmite, la respuesta del agente se transmite como una serie de actualizaciones. Para obtener la salida estructurada, debe recopilar todas las actualizaciones y, a continuación, acceder al valor de respuesta 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}")