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 DefaultAzureCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(new ChatClientAgentOptions()
        {
            Name = "HelpfulAssistant",
            Instructions = "You are a helpful assistant.",
            ChatOptions = chatOptions
        });

Avertissement

DefaultAzureCredential est pratique pour le développement, mais nécessite une considération minutieuse en production. En production, envisagez d’utiliser des informations d’identification spécifiques (par exemple ManagedIdentityCredential) pour éviter les problèmes de latence, la détection involontaire des informations d’identification et les risques de sécurité potentiels liés aux mécanismes de secours.

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.ToAgentResponseAsync()).Deserialize<PersonInfo>(JsonSerializerOptions.Web);

Conseil / Astuce

Consultez les exemples .NET pour obtenir des exemples exécutables complets.

Exemple de diffusion en continu

Conseil / Astuce

Consultez les exemples .NET pour obtenir des exemples exécutables complets.

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. Agent 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 Agent est construit sur n’importe quelle implémentation de client de conversation qui prend en charge la sortie structurée. Le Agent 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()).as_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, agent.run(..., stream=True) retourne un ResponseStream. Le finaliseur intégré du flux gère automatiquement l’analyse de sortie structurée. Vous pouvez donc itérer pour les mises à jour en temps réel, puis appeler get_final_response() pour obtenir le résultat analysé :

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

Si vous n’avez pas besoin de traiter les mises à jour de diffusion en continu individuelles, vous pouvez ignorer entièrement l’itération. get_final_response() Elle consomme automatiquement le flux :

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

Exemple complet

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

Prochaines étapes

Réponses en arrière-plan

  • Last updated on