Delen via

Gestructureerde uitvoer produceren met agents

Deze zelfstudiestap laat zien hoe u gestructureerde uitvoer kunt produceren met een agent, waar de agent is gebouwd op de Azure OpenAI Chat Completion-service.

Belangrijk

Niet alle agenttypen ondersteunen gestructureerde uitvoer. In deze stap wordt een ChatClientAgent gebruikt, die gestructureerde uitvoer ondersteunt.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten en het installeren van NuGet-pakketten.

Maak de agent met gestructureerde uitvoer

De ChatClientAgent is gebaseerd op elke IChatClient implementatie. Hierbij ChatClientAgent wordt gebruikgemaakt van de ondersteuning voor gestructureerde uitvoer die wordt geleverd door de onderliggende chatclient.

Wanneer u de agent maakt, kunt u het standaardexemplaar ChatOptions opgeven die moet worden gebruikt voor de onderliggende chatclient. Met dit ChatOptions exemplaar kunt u een voorkeur ChatResponseFormatkiezen.

Verschillende opties voor ResponseFormat zijn beschikbaar.

In dit voorbeeld wordt een agent gemaakt die gestructureerde uitvoer produceert in de vorm van een JSON-object dat voldoet aan een specifiek schema.

De eenvoudigste manier om het schema te produceren, is door een type te definiëren dat de structuur aangeeft van de gewenste uitvoer van de agent en vervolgens de AIJsonUtilities.CreateJsonSchema methode gebruikt om een schema te maken op basis van het type.

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

Vervolgens kunt u een ChatOptions exemplaar maken dat dit schema gebruikt voor de antwoordindeling.

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

Dit ChatOptions exemplaar kan worden gebruikt bij het maken van de agent.

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")
        .CreateAIAgent(new ChatClientAgentOptions()
        {
            Name = "HelpfulAssistant",
            Instructions = "You are a helpful assistant.",
            ChatOptions = chatOptions
        });

Nu kunt u de agent gewoon uitvoeren met tekstinformatie die de agent kan gebruiken om de gestructureerde uitvoer in te vullen.

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

Het antwoord van de agent kan vervolgens worden gedeserialiseerd in de PersonInfo klasse met behulp van de Deserialize<T> methode voor het antwoordobject.

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

Bij het streamen wordt het antwoord van de agent gestreamd als een reeks updates en kunt u het antwoord alleen deserialiseren zodra alle updates zijn ontvangen. U moet alle updates in één antwoord samenstellen voordat u deze deserialiseert.

var updates = agent.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");
personInfo = (await updates.ToAgentRunResponseAsync()).Deserialize<PersonInfo>(JsonSerializerOptions.Web);

Deze zelfstudiestap laat zien hoe u gestructureerde uitvoer kunt produceren met een agent, waar de agent is gebouwd op de Azure OpenAI Chat Completion-service.

Belangrijk

Niet alle agenttypen ondersteunen gestructureerde uitvoer. De ChatAgent ondersteunt gestructureerde uitvoer wanneer deze wordt gebruikt met compatibele chatclients.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten en het installeren van pakketten.

Maak de agent met gestructureerde uitvoer

De ChatAgent is gebouwd op basis van elke chatclient-implementatie die gestructureerde uitvoer ondersteunt. De ChatAgent parameter gebruikt de response_format parameter om het gewenste uitvoerschema op te geven.

Wanneer u de agent maakt of uitvoert, kunt u een Pydantic-model opgeven waarmee de structuur van de verwachte uitvoer wordt gedefinieerd.

Verschillende antwoordindelingen worden ondersteund op basis van de onderliggende chatclientmogelijkheden.

In dit voorbeeld wordt een agent gemaakt die gestructureerde uitvoer produceert in de vorm van een JSON-object dat voldoet aan een Pydantic-modelschema.

Definieer eerst een Pydantic-model dat de structuur vertegenwoordigt van de gewenste uitvoer van de agent:

from pydantic import BaseModel

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

U kunt nu een agent maken met behulp van de Azure OpenAI Chat-client:

from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

# Create the agent using Azure OpenAI Chat Client
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
    name="HelpfulAssistant",
    instructions="You are a helpful assistant that extracts person information from text."
)

U kunt nu de agent uitvoeren met tekstinformatie en de gestructureerde uitvoerindeling opgeven met behulp van de response_format parameter:

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

Het antwoord van de agent bevat de gestructureerde uitvoer in de value-eigenschap, dat direct toegankelijk is als een Pydantic-modelinstantie.

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

Bij het streamen wordt het antwoord van de agent gestreamd als een reeks updates. Als u de gestructureerde uitvoer wilt ophalen, moet u alle updates verzamelen en vervolgens de uiteindelijke antwoordwaarde openen:

from agent_framework import AgentRunResponse

# Get structured response from streaming agent using AgentRunResponse.from_agent_response_generator
# This method collects all streaming updates and combines them into a single AgentRunResponse
final_response = await AgentRunResponse.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}")

Volgende stappen

Een agent gebruiken als functiehulpmiddel

  • Last updated on