Freigeben über

Verwenden von Funktionstools mit menschlichen Genehmigungen im Loop

In diesem Schritt des Tutorials wird gezeigt, wie Sie Funktionstools verwenden, die eine menschliche Genehmigung durch einen Agenten erfordern, bei dem der Agent auf dem Azure OpenAI Chat Completion Service basiert.

Wenn Agents eine Benutzereingabe erfordern, z. B. zum Genehmigen eines Funktionsaufrufs, wird dies als "Human-in-the-Loop"-Muster bezeichnet. Ein Agentenlauf, der eine Benutzereingabe erfordert, liefert eine Antwort, die angibt, welche Eingabe vom Benutzer erforderlich ist, anstatt mit einer endgültigen Antwort abzuschließen. Der Anrufer des Agents ist dann dafür verantwortlich, die erforderlichen Eingaben vom Benutzer zu erhalten und sie im Rahmen eines neuen Agentendurchlaufs an den Agenten zurückzugeben.

Voraussetzungen

Die erforderlichen Komponenten und die Installation von NuGet-Paketen finden Sie im Schritt Erstellen und Ausführen eines einfachen Agents in diesem Lernprogramm.

Erstellung des Agenten mit Funktionstools

Bei der Verwendung von Funktionen ist es möglich, für jede Funktion anzugeben, ob sie eine menschliche Genehmigung erfordert, bevor sie ausgeführt wird. Dazu wird die AIFunction Instanz in eine ApprovalRequiredAIFunction Instanz umschlossen.

Hier ist ein Beispiel für ein einfaches Funktionstool, das das Wetter für einen bestimmten Ort fälscht.

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

Gehen Sie wie folgt vor, um eine Datei AIFunction zu erstellen und dann in eine ApprovalRequiredAIFunctionumzuschließen:

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

Beim Erstellen des Agents können Sie jetzt dem Agenten ein Funktionstool bereitstellen, das eine Genehmigung erfordert, indem Sie eine Liste von Tools an die CreateAIAgent-Methode übergeben.

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

Da Sie jetzt über eine Funktion verfügen, die eine Genehmigung erfordert, antwortet der Agent möglicherweise mit einer Genehmigungsanforderung, anstatt die Funktion direkt auszuführen und das Ergebnis zurückzugeben. Sie können den Antwortinhalt für alle FunctionApprovalRequestContent Instanzen überprüfen, was angibt, dass der Agent eine Benutzergenehmigung für eine Funktion erfordert.

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

Wenn Funktionsgenehmigungsanforderungen vorhanden sind, finden Sie die Details des Funktionsaufrufs einschließlich Name und Argumente in der FunctionCall Eigenschaft der FunctionApprovalRequestContent Instanz. Dies kann dem Benutzer angezeigt werden, damit er entscheiden kann, ob der Funktionsaufruf genehmigt oder abgelehnt werden soll. Gehen Sie in diesem Beispiel davon aus, dass eine Anforderung vorhanden ist.

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

Nachdem der Benutzer seine Eingabe bereitgestellt hat, können Sie eine FunctionApprovalResponseContent Instanz mithilfe der CreateResponse Methode auf dem/der FunctionApprovalRequestContent erstellen. Übergeben Sie true, um den Funktionsaufruf zu genehmigen, oder false, um ihn abzulehnen.

Der Antwortinhalt kann dann in einem neuen UserChatMessagezusammen mit demselben Thread-Objekt an den Agenten übergeben werden, um das Ergebnis vom Agenten abzurufen.

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

Wenn Sie Funktionstools mit menschlichen Genehmigungen im Prozess verwenden, denken Sie daran, nach jedem Agentenlauf nach FunctionApprovalRequestContent-Instanzen in der Antwort zu suchen, bis alle Funktionsaufrufe genehmigt oder abgelehnt wurden.

In diesem Schritt des Tutorials erfahren Sie, wie Sie Funktionen verwenden, die eine menschliche Genehmigung durch einen Agenten erfordern.

Wenn Agents eine Benutzereingabe erfordern, z. B. zum Genehmigen eines Funktionsaufrufs, wird dies als "Human-in-the-Loop"-Muster bezeichnet. Ein Agentenlauf, der eine Benutzereingabe erfordert, liefert eine Antwort, die angibt, welche Eingabe vom Benutzer erforderlich ist, anstatt mit einer endgültigen Antwort abzuschließen. Der Anrufer des Agents ist dann dafür verantwortlich, die erforderlichen Eingaben vom Benutzer zu erhalten und sie im Rahmen eines neuen Agentendurchlaufs an den Agenten zurückzugeben.

Voraussetzungen

Die erforderlichen Komponenten und die Installation von Python-Paketen finden Sie im Abschnitt zum Erstellen und Ausführen eines einfachen Agent-Schritts in diesem Lernprogramm.

Erstellen des Agents mit Funktionstools, die eine Genehmigung erfordern

Bei der Verwendung von Funktionen ist es möglich, für jede Funktion anzugeben, ob sie eine menschliche Genehmigung erfordert, bevor sie ausgeführt wird. Dies geschieht durch Setzen des approval_mode Parameters auf "always_require", wenn der @ai_function Dekorator verwendet wird.

Hier ist ein Beispiel für ein einfaches Funktionstool, das das Wetter für einen bestimmten Ort fälscht.

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

Um eine Funktion zu erstellen, die eine Genehmigung erfordert, können Sie den approval_mode Parameter verwenden:

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

Beim Erstellen des Agents können Sie nun das Genehmigung erfordernde Funktionstool bereitstellen, indem Sie dem ChatAgent-Konstruktor eine Liste von Tools übergeben.

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

Da Sie jetzt über eine Funktion verfügen, die eine Genehmigung erfordert, antwortet der Agent möglicherweise mit einer Genehmigungsanforderung, anstatt die Funktion direkt auszuführen und das Ergebnis zurückzugeben. Sie können die Antwort auf alle Benutzereingabeanforderungen überprüfen, was angibt, dass der Agent eine Benutzergenehmigung für eine Funktion erfordert.

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

Wenn Funktionsgenehmigungsanforderungen vorhanden sind, finden Sie die Details des Funktionsaufrufs einschließlich Name und Argumente in der function_call Eigenschaft für die Benutzereingabeanforderung. Dies kann dem Benutzer angezeigt werden, damit er entscheiden kann, ob der Funktionsaufruf genehmigt oder abgelehnt werden soll.

Nachdem der Benutzer seine Eingabe bereitgestellt hat, können Sie eine Antwort mithilfe der create_response Methode für die Benutzereingabeanforderung erstellen. Übergeben Sie True, um den Funktionsaufruf zu genehmigen, oder False, um ihn abzulehnen.

Die Antwort kann dann an den Agent in einem neuen ChatMessageübergeben werden, um das Ergebnis vom Agent zurück zu erhalten.

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)

Genehmigungen in einer Schleife bearbeiten

Wenn Sie mit mehreren Funktionsaufrufen arbeiten, die eine Genehmigung erfordern, müssen Sie möglicherweise Genehmigungen in einer Schleife verarbeiten, bis alle Funktionen genehmigt oder abgelehnt werden:

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)

Wenn Sie Funktionstools mit menschlichen Genehmigungen im Genehmigungsprozess verwenden, denken Sie daran, nach jedem Agentendurchlauf im Antwortfeld nach Benutzereingaben zu suchen, bis alle Funktionsaufrufe genehmigt oder abgelehnt wurden.

Nächste Schritte

Erstellen einer strukturierten Ausgabe mit Agents

  • Last updated on