Funkcióeszközök használata emberi jóváhagyással a folyamatban

Ez az oktatóanyag lépés bemutatja, hogyan használhat olyan függvényeszközöket, amelyek emberi jóváhagyást igényelnek egy ügynök segítségével, ahol az ügynök az Azure OpenAI Chat Completion szolgáltatásra épül.

Ha az ügynökök bármilyen felhasználói bemenetet igényelnek, például egy függvényhívás jóváhagyásához, akkor ezt ember által vezérelt mintának nevezzük. A felhasználói bemenetet igénylő ügynökfuttatás egy válaszsal fejeződik be, amely jelzi, hogy milyen bemenetre van szükség a felhasználótól, ahelyett, hogy végleges választ adna. Ezután az ügynök hívója felelős a szükséges bemenetek begyűjtéséért a felhasználótól, majd ezeket az ügynöknek adja vissza egy új ügynökfolyamat részeként.

Prerequisites

Az előfeltételekről és a NuGet-csomagok telepítéséről lásd az egyszerű ügynök létrehozása és futtatása lépést ebben az oktatóanyagban.

Az ügynök létrehozása funkcióeszközökkel

Függvények használatakor minden egyes függvény esetében jelezhető, hogy a végrehajtás előtt emberi jóváhagyásra van-e szükség. Ez úgy történik, hogy a AIFunction példányt egy ApprovalRequiredAIFunction példányba ágyazzuk.

Íme egy példa egy egyszerű függvényeszközre, amely meghamisít egy adott hely időjárását.

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

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

Ha létre szeretne hozni egy AIFunction elemet, majd be szeretné tördelni egybe ApprovalRequiredAIFunction, az alábbiakat teheti:

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

Az ügynök létrehozásakor most már biztosíthatja az ügynök számára a jóváhagyást igénylő függvényeszközt, ha átad egy eszközlistát a AsAIAgent metódusnak.

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
     .AsAIAgent(
        model: "gpt-4o-mini",
        instructions: "You are a helpful assistant",
        tools: [approvalRequiredWeatherFunction]);

Warning

DefaultAzureCredential a fejlesztéshez kényelmes, de a termelési környezetben gondos megfontolást igényel. Éles környezetben fontolja meg egy adott hitelesítő adat (pl. ManagedIdentityCredential) használatát a késési problémák elkerülése, a hitelesítő adatok nem szándékos próbálgatásának és a tartalék mechanizmusokból eredő esetleges biztonsági kockázatok elkerülése érdekében.

Mivel most már rendelkezik egy jóváhagyást igénylő függvénnyel, az ügynök ahelyett, hogy közvetlenül hajtja végre a függvényt, és visszaadja az eredményt, egy jóváhagyási kéréssel válaszolhat. A válasz tartalmát bármely ToolApprovalRequestContent példány esetében ellenőrizheti, ami azt jelzi, hogy az ügynöknek felhasználói jóváhagyásra van szüksége egy függvényhez.

AgentSession session = await agent.CreateSessionAsync();
AgentResponse response = await agent.RunAsync("What is the weather like in Amsterdam?", session);

var toolApprovalRequests = response.Messages
    .SelectMany(x => x.Contents)
    .OfType<ToolApprovalRequestContent>()
    .ToList();

Ha vannak függvényjóváhagyási kérelmek, a függvényhívás a nevével és argumentumaival együtt elérhető a ToolApprovalRequestContent példány ToolCall tulajdonságában. Ez megjeleníthető a felhasználó számára, hogy eldönthesse, jóváhagyja vagy elutasítja-e a függvényhívást. Ebben a példában tegyük fel, hogy van egy kérés.

ToolApprovalRequestContent requestContent = toolApprovalRequests.First();
var functionCall = (FunctionCallContent)requestContent.ToolCall;
Console.WriteLine($"We require approval to execute '{functionCall.Name}'");

Miután a felhasználó megadta a bemenetét, használja a CreateResponse metódust ToolApprovalRequestContent a jóváhagyási válasz létrehozásához. A függvényhívás jóváhagyásához adja meg a true értéket, vagy az elutasításhoz a false értéket.

A válasz tartalma ezután átadható az ügynöknek egy új UserChatMessage részeként, ugyanazzal a munkamenet objektummal együtt, hogy az eredmény visszakerüljön az ügynöktől.

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

Amikor függvényeszközöket használ emberi felülvizsgálattal történő jóváhagyásokkal, ne felejtse el ellenőrizni a válaszban szereplő ToolApprovalRequestContent példányokat minden ügynöki futtatást követően, amíg az összes függvényhívást jóvá nem hagyják vagy el nem utasítják.

Tip

Tekintse meg a .NET-ügynökök 01. lépéssel kapcsolatos példát: Függvényeszközök használata jóváhagyásokkal egy teljes és futtatható példát.

Ez az oktatóanyag lépés bemutatja, hogyan használhat olyan funkció eszközöket, amelyek emberi jóváhagyást igényelnek egy ügynök segítségével.

Ha az ügynökök bármilyen felhasználói bemenetet igényelnek, például egy függvényhívás jóváhagyásához, akkor ezt ember által vezérelt mintának nevezzük. A felhasználói bemenetet igénylő ügynökfuttatás egy válaszsal fejeződik be, amely jelzi, hogy milyen bemenetre van szükség a felhasználótól, ahelyett, hogy végleges választ adna. Ezután az ügynök hívója felelős a szükséges bemenetek begyűjtéséért a felhasználótól, majd ezeket az ügynöknek adja vissza egy új ügynökfolyamat részeként.

Prerequisites

Az előfeltételekről és a Python-csomagok telepítéséről lásd a Hozzon létre és futtasson egy egyszerű ügynököt lépést ebben az oktatóanyagban.

Az ügynök létrehozása jóváhagyást igénylő funkcionális eszközökkel.

Függvények használatakor minden egyes függvény esetében jelezhető, hogy a végrehajtás előtt emberi jóváhagyásra van-e szükség. Ez úgy történik, hogy a approval_mode paramétert "always_require" állítja be, amikor a @tool dekorátort használja.

Íme egy példa egy egyszerű függvényeszközre, amely meghamisít egy adott hely időjárását.

from typing import Annotated
from agent_framework import tool

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

Jóváhagyást igénylő függvény létrehozásához használja a következő paramétert approval_mode :

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

Az ügynök létrehozásakor most már megadhatja az ügynöknek a jóváhagyást igénylő funkció eszközt, egy lista átadásával a Agent konstruktornak.

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

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

Mivel most már rendelkezik egy jóváhagyást igénylő függvénnyel, az ügynök ahelyett, hogy közvetlenül hajtja végre a függvényt, és visszaadja az eredményt, egy jóváhagyási kéréssel válaszolhat. Minden felhasználói bemeneti kérés esetében ellenőrizheti a választ, ami azt jelzi, hogy az ügynöknek felhasználói jóváhagyásra van szüksége egy függvényhez.

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

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

Ha vannak függvény-jóváhagyási kérések, a függvényhívás részletei, beleértve a nevet és az argumentumokat, megtalálhatók a function_call felhasználói beviteli kérelem tulajdonságában. Ez megjeleníthető a felhasználó számára, hogy eldönthesse, jóváhagyja vagy elutasítja-e a függvényhívást.

Miután a felhasználó megadta a bemenetét, a felhasználói beviteli to_function_approval_response kérelem metódusával hozhat létre választ. A függvényhívás jóváhagyásához adja meg a True értéket, vagy az elutasításhoz a False értéket.

Folytassa a futtatást a jóváhagyási válasszal és ugyanazzal a AgentSession elemmel:

from agent_framework import Message

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

# Create the approval response
approval_message = Message(
    role="user",
    contents=[user_input_needed.to_function_approval_response(user_approval)]
)

# Continue the conversation with the approval
final_result = await agent.run(approval_message, session=session)
print(final_result.text)

Jóváhagyások kezelése ciklusban

Ha több, jóváhagyást igénylő függvényhívással dolgozik, előfordulhat, hogy a jóváhagyásokat egy ciklusban kell kezelnie, amíg az összes függvényt nem hagyja jóvá vagy nem utasítja el:

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

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

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

        # Build the approval responses for the requests stored in the session.
        new_inputs = []

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

            # 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(
                Message(role="user", contents=[user_input_needed.to_function_approval_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)

Amikor olyan függvényeszközöket használ, amelyek emberi felügyeletet igényelnek a jóváhagyások során, ne felejtse el ellenőrizni a felhasználói bemeneti kéréseket a válaszban, minden modul futtatása után, amíg az összes függvényhívást jóvá nem hagyják vagy el nem utasítják.

Important

Alapértelmezés szerint a helyi jóváhagyási válasz csak akkor engedélyezi az eszközhívást, ha az megegyezik az ugyanabban AgentSessionrögzített függőben lévő jóváhagyási kérelemmel. A keretrendszer figyelmen kívül hagy egy nem kötött választ, és figyelmeztetést ír a naplóba. Beállítás client.function_invocation_configuration["disable_approval_response_binding"] = True csak akkor, ha az alkalmazás egyenértékű kötést kényszerít ki, mielőtt az üzenetek elérnék az ügynököt. Ez a kikapcsolási lehetőség visszaállítja a korábbi, nem kötött működést, és lehetővé teheti, hogy egy meghamisított vagy újrajátszott válasz jóváhagyjon egy privilegizált eszközhívást.

A jóváhagyási és biztonsági köztes szoftver támogatja a Konvertált Python-paramétertípusok használata című részben leírt konvertált Python-paramétertípusokat. Ha a köztes szoftver már jóváhagyott argumentumokat módosít, az Ügynök-keretrendszer csak akkor hoz létre helyettesítő jóváhagyási kérelmet, ha a módosított értékek szerializálhatók JSON-ra, és újraérvényesíthetők, és ugyanazokat az értékeket adják. Ha ez a pontos oda-vissza út nem lehetséges, a hívás MiddlewareFailure zárt módon meghiúsul a jóváhagyás újbóli felhasználása vagy egy újabb jóváhagyás ismételt kérése helyett. Az approval binding megbízik a pontos, nem módosítható konvertált típusokban, valamint az időzóna nélküli vagy rögzített eltolású dátum- vagy időértékekben. Az egyéni alosztályok és más időzóna-implementációk zárt állapotban hibásodnak meg.

Teljes példa

# Copyright (c) Microsoft. All rights reserved.

import asyncio
from random import randrange
from typing import TYPE_CHECKING, Annotated, Any

from agent_framework import Agent, AgentResponse, Message, tool
from agent_framework.openai import OpenAIChatClient

if TYPE_CHECKING:
    from agent_framework import AgentSession, SupportsAgentRun

"""
Demonstration of a tool with approvals.

This sample demonstrates using AI functions with user approval workflows.
It shows how to handle function call approvals without using threads.
"""

conditions = ["sunny", "cloudy", "raining", "snowing", "clear"]


# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
def get_weather(location: Annotated[str, "The city and state, e.g. San Francisco, CA"]) -> str:
    """Get the current weather for a given location."""
    # Simulate weather data
    return f"The weather in {location} is {conditions[randrange(0, len(conditions))]} and {randrange(-10, 30)}°C."


# Define a simple weather tool that requires approval
@tool(approval_mode="always_require")
def get_weather_detail(location: Annotated[str, "The city and state, e.g. San Francisco, CA"]) -> str:
    """Get the current weather for a given location."""
    # Simulate weather data
    return (
        f"The weather in {location} is {conditions[randrange(0, len(conditions))]} and {randrange(-10, 30)}°C, "
        "with a humidity of 88%. "
        f"Tomorrow will be {conditions[randrange(0, len(conditions))]} with a high of {randrange(-10, 30)}°C."
    )


async def handle_approvals(
    query: str,
    agent: "SupportsAgentRun",
    session: "AgentSession",
) -> AgentResponse:
    """Handle function call approvals with an authoritative session."""
    result = await agent.run(query, session=session)
    while len(result.user_input_requests) > 0:
        new_inputs: list[Any] = []

        for user_input_needed in result.user_input_requests:
            print(
                f"\nUser Input Request for function from {agent.name}:"
                f"\n  Function: {user_input_needed.function_call.name}"
                f"\n  Arguments: {user_input_needed.function_call.arguments}"
            )

            # Get user approval
            user_approval = await asyncio.to_thread(input, "\nApprove function call? (y/n): ")

            # Add the user's approval response
            new_inputs.append(
                Message("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
            )

        result = await agent.run(new_inputs, session=session)

    return result


async def handle_approvals_streaming(
    query: str,
    agent: "SupportsAgentRun",
    session: "AgentSession",
) -> None:
    """Handle streaming function approvals with an authoritative session."""
    current_input: str | list[Any] = query
    has_user_input_requests = True
    while has_user_input_requests:
        has_user_input_requests = False
        user_input_requests: list[Any] = []

        # Stream the response
        async for chunk in agent.run(current_input, stream=True, session=session):
            if chunk.text:
                print(chunk.text, end="", flush=True)

            # Collect user input requests from the stream
            if chunk.user_input_requests:
                user_input_requests.extend(chunk.user_input_requests)

        if user_input_requests:
            has_user_input_requests = True
            new_inputs: list[Any] = []

            for user_input_needed in user_input_requests:
                print(
                    f"\n\nUser Input Request for function from {agent.name}:"
                    f"\n  Function: {user_input_needed.function_call.name}"
                    f"\n  Arguments: {user_input_needed.function_call.arguments}"
                )

                # Get user approval
                user_approval = await asyncio.to_thread(input, "\nApprove function call? (y/n): ")

                # Add the user's approval response
                new_inputs.append(
                    Message("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
                )

            # Update input with all the context for next iteration
            current_input = new_inputs


async def run_weather_agent_with_approval(stream: bool) -> None:
    """Example showing AI function with approval requirement."""
    print(f"\n=== Weather Agent with Approval Required ({'Streaming' if stream else 'Non-Streaming'}) ===\n")

    async with Agent(
        client=OpenAIChatClient(),
        name="WeatherAgent",
        instructions=("You are a helpful weather assistant. Use the get_weather tool to provide weather information."),
        tools=[get_weather, get_weather_detail],
    ) as agent:
        session = agent.create_session()
        query = "Can you give me an update of the weather in LA and Portland and detailed weather for Seattle?"
        print(f"User: {query}")

        if stream:
            print(f"\n{agent.name}: ", end="", flush=True)
            await handle_approvals_streaming(query, agent, session)
            print()
        else:
            result = await handle_approvals(query, agent, session)
            print(f"\n{agent.name}: {result}\n")


async def main() -> None:
    print("=== Demonstration of a tool with approvals ===\n")

    await run_weather_agent_with_approval(stream=False)
    await run_weather_agent_with_approval(stream=True)


if __name__ == "__main__":
    asyncio.run(main())

Eszköz jóváhagyása

Az eszköz végrehajtása előtt emberi jóváhagyást kérhet, ha a következővel tool.ApprovalRequiredFuncburkolja:

import "github.com/microsoft/agent-framework-go/tool"

approvedWeatherTool := tool.ApprovalRequiredFunc(weatherTool)

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Tools: []tool.Tool{approvedWeatherTool},
    },
})

Amikor a modell eszközhívást kér, a keretrendszer elfogja, és a végrehajtás előtt megvárja a jóváhagyást. A jóváhagyási folyamat közbenső szoftveren keresztül történik.

Az eszközjóváhagyás használata a Harness Agenttel

Az egyszerű/manuális összeállításhoz jóváhagyással megjelölt eszközre és jóváhagyási-válasz ciklusra van szükség. A Harness Agent ugyanazokat a jóváhagyottként megjelölt eszközöket és választartalmat használja, de middleware-t is telepít a sorba állított kérésekhez, az állandó „mindig jóváhagy” szabályokhoz és az opcionális heurisztikus automatikus jóváhagyáshoz.

A jóváhagyást igénylő függvényeket foglalja a(z) ApprovalRequiredAIFunction elembe, majd adja hozzá őket a(z) HarnessAgentOptions.ChatOptions.Tools segítségével:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var weatherTool = new ApprovalRequiredAIFunction(
    AIFunctionFactory.Create(GetWeather));

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a helpful assistant.",
        Tools = [weatherTool],
    },
});

AgentSession session = await agent.CreateSessionAsync();
AgentResponse response = await agent.RunAsync(
    "What is the weather like in Amsterdam?",
    session);

DisableToolAutoApproval alapértelmezett érték, falseígy a hám hozzáadja ToolApprovalAgent. Az alapértelmezett beállításnál ToolApprovalAgentOptionsnincs heurisztikus szabály konfigurálva; a nem egyező ToolApprovalRequestContent elemek továbbra is visszatérnek a hívóhoz jóváhagyás céljából. Megbízható automatikus jóváhagyási visszahívások hozzáadásához állítsa be a következőt ToolApprovalAgentOptions.AutoApprovalRules:

A(z) DisableToolAutoApproval = true beállítása csak az állandó szabályalapú, a sorba állítási és a heurisztikus automatikus jóváhagyási köztes szoftvert távolítja el. Nem szünteti meg a jóváhagyási követelményt egy ApprovalRequiredAIFunction esetében. A jóváhagyás–válasz összerendelése és a jóváhagyást nem igénylő eszközök megkerülése is alapértelmezés szerint engedélyezve marad; külön letiltási lehetőségeik: DisableApprovalResponseBinding és DisableApprovalNotRequiredFunctionBypassing.

Jelölje meg az eszközt a(z) approval_mode="always_require" jellel, majd adja át a(z) create_harness_agent részére:

from agent_framework import create_harness_agent, tool

@tool(approval_mode="always_require")
def get_weather_detail(location: str) -> str:
    """Get detailed weather information for a location."""
    return f"The weather in {location} is cloudy with a high of 15°C."

agent = create_harness_agent(
    client=client,
    agent_instructions="You are a helpful weather assistant.",
    tools=get_weather_detail,
)

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

disable_tool_auto_approval=False alapértelmezés szerint hozzáadja a(z) ToolApprovalMiddleware elemet. A köztes réteg megköveteli ugyanannak a AgentSession-nak a használatát a jóváhagyási körök során, több kérést sorba állít, alkalmazza a felhasználó korábbi válaszai alapján már érvényben lévő jóváhagyásokat, és kiértékeli a auto_approval_rules elemet, mielőtt visszaadná a kérést a hívónak. A auto_approval_rules=None használatával egyetlen heurisztikus visszahívási függvény sem hagy jóvá automatikusan egy hívást.

Az állandó jóváhagyások továbbra is AgentSession állapotban maradnak. Nem kötődnek az őket létrehozó ügynökhöz vagy eszközpéldányhoz. Az azonos nevű csereeszköz, beleértve az MCP-eszközt is, illeszkedhet egy mentett eszközszintű vagy argumentumspecifikus szabályhoz. Korlátozza a munkameneteket stabil megbízhatósági határra. Tekintse át a mentett szabályokat, amikor az ügynök vagy az eszközkészlet megváltozik, és indítson új munkamenetet, amikor a jóváhagyás ne legyen érvényes a következő munkamenetre.

A(z) disable_tool_auto_approval=True beállítás eltávolítja azt a harness middleware-t, de nem módosítja az eszköz approval_mode értékét; a normál result.user_input_requests jóváhagyási folyamat továbbra is érvényes.

A csomagolt Go-hám jelenleg nem érhető el. A jóváhagyást igénylő eszközöket foglalja tool.ApprovalRequiredFunc közé, és közvetlenül állítsa össze a jóváhagyási middleware-t.

Következő lépések

Kódértelmező