Usando ferramentas funcionais com aprovações humanas integradas

Esta etapa do tutorial mostra-lhe como usar ferramentas funcionais que exigem aprovação humana com um agente, onde o agente é desenvolvido no serviço de Conclusão de Conversação do Azure OpenAI.

Quando os agentes exigem qualquer entrada do usuário, por exemplo, para aprovar uma chamada de função, isso é chamado de padrão human-in-the-loop. Uma execução de agente que requer entrada do usuário, será concluída com uma resposta que indica qual entrada é necessária do usuário, em vez de completar com uma resposta final. O chamador do agente é então responsável por obter a entrada necessária do usuário e passá-la de volta para o agente como parte de uma nova execução do agente.

Pré-requisitos

Para obter pré-requisitos e instalar pacotes NuGet, consulte a etapa Criar e executar um agente simples neste tutorial.

Criar o agente com ferramentas funcionais

Ao usar funções, é possível indicar, para cada função, se ela requer aprovação humana antes de ser executada. Isso é feito encapsulando a AIFunction instância em uma ApprovalRequiredAIFunction instância.

Aqui está um exemplo de uma simples ferramenta de funções que finge obter o clima para um determinado local.

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

Para criar um AIFunction e, em seguida, envolvê-lo em um ApprovalRequiredAIFunction, você pode fazer o seguinte:

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

Ao criar o agente, agora você pode fornecer a ferramenta de função que requer aprovação para o agente, passando uma lista de ferramentas para o CreateAIAgent método.

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

Como agora você tem uma função que requer aprovação, o agente pode responder com uma solicitação de aprovação, em vez de executar a função diretamente e retornar o resultado. Você pode verificar o conteúdo da resposta para qualquer FunctionApprovalRequestContent instância, o que indica que o agente requer aprovação do usuário para uma função.

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

Se houver alguma solicitação de aprovação de função, os detalhes da chamada de função, incluindo nome e argumentos, podem ser encontrados na FunctionCall propriedade na FunctionApprovalRequestContent instância. Isso pode ser mostrado ao usuário, para que ele possa decidir se aprova ou rejeita a chamada de função. Para este exemplo, suponha que haja uma solicitação.

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

Depois que o usuário tiver fornecido sua entrada, você poderá criar uma FunctionApprovalResponseContent instância usando o CreateResponse método no FunctionApprovalRequestContent. Passe true para aprovar a chamada de função ou false rejeitá-la.

O conteúdo da resposta pode então ser passado para o agente em um novo UserChatMessage, juntamente com o mesmo objeto de thread para recuperar o resultado do agente.

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

Sempre que estiveres a usar ferramentas funcionais com aprovações humanas em fluxo contínuo, lembra-te de verificar se há instâncias de FunctionApprovalRequestContent na resposta, após cada execução do agente, até que todas as chamadas de função tenham sido aprovadas ou rejeitadas.

Esta etapa do tutorial mostra como usar ferramentas de função que exigem aprovação humana com um agente.

Quando os agentes exigem qualquer entrada do usuário, por exemplo, para aprovar uma chamada de função, isso é chamado de padrão human-in-the-loop. Uma execução de agente que requer entrada do usuário, será concluída com uma resposta que indica qual entrada é necessária do usuário, em vez de completar com uma resposta final. O chamador do agente é então responsável por obter a entrada necessária do usuário e passá-la de volta para o agente como parte de uma nova execução do agente.

Pré-requisitos

Para pré-requisitos e instalação de pacotes Python, consulte a etapa Criar e executar um agente simples neste tutorial.

Criar o agente com ferramentas funcionais que exigem aprovação

Ao usar funções, é possível indicar, para cada função, se ela requer aprovação humana antes de ser executada. Isso é feito definindo o approval_mode parâmetro para "always_require" ao usar o @ai_function decorador.

Aqui está um exemplo de uma simples ferramenta de funções que finge obter o clima para um determinado local.

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

Para criar uma função que requer aprovação, você pode usar o approval_mode parâmetro:

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

Ao criar o agente, pode-se agora fornecer a ferramenta relacionada a funções que requerem aprovação ao agente, passando uma lista de ferramentas para o ChatAgent construtor.

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

Como agora você tem uma função que requer aprovação, o agente pode responder com uma solicitação de aprovação, em vez de executar a função diretamente e retornar o resultado. Você pode verificar a resposta para quaisquer solicitações de entrada do usuário, o que indica que o agente requer aprovação do usuário para uma função.

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

Se houver alguma solicitação de aprovação de função, os detalhes da chamada de função, incluindo nome e argumentos, podem ser encontrados na function_call propriedade na solicitação de entrada do usuário. Isso pode ser mostrado ao usuário, para que ele possa decidir se aprova ou rejeita a chamada de função.

Depois que o usuário tiver fornecido sua entrada, você pode criar uma resposta usando o create_response método na solicitação de entrada do usuário. Passe True para aprovar a chamada de função ou False rejeitá-la.

A resposta pode então ser passada para o agente num novo ChatMessage, para recuperar o resultado do agente.

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)

Gerir aprovações num loop

Ao trabalhar com várias chamadas de função que exigem aprovação, talvez seja necessário lidar com aprovações em um loop até que todas as funções sejam aprovadas ou rejeitadas:

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)

Sempre que você estiver usando ferramentas de função com aprovações humanas no loop, lembre-se de verificar se há solicitações de entrada do usuário na resposta, após cada execução do agente, até que todas as chamadas de função tenham sido aprovadas ou rejeitadas.