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. Langkah ini menggunakan ChatClientAgent, yang mendukung output terstruktur.

Prasyarat

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

Membuat agen dengan output terstruktur

ChatClientAgent dibangun di atas IChatClient implementasi apa pun. menggunakan ChatClientAgent dukungan untuk output terstruktur yang disediakan oleh klien obrolan yang mendasar.

Saat membuat agen, Anda memiliki opsi untuk menyediakan instans default ChatOptions yang akan digunakan untuk klien obrolan yang mendasar. Instans ini ChatOptions memungkinkan Anda untuk memilih pilihan ChatResponseFormat.

Berbagai opsi untuk ResponseFormat tersedia:

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

Cara termudah untuk menghasilkan skema adalah dengan menentukan tipe yang menggambarkan struktur output yang dihasilkan agen, kemudian dengan menggunakan metode AIJsonUtilities.CreateJsonSchema untuk membuat skema dari tipe tersebut.

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

Anda kemudian dapat membuat ChatOptions instans yang menggunakan skema ini untuk format respons.

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

Instans ini ChatOptions dapat digunakan saat membuat agen.

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 AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(new ChatClientAgentOptions()
        {
            Name = "HelpfulAssistant",
            Instructions = "You are a helpful assistant.",
            ChatOptions = chatOptions
        });

Sekarang Anda hanya dapat menjalankan agen dengan beberapa informasi tekstual yang dapat digunakan agen untuk mengisi output terstruktur.

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

Respons agen kemudian dapat dideserialisasi menjadi objek kelas PersonInfo menggunakan metode Deserialize<T> pada objek respons.

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

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.

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

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 ChatAgent 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

ChatAgent dibangun di atas implementasi klien obrolan apa pun yang mendukung output terstruktur. ChatAgent 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, respons agen dialirkan sebagai serangkaian pembaruan. Untuk mendapatkan output terstruktur, Anda harus mengumpulkan semua pembaruan lalu mengakses nilai respons akhir:

from agent_framework import AgentResponse

# Get structured response from streaming agent using AgentResponse.from_agent_response_generator
# This method collects all streaming updates and combines them into a single AgentResponse
final_response = await AgentResponse.from_agent_response_generator(
    agent.run_stream(query, response_format=PersonInfo),
    output_format_type=PersonInfo,
)

if final_response.value:
    person_info = final_response.value
    print(f"Name: {person_info.name}, Age: {person_info.age}, Occupation: {person_info.occupation}")

Langkah selanjutnya

Menggunakan agen sebagai alat fungsi

  • Last updated on