Aracılığıyla paylaş

Ajanlarla Yapılandırılmış Veri Çıktısı Üretme

Bu öğretici adım, Azure OpenAI Sohbet Tamamlama hizmeti üzerinde oluşturulan bir ajan ile yapılandırılmış çıkış üretmenin nasıl yapıldığını göstermektedir.

Önemli

Tüm aracı türleri yapılandırılmış çıkışı desteklemez. Bu adımda yapılandırılmış çıkışı destekleyen bir ChatClientAgentkullanılır.

Önkoşullar

Önkoşullar ve NuGet paketlerini yükleme için bu öğreticideki Basit bir aracı oluşturma ve çalıştırma adımına bakın.

Yapılandırılmış çıkış ile aracı oluştur

ChatClientAgent, herhangi bir IChatClient uygulamanın üzerine kurulmuştur. ChatClientAgent altta yatan sohbet istemcisi tarafından sağlanan yapılandırılmış çıkış desteğini kullanır.

Aracıyı oluştururken, temel alınan sohbet istemcisi için kullanılacak varsayılan ChatOptions örneği sağlama seçeneğiniz vardır. Bu ChatOptions örnek, tercih edilen ChatResponseFormatöğesini seçmenize olanak tanır.

için ResponseFormat çeşitli seçenekler mevcuttur:

Bu örnek, belirli bir şemaya uyan bir JSON nesnesi biçiminde yapılandırılmış çıkış üreten bir aracı oluşturur.

Şemayı oluşturmanın en kolay yolu, aracıdan istediğiniz çıkışın yapısını temsil eden bir tür tanımlamak ve ardından türünden AIJsonUtilities.CreateJsonSchema bir şema oluşturmak için yöntemini kullanmaktır.

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

Ardından yanıt biçimi için bu şemayı kullanan bir ChatOptions örnek oluşturabilirsiniz.

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

Bu ChatOptions örnek aracı oluşturulurken kullanılabilir.

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

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Artık ajanı, ajanının yapılandırılmış çıktısını doldurmak için kullanabileceği bazı metin bilgileriyle çalıştırabilirsiniz.

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

Yanıt nesnesinde PersonInfo yöntemi kullanılarak, aracı yanıtı Deserialize<T> sınıfına deseriyalize edilebilir.

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

Akış yapılırken, ajan yanıtı bir dizi güncelleştirme olarak iletilir ve ancak tüm güncellemelere ulaşıldıktan sonra yanıt seri durumdan çıkartılabilir. Seri durumdan çıkarmadan önce tüm güncellemeleri tek bir yanıt içinde birleştirmeniz gerekir.

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

Çalıştırılabilir örneklerin tamamı için .NET örneklerine bakın.

Akış örneği

Tip

Çalıştırılabilir örneklerin tamamı için .NET örneklerine bakın.

Bu öğretici adım, Azure OpenAI Sohbet Tamamlama hizmeti üzerinde oluşturulan bir ajan ile yapılandırılmış çıkış üretmenin nasıl yapıldığını göstermektedir.

Önemli

Tüm aracı türleri yapılandırılmış çıkışı desteklemez. , Agent uyumlu sohbet istemcileriyle kullanıldığında yapılandırılmış çıkışı destekler.

Önkoşullar

Önkoşullar ve paketleri yükleme için bu öğreticideki Basit bir aracı oluşturma ve çalıştırma adımına bakın.

Yapılandırılmış çıkış ile aracı oluştur

, Agent yapılandırılmış çıkışı destekleyen tüm sohbet istemcisi uygulamalarının üzerine kurulmuştur. Agent, istenen çıkış şemasını belirtmek için response_format parametresini kullanır.

Aracıyı oluştururken veya çalıştırırken beklenen çıkışın yapısını tanımlayan bir Pydantic modeli sağlayabilirsiniz.

Temel alınan sohbet istemcisi özelliklerine göre çeşitli yanıt biçimleri desteklenir.

Bu örnek, Pydantic model şemasına uyan bir JSON nesnesi biçiminde yapılandırılmış çıkış üreten bir aracı oluşturur.

İlk olarak, aracıdan istediğiniz çıkışın yapısını temsil eden bir Pydantic modeli tanımlayın:

from pydantic import BaseModel

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

Artık Azure OpenAI Sohbet İstemcisi'ni kullanarak bir aracı oluşturabilirsiniz:

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

Artık aracıyı bazı metinsel bilgilerle çalıştırabilir ve parametresini response_format kullanarak yapılandırılmış çıkış biçimini belirtebilirsiniz:

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

Ajans yanıtı, value özelliğinde yapılandırılmış çıktıyı içerecektir ve bu çıkışa doğrudan bir Pydantic model örneği olarak erişilebilir.

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

Akış yaparken agent.run(..., stream=True) bir ResponseStream döndürür. Akışın yerleşik sonlandırıcısı, yapılandırılmış çıkış ayrıştırma işlemini otomatik olarak işler, böylece gerçek zamanlı güncelleştirmeler için yineleme yapabilir ve ardından ayrıştırılmış sonucu almak için çağrısı get_final_response() yapabilirsiniz:

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

Tek tek akış güncelleştirmelerini işlemeniz gerekmiyorsa yinelemeyi tamamen atlayabilirsiniz; get_final_response() akışı otomatik olarak kullanır:

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

Tam örnek

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

Sonraki Adımlar

Arka Plan Yanıtları

  • Last updated on