Bagikan melalui

Menghasilkan Output Terstruktur dengan Agen

Langkah tutorial ini menunjukkan kepada Anda cara menghasilkan output terstruktur dengan agen, di mana agen dibangun di layanan Penyelesaian Obrolan Azure OpenAI.

Penting

Tidak semua jenis agen mendukung output terstruktur secara asli. Mendukung output terstruktur ChatClientAgent saat digunakan dengan klien obrolan yang sesuai.

Prasyarat

Untuk prasyarat dan menginstal paket NuGet, lihat langkah Membuat dan menjalankan agen sederhana dalam tutorial ini.

Menentukan jenis untuk output terstruktur

Pertama, tentukan jenis yang mewakili struktur output yang Anda inginkan dari agen.

public class PersonInfo
{
    public string? Name { get; set; }
    public int? Age { get; set; }
    public string? Occupation { get; set; }
}

Membuat agen

Buat ChatClientAgent menggunakan Azure OpenAI Chat Client.

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");

Keluaran terstruktur dengan RunAsync<T>

Metode RunAsync<T> ini tersedia di AIAgent kelas dasar. Ini menerima parameter jenis generik yang menentukan jenis output terstruktur. Pendekatan ini berlaku ketika jenis output terstruktur diketahui pada waktu kompilasi dan instans hasil yang ditik diperlukan. Ini mendukung primitif, array, dan jenis kompleks.

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

Console.WriteLine($"Name: {response.Result.Name}, Age: {response.Result.Age}, Occupation: {response.Result.Occupation}");

Output terstruktur dengan ResponseFormat

Output terstruktur dapat dikonfigurasi dengan mengatur properti ResponseFormat pada AgentRunOptions saat pemanggilan, atau saat inisialisasi agen untuk agen yang mendukungnya, seperti ChatClientAgent dan Foundry Agent.

Pendekatan ini berlaku ketika:

  • Jenis output terstruktur tidak diketahui pada waktu kompilasi.
  • Skema diwakili sebagai JSON mentah.
  • Output terstruktur hanya dapat dikonfigurasi pada waktu pembuatan agen.
  • Hanya teks JSON mentah yang diperlukan tanpa deserialisasi.
  • Kolaborasi antar-agen digunakan.

Berbagai opsi untuk ResponseFormat tersedia:

Nota

Primitif dan array tidak didukung oleh pendekatan ResponseFormat. Jika Anda perlu bekerja dengan primitif atau array, gunakan pendekatan RunAsync<T> atau buat tipe pembungkus.

// Instead of using List<string> directly, create a wrapper type:
public class MovieListWrapper
{
    public List<string> Movies { get; set; }
}

using System.Text.Json;
using Microsoft.Extensions.AI;

AgentRunOptions runOptions = new()
{
    ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
};

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

PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text, JsonSerializerOptions.Web)!;

Console.WriteLine($"Name: {personInfo.Name}, Age: {personInfo.Age}, Occupation: {personInfo.Occupation}");

ResponseFormat juga dapat ditentukan menggunakan string skema JSON mentah, yang berguna ketika tidak ada jenis .NET yang sesuai yang tersedia, seperti untuk agen deklaratif atau skema yang dimuat dari konfigurasi eksternal:

string jsonSchema = """
{
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "age": { "type": "integer" },
        "occupation": { "type": "string" }
    },
    "required": ["name", "age", "occupation"]
}
""";

AgentRunOptions runOptions = new()
{
    ResponseFormat = ChatResponseFormat.ForJsonSchema(JsonElement.Parse(jsonSchema), "PersonInfo", "Information about a person")
};

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

JsonElement result = JsonSerializer.Deserialize<JsonElement>(response.Text);

Console.WriteLine($"Name: {result.GetProperty("name").GetString()}, Age: {result.GetProperty("age").GetInt32()}, Occupation: {result.GetProperty("occupation").GetString()}");

Keluaran terstruktur dengan fitur streaming

Saat streaming, respons agen dialirkan sebagai serangkaian pembaruan, dan Anda hanya dapat mendeserialisasi respons setelah semua pembaruan diterima. Anda harus merakit semua pembaruan menjadi satu respons sebelum mendeserialisasinya.

using System.Text.Json;
using Microsoft.Extensions.AI;

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 = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
        });

> [!WARNING]
> `DefaultAzureCredential` is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.

IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");

AgentResponse response = await updates.ToAgentResponseAsync();

PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text)!;

Console.WriteLine($"Name: {personInfo.Name}, Age: {personInfo.Age}, Occupation: {personInfo.Occupation}");

Output terstruktur dengan agen yang seharusnya memiliki kemampuan output terstruktur namun tidak memilikinya.

Beberapa agen tidak secara asli mendukung output terstruktur, baik karena itu bukan bagian dari protokol atau karena agen menggunakan model bahasa tanpa kemampuan output terstruktur. Salah satu pendekatan yang mungkin adalah membuat agen dekorator kustom yang membungkus apa pun AIAgent dan menggunakan panggilan LLM tambahan melalui klien obrolan untuk mengonversi respons teks agen menjadi JSON terstruktur.

Nota

Karena pendekatan ini bergantung pada panggilan LLM tambahan untuk mengubah respons, keandalannya mungkin tidak cukup untuk semua skenario.

Untuk implementasi referensi pola ini yang dapat Anda adaptasi dengan persyaratan Anda sendiri, lihat sampel StructuredOutputAgent.

Petunjuk / Saran

Lihat sampel .NET untuk contoh lengkap yang dapat dijalankan.

Contoh streaming

Petunjuk / Saran

Lihat sampel .NET untuk contoh lengkap yang dapat dijalankan.

Langkah tutorial ini menunjukkan kepada Anda cara menghasilkan output terstruktur dengan agen, di mana agen dibangun di layanan Penyelesaian Obrolan Azure OpenAI.

Penting

Tidak semua jenis agen mendukung output terstruktur. Mendukung output terstruktur Agent saat digunakan dengan klien obrolan yang sesuai.

Prasyarat

Untuk prasyarat dan penginstalan paket, lihat langkah Buat dan jalankan agen sederhana dalam tutorial ini.

Membuat agen dengan output terstruktur

Agent dibangun di atas implementasi klien obrolan apa pun yang mendukung output terstruktur. Agent menggunakan response_format parameter untuk menentukan skema output yang diinginkan.

Saat membuat atau menjalankan agen, Anda dapat menyediakan model Pydantic yang menentukan struktur output yang diharapkan.

Berbagai format respons didukung berdasarkan kemampuan klien obrolan yang mendasar.

Contoh ini membuat agen yang menghasilkan output terstruktur dalam bentuk objek JSON yang sesuai dengan skema model Pydantic.

Pertama, tentukan model Pydantic yang mewakili struktur output yang Anda inginkan dari agen:

from pydantic import BaseModel

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

Sekarang Anda dapat membuat agen menggunakan Klien Obrolan 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."
)

Sekarang Anda dapat menjalankan agen dengan beberapa informasi tekstual dan menentukan format output terstruktur menggunakan response_format parameter :

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

Respons agen akan berisi output terstruktur dalam value properti , yang dapat diakses langsung sebagai instans model 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")

Saat streaming, agent.run(..., stream=True) mengembalikan ResponseStream. Finalizer bawaan stream secara otomatis menangani proses penguraian keluaran terstruktur, sehingga Anda dapat melakukan iterasi untuk pembaruan real-time lalu memanggil get_final_response() untuk mendapatkan hasil yang sudah diurai.

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

Jika Anda tidak perlu memproses pembaruan streaming individu, Anda dapat sepenuhnya melewati iterasi — get_final_response() akan secara otomatis mengonsumsi aliran tersebut.

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

Contoh lengkap

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

Langkah selanjutnya

Respons Latar Belakang

  • Last updated on