Freigeben über

Erstellen einer strukturierten Ausgabe mit Agents

In diesem Lernschritt erfahren Sie, wie Sie eine strukturierte Ausgabe mit einem Agenten erzeugen, der auf dem Azure OpenAI Chat Completion-Service basiert.

Von Bedeutung

Nicht alle Agenttypen unterstützen strukturierte Ausgabe. Dieser Schritt verwendet eine ChatClientAgent, die strukturierte Ausgabe unterstützt.

Voraussetzungen

Für Voraussetzungen und die Installation von NuGet-Paketen siehe den Schritt Erstellen und Ausführen eines einfachen Agenten in diesem Tutorial.

Erstellen eines Agents mit strukturierter Ausgabe

Dies ChatClientAgent basiert auf jeder IChatClient Implementierung. Der ChatClientAgent nutzt die Unterstützung für strukturierte Ausgaben, die vom zugrunde liegenden Chatclient bereitgestellt wird.

Beim Erstellen des Agents haben Sie die Möglichkeit, die Standardinstanz ChatOptions bereitzustellen, die für den zugrunde liegenden Chatclient verwendet werden soll. Mit dieser ChatOptions Instanz können Sie eine bevorzugte ChatResponseFormatInstanz auswählen.

Es stehen verschiedene Optionen zur ResponseFormat Verfügung:

In diesem Beispiel wird ein Agent erstellt, der eine strukturierte Ausgabe in Form eines JSON-Objekts erzeugt, das einem bestimmten Schema entspricht.

Die einfachste Möglichkeit zum Erstellen des Schemas besteht darin, einen Typ zu definieren, der die Struktur der vom Agent gewünschten Ausgabe darstellt, und dann die AIJsonUtilities.CreateJsonSchema Methode zum Erstellen eines Schemas aus dem Typ verwenden.

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

Anschließend können Sie eine ChatOptions Instanz erstellen, die dieses Schema für das Antwortformat verwendet.

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

Diese ChatOptions Instanz kann beim Erstellen des Agents verwendet werden.

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

Warnung

DefaultAzureCredential ist praktisch für die Entwicklung, erfordert aber sorgfältige Überlegungen in der Produktion. Berücksichtigen Sie in der Produktion die Verwendung bestimmter Anmeldeinformationen (z. B. ManagedIdentityCredential), um Latenzprobleme, unbeabsichtigte Abfragen von Anmeldeinformationen und potenzielle Sicherheitsrisiken durch Ausweichmechanismen zu vermeiden.

Jetzt können Sie den Agenten einfach mit Textinformationen starten, die er zum Ausfüllen der strukturierten Ausgabe verwenden kann.

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

Die Agentantwort kann dann mithilfe der PersonInfo Methode für das Antwortobjekt in die Deserialize<T> Klasse deserialisiert werden.

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

Beim Streaming wird die Agent-Antwort als eine Reihe von Updates gestreamt, und Sie können die Antwort nur deserialisieren, nachdem alle Updates empfangen wurden. Sie müssen alle Updates in einer einzigen Antwort zusammenstellen, bevor Sie sie deserialisieren.

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

Tipp

Vollständige Runnable-Beispiele finden Sie in den .NET-Beispielen .

Streamingbeispiel

Tipp

Vollständige Runnable-Beispiele finden Sie in den .NET-Beispielen .

In diesem Lernschritt erfahren Sie, wie Sie eine strukturierte Ausgabe mit einem Agenten erzeugen, der auf dem Azure OpenAI Chat Completion-Service basiert.

Von Bedeutung

Nicht alle Agenttypen unterstützen strukturierte Ausgabe. Agent unterstützt die strukturierte Ausgabe, wenn es mit kompatiblen Chat-Clients verwendet wird.

Voraussetzungen

Die erforderlichen Komponenten und die Installation von Paketen finden Sie im Schritt "Erstellen und Ausführen eines einfachen Agents " in diesem Lernprogramm.

Erstellen eines Agents mit strukturierter Ausgabe

Diese Agent basiert auf jeder Chat-Client-Implementierung, die strukturierte Ausgabe unterstützt. Der Agent verwendet den response_format Parameter, um das gewünschte Ausgabeschema anzugeben.

Beim Erstellen oder Ausführen des Agents können Sie ein Pydantisches Modell bereitstellen, das die Struktur der erwarteten Ausgabe definiert.

Verschiedene Antwortformate werden basierend auf den zugrunde liegenden Chatclientfunktionen unterstützt.

In diesem Beispiel wird ein Agent erstellt, der eine strukturierte Ausgabe in Form eines JSON-Objekts erzeugt, das einem Pydantischen Modellschema entspricht.

Definieren Sie zunächst ein Pydantisches Modell, das die Struktur der gewünschten Ausgabe aus dem Agent darstellt:

from pydantic import BaseModel

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

Jetzt können Sie einen Agent mit dem Azure OpenAI-Chatclient erstellen:

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

Jetzt können Sie den Agent mit textbezogenen Informationen ausführen und das strukturierte Ausgabeformat mithilfe des response_format Parameters angeben:

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

Die Agentantwort enthält die strukturierte Ausgabe in der value Eigenschaft, auf die direkt als Pydantische Modellinstanz zugegriffen werden kann:

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

Beim Streaming gibt agent.run(..., stream=True) ein ResponseStream zurück. Der integrierte Finalizer des Datenstroms verarbeitet automatisch die strukturierten Ausgabedaten, sodass Sie nach Echtzeitaktualisierungen durchlaufen können und dann get_final_response() aufrufen, um das geparste Ergebnis abzurufen.

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

Wenn Sie keine einzelnen Streamingupdates verarbeiten müssen, können Sie die Iteration vollständig überspringen – get_final_response() verwendet automatisch den Datenstrom:

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

Vollständiges Beispiel

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

Nächste Schritte

Hintergrundantworten

  • Last updated on