Delen via

Gestructureerde uitvoer produceren met agents

Deze zelfstudiestap laat zien hoe u gestructureerde uitvoer kunt produceren met een agent, waar de agent is gebouwd op de Azure OpenAI Chat Completion-service.

Belangrijk

Niet alle agenttypen ondersteunen gestructureerde uitvoer. In deze stap wordt een ChatClientAgent gebruikt, die gestructureerde uitvoer ondersteunt.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten en het installeren van NuGet-pakketten.

Maak de agent met gestructureerde uitvoer

De ChatClientAgent is gebaseerd op elke IChatClient implementatie. Hierbij ChatClientAgent wordt gebruikgemaakt van de ondersteuning voor gestructureerde uitvoer die wordt geleverd door de onderliggende chatclient.

Wanneer u de agent maakt, kunt u het standaardexemplaar ChatOptions opgeven die moet worden gebruikt voor de onderliggende chatclient. Met dit ChatOptions exemplaar kunt u een voorkeur ChatResponseFormatkiezen.

Verschillende opties voor ResponseFormat zijn beschikbaar.

In dit voorbeeld wordt een agent gemaakt die gestructureerde uitvoer produceert in de vorm van een JSON-object dat voldoet aan een specifiek schema.

De eenvoudigste manier om het schema te produceren, is door een type te definiëren dat de structuur aangeeft van de gewenste uitvoer van de agent en vervolgens de AIJsonUtilities.CreateJsonSchema methode gebruikt om een schema te maken op basis van het 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));

Vervolgens kunt u een ChatOptions exemplaar maken dat dit schema gebruikt voor de antwoordindeling.

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

Dit ChatOptions exemplaar kan worden gebruikt bij het maken van de 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
        });

Waarschuwing

DefaultAzureCredential is handig voor ontwikkeling, maar vereist zorgvuldige overwegingen in de productieomgeving. Overweeg in productie een specifieke referentie te gebruiken (bijvoorbeeld ManagedIdentityCredential) om latentieproblemen, onbedoelde referentieprobing en potentiële beveiligingsrisico's van terugvalmechanismen te voorkomen.

Nu kunt u de agent gewoon uitvoeren met tekstinformatie die de agent kan gebruiken om de gestructureerde uitvoer in te vullen.

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

Het antwoord van de agent kan vervolgens worden gedeserialiseerd in de PersonInfo klasse met behulp van de Deserialize<T> methode voor het antwoordobject.

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

Bij het streamen wordt het antwoord van de agent gestreamd als een reeks updates en kunt u het antwoord alleen deserialiseren zodra alle updates zijn ontvangen. U moet alle updates in één antwoord samenstellen voordat u deze deserialiseert.

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

Aanbeveling

Zie de .NET-voorbeelden voor volledige runnable voorbeelden.

Voorbeeld van streaming

Aanbeveling

Zie de .NET-voorbeelden voor volledige runnable voorbeelden.

Deze zelfstudiestap laat zien hoe u gestructureerde uitvoer kunt produceren met een agent, waar de agent is gebouwd op de Azure OpenAI Chat Completion-service.

Belangrijk

Niet alle agenttypen ondersteunen gestructureerde uitvoer. De Agent ondersteunt gestructureerde uitvoer wanneer deze wordt gebruikt met compatibele chatclients.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten en het installeren van pakketten.

Maak de agent met gestructureerde uitvoer

De Agent is gebouwd op basis van elke chatclient-implementatie die gestructureerde uitvoer ondersteunt. De Agent parameter gebruikt de response_format parameter om het gewenste uitvoerschema op te geven.

Wanneer u de agent maakt of uitvoert, kunt u een Pydantic-model opgeven waarmee de structuur van de verwachte uitvoer wordt gedefinieerd.

Verschillende antwoordindelingen worden ondersteund op basis van de onderliggende chatclientmogelijkheden.

In dit voorbeeld wordt een agent gemaakt die gestructureerde uitvoer produceert in de vorm van een JSON-object dat voldoet aan een Pydantic-modelschema.

Definieer eerst een Pydantic-model dat de structuur vertegenwoordigt van de gewenste uitvoer van de agent:

from pydantic import BaseModel

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

U kunt nu een agent maken met behulp van de Azure OpenAI Chat-client:

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

U kunt nu de agent uitvoeren met tekstinformatie en de gestructureerde uitvoerindeling opgeven met behulp van de response_format parameter:

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

Het antwoord van de agent bevat de gestructureerde uitvoer in de value-eigenschap, dat direct toegankelijk is als een Pydantic-modelinstantie.

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

Bij het streamen geeft agent.run(..., stream=True) een ResponseStream. De ingebouwde finalizer van de stream verwerkt automatisch gestructureerde uitvoerparsering, zodat u realtime updates kunt herhalen en vervolgens kunt aanroepen get_final_response() om het geparseerde resultaat op te halen:

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

Als u afzonderlijke streaming-updates niet hoeft te verwerken, kunt u de iteratie volledig overslaan. get_final_response() De stream wordt automatisch gebruikt:

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

Volledig voorbeeld

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

Volgende stappen

Achtergrondantwoorden

  • Last updated on