Использование инструментов функций с утверждениями с участием человека

На этом шаге руководства показано, как использовать инструменты функций, требующие человеческого утверждения с агентом, который построен на службе завершения чата Azure OpenAI.

Когда агентам требуется ввод от пользователя, например, для одобрения вызова функции, это называется шаблоном "человек в процессе". Запуск агента, требующего ввода данных пользователем, будет завершен с ответом, указывающим, какие входные данные требуются от пользователя, вместо завершения с окончательным ответом. Затем вызывающий агент отвечает за получение необходимых входных данных от пользователя и передачу его обратно агенту в рамках нового запуска агента.

Предпосылки

Предварительные требования и установка пакетов NuGet см. в разделе "Создание и запуск простого агента " в этом руководстве.

Создание агента с помощью средств функций

При использовании функций можно указать для каждой функции, требуется ли утверждение человека перед выполнением. Это делается путем обертки экземпляра AIFunction в экземпляр ApprovalRequiredAIFunction.

Вот пример простой функции, которая имитирует получение данных о погоде для указанного местоположения.

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

Чтобы создать AIFunction и затем упаковать его в ApprovalRequiredAIFunction, можно выполнить следующие действия:

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

При создании агента теперь можно указать инструмент, требующий утверждения, передав список инструментов в метод 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]);

Поскольку теперь у вас есть функция, требующая утверждения, агент может ответить с запросом на утверждение, а не выполнять функцию непосредственно и возвращать результат. Вы можете проверить содержимое ответа на наличие любых экземпляров FunctionApprovalRequestContent, указывающих на то, что агенту требуется одобрение пользователя для выполнения функции.

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

Если есть запросы на утверждение функции, подробные сведения о вызове функции, включая имя и аргументы, можно найти в FunctionCall свойстве в экземпляре FunctionApprovalRequestContent . Это можно показать пользователю, чтобы они могли решить, следует ли утвердить или отклонить вызов функции. В этом примере предполагается, что существует один запрос.

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

После предоставления пользователем своих данных, вы можете создать экземпляр FunctionApprovalResponseContent с помощью метода CreateResponse на FunctionApprovalRequestContent. Передайте true , чтобы утвердить вызов функции или false отклонить его.

Затем содержимое ответа можно передать агенту в новом UserChatMessage объекте, а также тот же объект потока, чтобы получить результат от агента.

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

Всякий раз, когда вы используете инструменты функций с утверждениями с участием человека, не забудьте проверить наличие FunctionApprovalRequestContent случаев в ответе после каждого запуска агента, до тех пор, пока все вызовы функций не будут утверждены или отклонены.

На этом шаге руководства показано, как использовать инструменты функций, требующие одобрения человека при содействии агента.

Когда агентам требуется ввод от пользователя, например, для одобрения вызова функции, это называется шаблоном "человек в процессе". Запуск агента, требующего ввода данных пользователем, будет завершен с ответом, указывающим, какие входные данные требуются от пользователя, вместо завершения с окончательным ответом. Затем вызывающий агент отвечает за получение необходимых входных данных от пользователя и передачу его обратно агенту в рамках нового запуска агента.

Предпосылки

Для предварительных требований и установки пакетов Python см. шаг Создание и запуск простого агента в этом учебном пособии.

Создайте агента с инструментами, выполнение функций которых требует утверждения

При использовании функций можно указать для каждой функции, требуется ли утверждение человека перед выполнением. Это делается путем задания параметра approval_mode значением "always_require" при использовании декоратора @ai_function.

Вот пример простой функции, которая имитирует получение данных о погоде для указанного местоположения.

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

Чтобы создать функцию, требующую утверждения, можно использовать approval_mode параметр:

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

При создании агента теперь можно предоставить агенту инструмент функции, требующий утверждения, передав список инструментов в конструктор 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

Поскольку теперь у вас есть функция, требующая утверждения, агент может ответить с запросом на утверждение, а не выполнять функцию непосредственно и возвращать результат. Вы можете проверить ответ на любые запросы на входные данные пользователя, указывающие, что агенту требуется утверждение пользователя для функции.

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

Если есть запросы на утверждение функции, подробные сведения о вызове функции, включая имя и аргументы, можно найти в function_call свойстве в запросе на ввод пользователя. Это можно показать пользователю, чтобы они могли решить, следует ли утвердить или отклонить вызов функции.

Когда пользователь предоставил входные данные, можно создать ответ с помощью create_response метода в запросе на ввод пользователя. Передайте True , чтобы утвердить вызов функции или False отклонить его.

Затем ответ можно передать агенту в новом ChatMessage, чтобы получить результат обратно от агента.

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)

Обработка одобрений в цикле

При работе с несколькими вызовами функций, требующих утверждения, может потребоваться обрабатывать утверждения в цикле, пока все функции не будут утверждены или отклонены:

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)

Всякий раз, когда вы используете инструменты функций с утверждениями с участием человека, не забудьте проверить запросы на ввод от пользователей в ответе после каждого выполнения агента, пока все вызовы функций не будут утверждены или отклонены.

Дальнейшие шаги

Создание структурированных выходных данных с помощью агентов