Megosztás:

Strukturált kimenet előállítása ügynökökkel

Ez az oktatóanyag lépés bemutatja, hogyan hozhat létre strukturált kimenetet egy ügynökkel, ahol az ügynök az Azure OpenAI Csevegés befejezése szolgáltatásra épül.

Fontos

Nem minden ügynöktípus támogatja a strukturált kimenetet. A ChatClientAgent támogatja a strukturált kimenetet ebben a lépésben.

Előfeltételek

Az előfeltételekről és a NuGet-csomagok telepítéséről lásd az egyszerű ügynök létrehozása és futtatása lépést ebben az oktatóanyagban.

Az ügynök létrehozása strukturált kimenettel

A ChatClientAgent rendszer minden IChatClient implementációra épül. A ChatClientAgent rendszer a mögöttes csevegőügyfél által biztosított strukturált kimenet támogatását használja.

Az ügynök létrehozásakor megadhatja az alapul ChatOptions szolgáló csevegőügyfél alapértelmezett példányát. Ez a ChatOptions példány lehetővé teszi egy előnyben részesített ChatResponseFormat kiválasztását.

Különböző lehetőségek ResponseFormat állnak rendelkezésre:

Ez a példa létrehoz egy ügynököt, amely egy adott sémának megfelelő JSON-objektum formájában hoz létre strukturált kimenetet.

A séma létrehozásának legegyszerűbb módja egy olyan típus definiálása, amely az ügynök által kívánt kimenet szerkezetét jelöli, majd a AIJsonUtilities.CreateJsonSchema metódussal létrehoz egy sémát a típusból.

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

Ezután létrehozhat egy példányt ChatOptions , amely ezt a sémát használja a válaszformátumhoz.

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

Ez a ChatOptions példány használható az ügynök létrehozásakor.

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

Figyelmeztetés

DefaultAzureCredential a fejlesztéshez kényelmes, de a termelési környezetben gondos megfontolást igényel. Éles környezetben fontolja meg egy adott hitelesítő adat (pl. ManagedIdentityCredential) használatát a késési problémák elkerülése, a hitelesítő adatok nem szándékos próbálgatásának és a tartalék mechanizmusokból eredő esetleges biztonsági kockázatok elkerülése érdekében.

Most már egyszerűen futtathatja az ügynököt olyan szöveges információkkal, amelyekkel az ügynök kitöltheti a strukturált kimenetet.

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

Az ügynök válasza ezután deszerializálható az PersonInfo osztályba a Deserialize<T> válaszobjektum metódusával.

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

Streameléskor az ügynök válasza frissítéssorozatként lesz streamelve, és a válasz csak az összes frissítés beérkezése után deszerializálható. Az összes frissítést a deszerializálás előtt egyetlen válaszba kell összeállítania.

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

Jótanács

A teljes futtatható példákért tekintse meg a .NET-mintákat .

Streamelési példa

Jótanács

A teljes futtatható példákért tekintse meg a .NET-mintákat .

Ez az oktatóanyag lépés bemutatja, hogyan hozhat létre strukturált kimenetet egy ügynökkel, ahol az ügynök az Azure OpenAI Csevegés befejezése szolgáltatásra épül.

Fontos

Nem minden ügynöktípus támogatja a strukturált kimenetet. Támogatja Agent a strukturált kimenetet, ha kompatibilis csevegőalkalmazásokkal használják.

Előfeltételek

Az előfeltételekről és a csomagok telepítéséről lásd a Egyszerű ügynök létrehozása és futtatása lépést ebben az oktatóanyagban.

Az ügynök létrehozása strukturált kimenettel

A Agent bármely olyan csevegőügyfél-implementáción alapul, amely támogatja a strukturált kimenetet. A Agent paraméter a response_format kívánt kimeneti séma megadására használja.

Az ügynök létrehozásakor vagy futtatásakor megadhat egy Pydantic-modellt, amely meghatározza a várt kimenet struktúráját.

A különböző válaszformátumok a mögöttes csevegőügyfél képességei alapján támogatottak.

Ez a példa létrehoz egy ügynököt, amely egy Pydantic-modellsémának megfelelő JSON-objektum formájában hoz létre strukturált kimenetet.

Először definiáljon egy Pydantic-modellt, amely az ügynök által kívánt kimenet struktúráját jelöli:

from pydantic import BaseModel

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

Most már létrehozhat egy ügynököt az Azure OpenAI csevegőügyfél használatával:

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

Most már futtathatja az ügynököt szöveges információkkal, és megadhatja a strukturált kimeneti formátumot a response_format paraméterrel:

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

Az ügynök válasza a value tulajdonságban található strukturált kimenetet tartalmazza, amely közvetlenül elérhető modellpéldányként a Pydantic-ban:

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

Streameléskor agent.run(..., stream=True) egy ResponseStream. A stream beépített véglegesítője automatikusan kezeli a strukturált kimeneti elemzéseket, így valós idejű frissítéseket iterálhat, majd meghívhatja get_final_response() az elemzés eredményét:

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

Ha nem kell feldolgoznia az egyes streamelési frissítéseket, teljesen kihagyhatja az iterációt – get_final_response() automatikusan felhasználja a streamet:

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

Teljes példa

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

Következő lépések

Háttérválaszok

  • Last updated on