Gebruik van functietools met menselijke tussenkomst voor goedkeuringen

Deze zelfstudiestap laat zien hoe u functiehulpprogramma's gebruikt waarvoor menselijke goedkeuring met een agent is vereist, waarbij de agent is gebouwd op de Azure OpenAI Chat Completion-service.

Wanneer agents gebruikersinvoer nodig hebben, bijvoorbeeld om een functieaanroep goed te keuren, wordt dit een human-in-the-loop-patroon genoemd. Een agentuitvoering waarvoor gebruikersinvoer is vereist, wordt voltooid met een antwoord dat aangeeft welke invoer van de gebruiker is vereist, in plaats van een definitief antwoord te voltooien. De aanroeper van de agent is vervolgens verantwoordelijk voor het ophalen van de vereiste invoer van de gebruiker en het aan de agent doorgeven ervan als onderdeel van een nieuwe agent-uitvoering.

Vereiste voorwaarden

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

De agent maken met functiehulpprogramma's

Wanneer u functies gebruikt, is het mogelijk om aan te geven voor elke functie, of er menselijke goedkeuring is vereist voordat deze wordt uitgevoerd. Dit wordt gedaan door het AIFunction exemplaar in een ApprovalRequiredAIFunction instantie te verpakken.

Hier volgt een voorbeeld van een eenvoudig hulpmiddel voor functies dat doet alsof het het weer voor een bepaalde locatie ophaalt.

using System;
using System.ComponentModel;
using System.Linq;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
    => $"The weather in {location} is cloudy with a high of 15°C.";

Als u een AIFunction en vervolgens in een ApprovalRequiredAIFunctionwilt verpakken, kunt u het volgende doen:

AIFunction weatherFunction = AIFunctionFactory.Create(GetWeather);
AIFunction approvalRequiredWeatherFunction = new ApprovalRequiredAIFunction(weatherFunction);

Wanneer u de agent creëert, kunt u nu de functie voor goedkeuring vereisend hulpprogramma aan de agent verschaffen door een lijst met hulpmiddelen door te geven aan de CreateAIAgent methode.

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

Omdat u nu een functie hebt waarvoor goedkeuring is vereist, kan de agent reageren met een aanvraag voor goedkeuring, in plaats van de functie rechtstreeks uit te voeren en het resultaat te retourneren. U kunt de antwoordinhoud voor alle FunctionApprovalRequestContent exemplaren controleren, wat aangeeft dat de agent goedkeuring van de gebruiker voor een functie vereist.

AgentThread thread = agent.GetNewThread();
AgentRunResponse response = await agent.RunAsync("What is the weather like in Amsterdam?", thread);

var functionApprovalRequests = response.Messages
    .SelectMany(x => x.Contents)
    .OfType<FunctionApprovalRequestContent>()
    .ToList();

Als er aanvragen voor functiegoedkeuring zijn, kunt u de details van de functie-aanroep, inclusief naam en argumenten, vinden in de FunctionCall eigenschap van het FunctionApprovalRequestContent exemplaar. Dit kan worden weergegeven aan de gebruiker, zodat hij of zij kan bepalen of de functieaanroep moet worden goedgekeurd of geweigerd. In dit voorbeeld wordt ervan uitgegaan dat er één aanvraag is.

FunctionApprovalRequestContent requestContent = functionApprovalRequests.First();
Console.WriteLine($"We require approval to execute '{requestContent.FunctionCall.Name}'");

Zodra de gebruiker zijn invoer heeft opgegeven, kunt u een FunctionApprovalResponseContent exemplaar maken met behulp van de CreateResponse methode op de FunctionApprovalRequestContent. Geef true door om de functie-aanroep goed te keuren of false om deze af te wijzen.

De antwoordinhoud kan vervolgens worden doorgegeven aan de agent in een nieuwe User samen met hetzelfde ChatMessage threadobject om het resultaat van de agent terug te ontvangen.

var approvalMessage = new ChatMessage(ChatRole.User, [requestContent.CreateResponse(true)]);
Console.WriteLine(await agent.RunAsync(approvalMessage, thread));

Wanneer u functietools gebruikt met menselijke goedkeuringen in de cyclus, moet u nagaan op FunctionApprovalRequestContent exemplaren in het antwoord na elke agentuitvoering, totdat alle functieaanroepen zijn goedgekeurd of geweigerd.

In deze zelfstudie leert u hoe u functiehulpprogramma's gebruikt waarvoor goedkeuring door een mens met behulp van een agent vereist is.

Wanneer agents gebruikersinvoer nodig hebben, bijvoorbeeld om een functieaanroep goed te keuren, wordt dit een human-in-the-loop-patroon genoemd. Een agentuitvoering waarvoor gebruikersinvoer is vereist, wordt voltooid met een antwoord dat aangeeft welke invoer van de gebruiker is vereist, in plaats van een definitief antwoord te voltooien. De aanroeper van de agent is vervolgens verantwoordelijk voor het ophalen van de vereiste invoer van de gebruiker en het aan de agent doorgeven ervan als onderdeel van een nieuwe agent-uitvoering.

Vereiste voorwaarden

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

Maak de agent met functionaliteiten waarvoor goedkeuring is vereist

Wanneer u functies gebruikt, is het mogelijk om aan te geven voor elke functie, of er menselijke goedkeuring is vereist voordat deze wordt uitgevoerd. Dit wordt bereikt door de approval_mode parameter op "always_require" te zetten wanneer de @ai_function decorator wordt gebruikt.

Hier volgt een voorbeeld van een eenvoudig hulpmiddel voor functies dat doet alsof het het weer voor een bepaalde locatie ophaalt.

from typing import Annotated
from agent_framework import ai_function

@ai_function
def get_weather(location: Annotated[str, "The city and state, e.g. San Francisco, CA"]) -> str:
    """Get the current weather for a given location."""
    return f"The weather in {location} is cloudy with a high of 15°C."

Als u een functie wilt maken waarvoor goedkeuring is vereist, kunt u de approval_mode parameter gebruiken:

@ai_function(approval_mode="always_require")
def get_weather_detail(location: Annotated[str, "The city and state, e.g. San Francisco, CA"]) -> str:
    """Get detailed weather information for a given location."""
    return f"The weather in {location} is cloudy with a high of 15°C, humidity 88%."

Wanneer u de agent maakt, kunt u nu de functiehulpprogramma's die goedkeuring vereisen aan de agent toewijzen door een lijst met hulpprogramma's door te geven aan de ChatAgent constructor.

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIResponsesClient

async with ChatAgent(
    chat_client=OpenAIResponsesClient(),
    name="WeatherAgent",
    instructions="You are a helpful weather assistant.",
    tools=[get_weather, get_weather_detail],
) as agent:
    # Agent is ready to use

Omdat u nu een functie hebt waarvoor goedkeuring is vereist, kan de agent reageren met een aanvraag voor goedkeuring, in plaats van de functie rechtstreeks uit te voeren en het resultaat te retourneren. U kunt het antwoord controleren op aanvragen voor gebruikersinvoer. Dit geeft aan dat de agent goedkeuring van de gebruiker voor een functie vereist.

result = await agent.run("What is the detailed weather like in Amsterdam?")

if result.user_input_requests:
    for user_input_needed in result.user_input_requests:
        print(f"Function: {user_input_needed.function_call.name}")
        print(f"Arguments: {user_input_needed.function_call.arguments}")

Als er aanvragen voor functiegoedkeuring zijn, kunt u de details van de functieaanroep, inclusief naam en argumenten, vinden in de function_call eigenschap van de invoeraanvraag van de gebruiker. Dit kan worden weergegeven aan de gebruiker, zodat hij of zij kan bepalen of de functieaanroep moet worden goedgekeurd of geweigerd.

Zodra de gebruiker zijn invoer heeft opgegeven, kunt u een antwoord maken met behulp van de create_response methode voor de invoeraanvraag van de gebruiker. Geef True door om de functie-aanroep goed te keuren of False om deze af te wijzen.

Het antwoord kan vervolgens worden doorgegeven aan de agent in een nieuwe ChatMessage, om het resultaat van de agent terug te ontvangen.

from agent_framework import ChatMessage, Role

# Get user approval (in a real application, this would be interactive)
user_approval = True  # or False to reject

# Create the approval response
approval_message = ChatMessage(
    role=Role.USER, 
    contents=[user_input_needed.create_response(user_approval)]
)

# Continue the conversation with the approval
final_result = await agent.run([
    "What is the detailed weather like in Amsterdam?",
    ChatMessage(role=Role.ASSISTANT, contents=[user_input_needed]),
    approval_message
])
print(final_result.text)

Goedkeuringen verwerken in een lus

Wanneer u werkt met meerdere functie-aanroepen waarvoor goedkeuring is vereist, moet u mogelijk goedkeuringen in een lus verwerken totdat alle functies zijn goedgekeurd of geweigerd:

async def handle_approvals(query: str, agent) -> str:
    """Handle function call approvals in a loop."""
    current_input = query

    while True:
        result = await agent.run(current_input)

        if not result.user_input_requests:
            # No more approvals needed, return the final result
            return result.text

        # Build new input with all context
        new_inputs = [query]

        for user_input_needed in result.user_input_requests:
            print(f"Approval needed for: {user_input_needed.function_call.name}")
            print(f"Arguments: {user_input_needed.function_call.arguments}")

            # Add the assistant message with the approval request
            new_inputs.append(ChatMessage(role=Role.ASSISTANT, contents=[user_input_needed]))

            # Get user approval (in practice, this would be interactive)
            user_approval = True  # Replace with actual user input

            # Add the user's approval response
            new_inputs.append(
                ChatMessage(role=Role.USER, contents=[user_input_needed.create_response(user_approval)])
            )

        # Continue with all the context
        current_input = new_inputs

# Usage
result_text = await handle_approvals("Get detailed weather for Seattle and Portland", agent)
print(result_text)

Wanneer u functietools met menselijke goedkeuringen in de controlelus gebruikt, vergeet niet te controleren op gebruikersinvoer aanvragen in de reactie, nadat elke agent run is voltooid, totdat alle functieaanroepen zijn goedgekeurd of geweigerd.

Volgende stappen

Gestructureerde uitvoer produceren met agents