Použití funkčních nástrojů s lidským schvalováním ve smyčce

Tento návod ukazuje, jak používat funkční nástroje, které vyžadují lidské schválení pomocí agenta, který je založený na službě Azure OpenAI Chat Completion.

Pokud agenti vyžadují jakýkoli uživatelský vstup, například ke schválení volání funkce, označuje se to jako vzor člověk ve smyčce. Spuštění agenta, které vyžaduje vstup uživatele, se dokončí s odpovědí, která označuje, jaký vstup je od uživatele vyžadován, místo dokončení konečné odpovědi. Volající agentu je pak zodpovědný za získání požadovaného vstupu od uživatele a jeho předání zpět agentovi v rámci nového spuštění agenta.

Požadavky

Informace o požadavcích a instalaci balíčků NuGet naleznete v kroku Vytvoření a spuštění jednoduchého agenta v tomto kurzu.

Vytvoření agenta pomocí nástrojů funkcí

Při použití funkcí je možné pro každou funkci označit, jestli před provedením vyžaduje schválení člověkem. To se provádí zabalením AIFunction instance do ApprovalRequiredAIFunction instance.

Tady je příklad jednoduchého funkčního nástroje, který zfalšuje počasí pro dané místo.

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

Chcete-li vytvořit prvek AIFunction a následně jej zabalit do ApprovalRequiredAIFunction, můžete postupovat následovně:

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

Při vytváření agenta nyní můžete poskytnout nástroj funkce vyžadující schválení tím, že předáte seznam nástrojů metodě CreateAIAgent.

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

Vzhledem k tomu, že teď máte funkci, která vyžaduje schválení, může agent odpovědět žádostí o schválení místo toho, aby funkci spouštěl přímo a vrátil výsledek. Obsah odpovědi můžete zkontrolovat pro všechny FunctionApprovalRequestContent instance, což značí, že agent vyžaduje schválení funkce uživatelem.

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

Pokud existují nějaké žádosti o schválení funkce, podrobnosti volání funkce včetně názvu a argumentů lze najít ve FunctionCall vlastnosti instance FunctionApprovalRequestContent . To se může uživateli zobrazit, aby se mohli rozhodnout, jestli se má schválit nebo odmítnout volání funkce. V tomto příkladu předpokládejme, že existuje jeden požadavek.

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

Jakmile uživatel zadá svůj vstup, můžete vytvořit instanci FunctionApprovalResponseContent pomocí metody CreateResponse na FunctionApprovalRequestContent. Schvalte volání funkce předáním true nebo jej odmítněte předáním false.

Obsah odpovědi se pak může předat agentu v nové UserChatMessage, spolu se stejným objektem vlákna, aby se získal výsledek zpět od agenta.

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

Kdykoli používáte funkční nástroje se schvalováním s lidským zapojením, nezapomeňte po každém spuštění agenta zkontrolovat FunctionApprovalRequestContent případy v odpovědi, dokud nebudou všechna volání funkcí schválena nebo odmítnuta.

V tomto kroku kurzu se naučíte, jak používat funkční nástroje, které vyžadují schválení člověkem, za použití agenta.

Pokud agenti vyžadují jakýkoli uživatelský vstup, například ke schválení volání funkce, označuje se to jako vzor člověk ve smyčce. Spuštění agenta, které vyžaduje vstup uživatele, se dokončí s odpovědí, která označuje, jaký vstup je od uživatele vyžadován, místo dokončení konečné odpovědi. Volající agentu je pak zodpovědný za získání požadovaného vstupu od uživatele a jeho předání zpět agentovi v rámci nového spuštění agenta.

Požadavky

Informace o požadavcích a instalaci balíčků Pythonu najdete v části Vytvoření a spuštění jednoduchého agenta v tomto kurzu.

Vytvořte agenta s využitím nástrojů, které vyžadují schválení.

Při použití funkcí je možné pro každou funkci označit, jestli před provedením vyžaduje schválení člověkem. Nastavte parametr approval_mode na "always_require" při použití dekorátoru @ai_function.

Tady je příklad jednoduchého funkčního nástroje, který zfalšuje počasí pro dané místo.

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

K vytvoření funkce, která vyžaduje schválení, můžete použít approval_mode parametr:

@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%."

Při vytváření agenta teď můžete poskytnout schválení vyžadující nástroj funkce agentu předáním seznamu nástrojů konstruktoru ChatAgent .

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

Vzhledem k tomu, že teď máte funkci, která vyžaduje schválení, může agent odpovědět žádostí o schválení místo toho, aby funkci spouštěl přímo a vrátil výsledek. Můžete zkontrolovat odpověď na všechny požadavky na vstup uživatele, což značí, že agent vyžaduje schválení funkce uživatelem.

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

Pokud existují nějaké žádosti o schválení funkce, podrobnosti volání funkce včetně názvu a argumentů lze najít ve function_call vlastnosti žádosti o zadání uživatele. To se může uživateli zobrazit, aby se mohli rozhodnout, jestli se má schválit nebo odmítnout volání funkce.

Jakmile uživatel zadá svůj vstup, můžete vytvořit odpověď pomocí create_response metody v požadavku na vstup uživatele. Schvalte volání funkce předáním True nebo jej odmítněte předáním False.

Odpověď může být předána agentovi v nové ChatMessage, aby agent vrátil výsledek.

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)

Zpracování schvalovacích procesů ve smyčce

Při práci s několika voláními funkcí vyžadujícími schválení může být potřeba zpracovávat schválení v cyklu, dokud nebudou všechny funkce schváleny nebo odmítnuty.

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)

Kdykoli používáte nástroje funkcí s lidským schvalováním ve smyčce, nezapomeňte po každém běhu agenta zkontrolovat uživatelské žádosti o vstup v odpovědi, dokud nebudou všechny volání funkcí schváleny nebo odmítnuty.

Další kroky

Vytváření strukturovaného výstupu pomocí agentů