Partager via

Produire une sortie structurée avec des agents

Cette étape du tutoriel vous montre comment produire une sortie structurée avec un agent, où l’agent est basé sur le service Azure OpenAI Chat Completion.

Important

Tous les types d’agents ne prennent pas en charge la sortie structurée. Cette étape utilise un ChatClientAgent, qui permet la sortie structurée.

Prerequisites

Pour connaître les prérequis et l’installation des packages NuGet, consultez l’étape Créer et exécuter un agent simple dans ce tutoriel.

Créer l’agent avec une sortie structurée

ChatClientAgent est basé sur n’importe quelle implémentation de IChatClient. Le ChatClientAgent utilise la prise en charge de la sortie structurée fournie par le client de chat sous-jacent.

Lors de la création de l’agent, vous avez la possibilité de fournir l’instance par défaut ChatOptions à utiliser pour le client de conversation sous-jacent. Cette ChatOptions instance vous permet de choisir un choix préféré ChatResponseFormat.

Différentes options ResponseFormat sont disponibles :

Cet exemple crée un agent qui produit une sortie structurée sous la forme d’un objet JSON conforme à un schéma spécifique.

Le moyen le plus simple de produire le schéma consiste à définir un type qui représente la structure de la sortie souhaitée à partir de l’agent, puis à utiliser la AIJsonUtilities.CreateJsonSchema méthode pour créer un schéma à partir du type.

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

Vous pouvez ensuite créer une ChatOptions instance qui utilise ce schéma pour le format de réponse.

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

Cette ChatOptions instance peut être utilisée lors de la création de l’agent.

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

Vous pouvez maintenant simplement exécuter l’agent avec des informations textuelles que l’agent peut utiliser pour remplir la sortie structurée.

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

La réponse de l’agent peut ensuite être désérialisée dans la classe PersonInfo à l'aide de la méthode Deserialize<T> sur l’objet de réponse.

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

Lors de la diffusion en continu, la réponse de l’agent est diffusée en tant que série de mises à jour et vous ne pouvez désérialiser la réponse qu’une fois que toutes les mises à jour ont été reçues. Vous devez assembler toutes les mises à jour en une seule réponse avant de la désérialiser.

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

Cette étape du tutoriel vous montre comment produire une sortie structurée avec un agent, où l’agent est basé sur le service Azure OpenAI Chat Completion.

Important

Tous les types d’agents ne prennent pas en charge la sortie structurée. ChatAgent prend en charge la sortie structurée lorsqu’il est utilisé avec des clients de messagerie compatibles.

Prerequisites

Pour connaître les prérequis et l’installation des packages, consultez l’étape Créer et exécuter un agent simple dans ce tutoriel.

Créer l’agent avec une sortie structurée

Le ChatAgent est construit sur n’importe quelle implémentation de client de conversation qui prend en charge la sortie structurée. Le ChatAgent utilise le paramètre response_format pour spécifier le schéma de sortie souhaité.

Lors de la création ou de l’exécution de l’agent, vous pouvez fournir un modèle Pydantic qui définit la structure de la sortie attendue.

Différents formats de réponse sont pris en charge en fonction des fonctionnalités du client de conversation sous-jacentes.

Cet exemple crée un agent qui produit une sortie structurée sous la forme d’un objet JSON conforme à un schéma de modèle Pydantic.

Tout d’abord, définissez un modèle Pydantic qui représente la structure de la sortie souhaitée à partir de l’agent :

from pydantic import BaseModel

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

Vous pouvez maintenant créer un agent à l’aide du client Azure OpenAI Chat :

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

Vous pouvez maintenant exécuter l’agent avec des informations textuelles et spécifier le format de sortie structuré à l’aide du response_format paramètre :

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

La réponse de l’agent contiendra la sortie structurée dans la value propriété, accessible directement en tant qu’instance de modèle 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")

Lors de la diffusion en continu, la réponse de l’agent est diffusée en continu sous la forme d’une série de mises à jour. Pour obtenir la sortie structurée, vous devez collecter toutes les mises à jour, puis accéder à la valeur de réponse finale :

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

Étapes suivantes

Utilisation d’un agent en tant qu’outil de fonction

  • Last updated on