Udostępnij przez

Tworzenie uporządkowanych danych wyjściowych z wykorzystaniem agentów

W tym kroku samouczka pokazano, jak utworzyć ustrukturyzowany wynik za pomocą agenta, w którym agent jest oparty na usłudze Ukończenia Czatu Azure OpenAI.

Ważne

Nie wszystkie typy agentów obsługują dane wyjściowe ze strukturą. W tym kroku używany jest komponent ChatClientAgent, który obsługuje strukturalne dane wyjściowe.

Wymagania wstępne

Aby uzyskać wymagania wstępne i zainstalować pakiety NuGet, zobacz krok Tworzenie i uruchamianie prostego agenta w tym samouczku.

Tworzenie agenta ze ustrukturyzowanymi danymi wyjściowymi

Element ChatClientAgent jest oparty na dowolnej IChatClient implementacji. Funkcja ChatClientAgent korzysta z obsługi danych wyjściowych ze strukturą udostępnianych przez bazowego klienta czatu.

Podczas tworzenia agenta możesz podać domyślne wystąpienie ChatOptions do użycia dla bazowego klienta czatu. To ChatOptions wystąpienie umożliwia wybranie preferowanego ChatResponseFormat.

Dostępne są różne opcje ResponseFormat :

W tym przykładzie tworzony jest agent tworzący ustrukturyzowane dane wyjściowe w postaci obiektu JSON zgodnego z określonym schematem.

Najprostszym sposobem utworzenia schematu jest zdefiniowanie typu reprezentującego strukturę danych wyjściowych z agenta, a następnie użycie AIJsonUtilities.CreateJsonSchema metody w celu utworzenia schematu na podstawie typu.

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

Następnie możesz utworzyć ChatOptions wystąpienie, które używa tego schematu dla formatu odpowiedzi.

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

Tego ChatOptions wystąpienia można używać do tworzenia agenta.

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

Ostrzeżenie

DefaultAzureCredential jest wygodne do programowania, ale wymaga starannego rozważenia w środowisku produkcyjnym. W środowisku produkcyjnym rozważ użycie określonego poświadczenia (np. ManagedIdentityCredential), aby uniknąć problemów z opóźnieniami, niezamierzonego sondowania poświadczeń i potencjalnych zagrożeń bezpieczeństwa wynikających z mechanizmów awaryjnych.

Teraz możesz po prostu uruchomić agenta z pewnymi tekstowymi informacjami, których agent może użyć do wypełnienia ustrukturyzowanych danych wyjściowych.

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

Następnie odpowiedź agenta może zostać zdeserializowana do klasy PersonInfo przy użyciu metody Deserialize<T> na obiekcie odpowiedzi.

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

Podczas strumieniowania odpowiedź agenta jest przesyłana w formie serii aktualizacji, a deserializację odpowiedzi można przeprowadzić dopiero po odebraniu wszystkich aktualizacji. Należy zebrać wszystkie aktualizacje w jedną odpowiedź przed deserializowaniem ich.

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

Tip

Zobacz przykłady dla platformy .NET , aby uzyskać pełne przykłady możliwych do uruchomienia.

Przykład przesyłania strumieniowego

Tip

Zobacz przykłady dla platformy .NET , aby uzyskać pełne przykłady możliwych do uruchomienia.

W tym kroku samouczka pokazano, jak utworzyć ustrukturyzowany wynik za pomocą agenta, w którym agent jest oparty na usłudze Ukończenia Czatu Azure OpenAI.

Ważne

Nie wszystkie typy agentów obsługują dane wyjściowe ze strukturą. Funkcja Agent obsługuje dane wyjściowe ze strukturą, gdy są używane z zgodnymi klientami czatu.

Wymagania wstępne

Aby uzyskać informacje o wymaganiach wstępnych i instalowanych pakietach, zobacz krok Tworzenie i uruchamianie prostego agenta w tym samouczku.

Tworzenie agenta ze ustrukturyzowanymi danymi wyjściowymi

Element Agent jest zbudowany na podstawie dowolnej implementacji klienta czatu, która obsługuje ustrukturyzowane dane wyjściowe. Parametr Agent używa parametru response_format do określenia żądanego schematu wyjściowego.

Podczas tworzenia lub uruchamiania agenta można podać model Pydantic, który definiuje strukturę oczekiwanych danych wyjściowych.

Różne formaty odpowiedzi są obsługiwane na podstawie podstawowych możliwości klienta czatu.

W tym przykładzie tworzony jest agent, który generuje ustrukturyzowane dane wyjściowe w postaci obiektu JSON zgodnego ze schematem modelu Pydantic.

Najpierw zdefiniuj model Pydantic, który reprezentuje strukturę danych wyjściowych, które chcesz uzyskać od agenta:

from pydantic import BaseModel

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

Teraz możesz utworzyć agenta przy użyciu klienta czatu usługi Azure OpenAI:

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

Teraz możesz uruchomić agenta z pewnymi informacjami tekstowymi i określić ustrukturyzowany format danych wyjściowych przy użyciu parametru response_format :

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

Odpowiedź zgenerowana przez agenta będzie zawierać ustrukturyzowane dane wyjściowe we właściwości value, do których można uzyskać bezpośredni dostęp jako wystąpienie modelu 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")

Podczas przesyłania strumieniowego agent.run(..., stream=True) zwraca wartość ResponseStream. Wbudowany finalizator strumienia automatycznie obsługuje analizowanie danych wyjściowych o strukturze, dzięki czemu można iterować w celu aktualizowania w czasie rzeczywistym, a następnie wywołać metodę get_final_response() w celu uzyskania przeanalizowanego wyniku.

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

Jeśli nie musisz przetwarzać poszczególnych aktualizacji przesyłania strumieniowego, możesz całkowicie pominąć iterację — get_final_response() automatycznie zużyje strumień:

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

Kompletny przykład

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

Dalsze kroki

Odpowiedzi systemowe

  • Last updated on