Human-in-the-Loop com AG-UI

Este tutorial demonstra como implementar fluxos de trabalho de aprovação com pessoas no ciclo com AG-UI em .NET. A implementação do .NET utiliza a Microsoft. Extensions.AI ApprovalRequiredAIFunction e traduz pedidos de aprovação em AG-UI "chamadas de ferramenta cliente" que o cliente gere e responde.

Visão geral

O padrão de aprovação AG-UI C# funciona da seguinte maneira:

1. Servidor: encapsula funções com ApprovalRequiredAIFunction para marcá-las como exigindo aprovação
2. Middleware: interceta FunctionApprovalRequestContent do agente e converte numa chamada de ferramenta de cliente
3. Cliente: Recebe a chamada da ferramenta, exibe a interface de aprovação e envia a resposta de aprovação como resultado do uso da ferramenta
4. Middleware: desempacota a resposta de aprovação e a converte em FunctionApprovalResponseContent
5. Agente: Continua a execução com a decisão de aprovação do usuário

Pré-requisitos

• Recurso Azure OpenAI com um modelo implantado
• Variáveis de ambiente:
  • AZURE_OPENAI_ENDPOINT
  • AZURE_OPENAI_DEPLOYMENT_NAME
• Compreensão da renderização de ferramentas de backend

Implementação do servidor

Definir Ferramenta que Requer Aprovação

Crie uma função e envolva-a com ApprovalRequiredAIFunction:

using System.ComponentModel;
using Microsoft.Extensions.AI;

[Description("Send an email to a recipient.")]
static string SendEmail(
    [Description("The email address to send to")] string to,
    [Description("The subject line")] string subject,
    [Description("The email body")] string body)
{
    return $"Email sent to {to} with subject '{subject}'";
}

// Create approval-required tool
#pragma warning disable MEAI001 // Type is for evaluation purposes only
AITool[] tools = [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(SendEmail))];
#pragma warning restore MEAI001

Criar modelos de aprovação

Defina modelos para a solicitação de aprovação e resposta:

using System.Text.Json.Serialization;

public sealed class ApprovalRequest
{
    [JsonPropertyName("approval_id")]
    public required string ApprovalId { get; init; }

    [JsonPropertyName("function_name")]
    public required string FunctionName { get; init; }

    [JsonPropertyName("function_arguments")]
    public JsonElement? FunctionArguments { get; init; }

    [JsonPropertyName("message")]
    public string? Message { get; init; }
}

public sealed class ApprovalResponse
{
    [JsonPropertyName("approval_id")]
    public required string ApprovalId { get; init; }

    [JsonPropertyName("approved")]
    public required bool Approved { get; init; }
}

[JsonSerializable(typeof(ApprovalRequest))]
[JsonSerializable(typeof(ApprovalResponse))]
[JsonSerializable(typeof(Dictionary<string, object?>))]
internal partial class ApprovalJsonContext : JsonSerializerContext
{
}

Implementar middleware de aprovação

Crie middleware que traduza entre os tipos de aprovação Microsoft.Extensions.AI e o protocolo AG-UI:

Importante

Depois de converter as respostas de aprovação, devem ser removidos do histórico de mensagens a invocação da ferramenta request_approval e seu resultado. Caso contrário, o Azure OpenAI devolverá um erro: "tool_calls deve ser seguido por mensagens das ferramentas para responder a cada 'tool_call_id'".

using System.Runtime.CompilerServices;
using System.Text.Json;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Options;

// Get JsonSerializerOptions from the configured HTTP JSON options
var jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>().Value;

var agent = baseAgent
    .AsBuilder()
    .Use(runFunc: null, runStreamingFunc: (messages, session, options, innerAgent, cancellationToken) =>
        HandleApprovalRequestsMiddleware(
            messages,
            session,
            options,
            innerAgent,
            jsonOptions.SerializerOptions,
            cancellationToken))
    .Build();

static async IAsyncEnumerable<AgentResponseUpdate> HandleApprovalRequestsMiddleware(
    IEnumerable<ChatMessage> messages,
    AgentSession? session,
    AgentRunOptions? options,
    AIAgent innerAgent,
    JsonSerializerOptions jsonSerializerOptions,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    // Process messages: Convert approval responses back to agent format
    var modifiedMessages = ConvertApprovalResponsesToFunctionApprovals(messages, jsonSerializerOptions);

    // Invoke inner agent
    await foreach (var update in innerAgent.RunStreamingAsync(
        modifiedMessages, session, options, cancellationToken))
    {
        // Process updates: Convert approval requests to client tool calls
        await foreach (var processedUpdate in ConvertFunctionApprovalsToToolCalls(update, jsonSerializerOptions))
        {
            yield return processedUpdate;
        }
    }

    // Local function: Convert approval responses from client back to FunctionApprovalResponseContent
    static IEnumerable<ChatMessage> ConvertApprovalResponsesToFunctionApprovals(
        IEnumerable<ChatMessage> messages,
        JsonSerializerOptions jsonSerializerOptions)
    {
        // Look for "request_approval" tool calls and their matching results
        Dictionary<string, FunctionCallContent> approvalToolCalls = [];
        FunctionResultContent? approvalResult = null;

        foreach (var message in messages)
        {
            foreach (var content in message.Contents)
            {
                if (content is FunctionCallContent { Name: "request_approval" } toolCall)
                {
                    approvalToolCalls[toolCall.CallId] = toolCall;
                }
                else if (content is FunctionResultContent result && approvalToolCalls.ContainsKey(result.CallId))
                {
                    approvalResult = result;
                }
            }
        }

        // If no approval response found, return messages unchanged
        if (approvalResult == null)
        {
            return messages;
        }

        // Deserialize the approval response
        if ((approvalResult.Result as JsonElement?)?.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalResponse))) is not ApprovalResponse response)
        {
            return messages;
        }

        // Extract the original function call details from the approval request
        var originalToolCall = approvalToolCalls[approvalResult.CallId];

        if (originalToolCall.Arguments?.TryGetValue("request", out JsonElement request) != true ||
            request.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalRequest))) is not ApprovalRequest approvalRequest)
        {
            return messages;
        }

        // Deserialize the function arguments from JsonElement
        var functionArguments = approvalRequest.FunctionArguments is { } args
            ? (Dictionary<string, object?>?)args.Deserialize(
                jsonSerializerOptions.GetTypeInfo(typeof(Dictionary<string, object?>)))
            : null;

        var originalFunctionCall = new FunctionCallContent(
            callId: response.ApprovalId,
            name: approvalRequest.FunctionName,
            arguments: functionArguments);

        var functionApprovalResponse = new FunctionApprovalResponseContent(
            response.ApprovalId,
            response.Approved,
            originalFunctionCall);

        // Replace/remove the approval-related messages
        List<ChatMessage> newMessages = [];
        foreach (var message in messages)
        {
            bool hasApprovalResult = false;
            bool hasApprovalRequest = false;

            foreach (var content in message.Contents)
            {
                if (content is FunctionResultContent { CallId: var callId } && callId == approvalResult.CallId)
                {
                    hasApprovalResult = true;
                    break;
                }
                if (content is FunctionCallContent { Name: "request_approval", CallId: var reqCallId } && reqCallId == approvalResult.CallId)
                {
                    hasApprovalRequest = true;
                    break;
                }
            }

            if (hasApprovalResult)
            {
                // Replace tool result with approval response
                newMessages.Add(new ChatMessage(ChatRole.User, [functionApprovalResponse]));
            }
            else if (hasApprovalRequest)
            {
                // Skip the request_approval tool call message
                continue;
            }
            else
            {
                newMessages.Add(message);
            }
        }

        return newMessages;
    }

    // Local function: Convert FunctionApprovalRequestContent to client tool calls
    static async IAsyncEnumerable<AgentResponseUpdate> ConvertFunctionApprovalsToToolCalls(
        AgentResponseUpdate update,
        JsonSerializerOptions jsonSerializerOptions)
    {
        // Check if this update contains a FunctionApprovalRequestContent
        FunctionApprovalRequestContent? approvalRequestContent = null;
        foreach (var content in update.Contents)
        {
            if (content is FunctionApprovalRequestContent request)
            {
                approvalRequestContent = request;
                break;
            }
        }

        // If no approval request, yield the update unchanged
        if (approvalRequestContent == null)
        {
            yield return update;
            yield break;
        }

        // Convert the approval request to a "client tool call"
        var functionCall = approvalRequestContent.FunctionCall;
        var approvalId = approvalRequestContent.Id;

        // Serialize the function arguments as JsonElement
        var argsElement = functionCall.Arguments?.Count > 0
            ? JsonSerializer.SerializeToElement(functionCall.Arguments, jsonSerializerOptions.GetTypeInfo(typeof(IDictionary<string, object?>)))
            : (JsonElement?)null;

        var approvalData = new ApprovalRequest
        {
            ApprovalId = approvalId,
            FunctionName = functionCall.Name,
            FunctionArguments = argsElement,
            Message = $"Approve execution of '{functionCall.Name}'?"
        };

        var approvalJson = JsonSerializer.Serialize(approvalData, jsonSerializerOptions.GetTypeInfo(typeof(ApprovalRequest)));

        // Yield a tool call update that represents the approval request
        yield return new AgentResponseUpdate(ChatRole.Assistant, [
            new FunctionCallContent(
                callId: approvalId,
                name: "request_approval",
                arguments: new Dictionary<string, object?> { ["request"] = approvalJson })
        ]);
    }
}

Implementação do Cliente

Implementar middleware do lado do cliente

O cliente requer middleware bidirecional que lida com ambos:

1. Entrada: Convertendo request_approval chamadas de ferramentas em FunctionApprovalRequestContent
2. Saída: Convertendo FunctionApprovalResponseContent de volta em resultados da ferramenta

Importante

Use AdditionalProperties em AIContent objetos para controlar a correlação entre solicitações de aprovação e respostas, evitando dicionários de estado externos.

using System.Runtime.CompilerServices;
using System.Text.Json;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.AGUI;
using Microsoft.Extensions.AI;

// Get JsonSerializerOptions from the client
var jsonSerializerOptions = JsonSerializerOptions.Default;

#pragma warning disable MEAI001 // Type is for evaluation purposes only
// Wrap the agent with approval middleware
var wrappedAgent = agent
    .AsBuilder()
    .Use(runFunc: null, runStreamingFunc: (messages, session, options, innerAgent, cancellationToken) =>
        HandleApprovalRequestsClientMiddleware(
            messages,
            session,
            options,
            innerAgent,
            jsonSerializerOptions,
            cancellationToken))
    .Build();

static async IAsyncEnumerable<AgentResponseUpdate> HandleApprovalRequestsClientMiddleware(
    IEnumerable<ChatMessage> messages,
    AgentSession? session,
    AgentRunOptions? options,
    AIAgent innerAgent,
    JsonSerializerOptions jsonSerializerOptions,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    // Process messages: Convert approval responses back to tool results
    var processedMessages = ConvertApprovalResponsesToToolResults(messages, jsonSerializerOptions);

    // Invoke inner agent
    await foreach (var update in innerAgent.RunStreamingAsync(processedMessages, session, options, cancellationToken))
    {
        // Process updates: Convert tool calls to approval requests
        await foreach (var processedUpdate in ConvertToolCallsToApprovalRequests(update, jsonSerializerOptions))
        {
            yield return processedUpdate;
        }
    }

    // Local function: Convert FunctionApprovalResponseContent back to tool results
    static IEnumerable<ChatMessage> ConvertApprovalResponsesToToolResults(
        IEnumerable<ChatMessage> messages,
        JsonSerializerOptions jsonSerializerOptions)
    {
        List<ChatMessage> processedMessages = [];

        foreach (var message in messages)
        {
            List<AIContent> convertedContents = [];
            bool hasApprovalResponse = false;

            foreach (var content in message.Contents)
            {
                if (content is FunctionApprovalResponseContent approvalResponse)
                {
                    hasApprovalResponse = true;

                    // Get the original request_approval CallId from AdditionalProperties
                    if (approvalResponse.AdditionalProperties?.TryGetValue("request_approval_call_id", out string? requestApprovalCallId) == true)
                    {
                        var response = new ApprovalResponse
                        {
                            ApprovalId = approvalResponse.Id,
                            Approved = approvalResponse.Approved
                        };

                        var responseJson = JsonSerializer.SerializeToElement(response, jsonSerializerOptions.GetTypeInfo(typeof(ApprovalResponse)));

                        var toolResult = new FunctionResultContent(
                            callId: requestApprovalCallId,
                            result: responseJson);

                        convertedContents.Add(toolResult);
                    }
                }
                else
                {
                    convertedContents.Add(content);
                }
            }

            if (hasApprovalResponse && convertedContents.Count > 0)
            {
                processedMessages.Add(new ChatMessage(ChatRole.Tool, convertedContents));
            }
            else
            {
                processedMessages.Add(message);
            }
        }

        return processedMessages;
    }

    // Local function: Convert request_approval tool calls to FunctionApprovalRequestContent
    static async IAsyncEnumerable<AgentResponseUpdate> ConvertToolCallsToApprovalRequests(
        AgentResponseUpdate update,
        JsonSerializerOptions jsonSerializerOptions)
    {
        FunctionCallContent? approvalToolCall = null;
        foreach (var content in update.Contents)
        {
            if (content is FunctionCallContent { Name: "request_approval" } toolCall)
            {
                approvalToolCall = toolCall;
                break;
            }
        }

        if (approvalToolCall == null)
        {
            yield return update;
            yield break;
        }

        if (approvalToolCall.Arguments?.TryGetValue("request", out JsonElement request) != true ||
            request.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalRequest))) is not ApprovalRequest approvalRequest)
        {
            yield return update;
            yield break;
        }

        var functionArguments = approvalRequest.FunctionArguments is { } args
            ? (Dictionary<string, object?>?)args.Deserialize(
                jsonSerializerOptions.GetTypeInfo(typeof(Dictionary<string, object?>)))
            : null;

        var originalFunctionCall = new FunctionCallContent(
            callId: approvalRequest.ApprovalId,
            name: approvalRequest.FunctionName,
            arguments: functionArguments);

        // Yield the original tool call first (for message history)
        yield return new AgentResponseUpdate(ChatRole.Assistant, [approvalToolCall]);

        // Create approval request with CallId stored in AdditionalProperties
        var approvalRequestContent = new FunctionApprovalRequestContent(
            approvalRequest.ApprovalId,
            originalFunctionCall);

        // Store the request_approval CallId in AdditionalProperties for later retrieval
        approvalRequestContent.AdditionalProperties ??= new Dictionary<string, object?>();
        approvalRequestContent.AdditionalProperties["request_approval_call_id"] = approvalToolCall.CallId;

        yield return new AgentResponseUpdate(ChatRole.Assistant, [approvalRequestContent]);
    }
}
#pragma warning restore MEAI001

Lidar com solicitações de aprovação e enviar respostas

O código de consumo processa as solicitações de aprovação e continua automaticamente até que não sejam necessárias mais aprovações:

Lidar com solicitações de aprovação e enviar respostas

O código de consumo processa solicitações de aprovação. Ao receber um FunctionApprovalRequestContent, armazene o request_approval CallId em AdditionalProperties da resposta:

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

#pragma warning disable MEAI001 // Type is for evaluation purposes only
List<AIContent> approvalResponses = [];
List<FunctionCallContent> approvalToolCalls = [];

do
{
    approvalResponses.Clear();
    approvalToolCalls.Clear();

    await foreach (AgentResponseUpdate update in wrappedAgent.RunStreamingAsync(
        messages, session, cancellationToken: cancellationToken))
    {
        foreach (AIContent content in update.Contents)
        {
            if (content is FunctionApprovalRequestContent approvalRequest)
            {
                DisplayApprovalRequest(approvalRequest);

                // Get user approval
                Console.Write($"\nApprove '{approvalRequest.FunctionCall.Name}'? (yes/no): ");
                string? userInput = Console.ReadLine();
                bool approved = userInput?.ToUpperInvariant() is "YES" or "Y";

                // Create approval response and preserve the request_approval CallId
                var approvalResponse = approvalRequest.CreateResponse(approved);

                // Copy AdditionalProperties to preserve the request_approval_call_id
                if (approvalRequest.AdditionalProperties != null)
                {
                    approvalResponse.AdditionalProperties ??= new Dictionary<string, object?>();
                    foreach (var kvp in approvalRequest.AdditionalProperties)
                    {
                        approvalResponse.AdditionalProperties[kvp.Key] = kvp.Value;
                    }
                }

                approvalResponses.Add(approvalResponse);
            }
            else if (content is FunctionCallContent { Name: "request_approval" } requestApprovalCall)
            {
                // Track the original request_approval tool call
                approvalToolCalls.Add(requestApprovalCall);
            }
            else if (content is TextContent textContent)
            {
                Console.Write(textContent.Text);
            }
        }
    }

    // Add both messages in correct order
    if (approvalResponses.Count > 0 && approvalToolCalls.Count > 0)
    {
        messages.Add(new ChatMessage(ChatRole.Assistant, approvalToolCalls.ToArray()));
        messages.Add(new ChatMessage(ChatRole.User, approvalResponses.ToArray()));
    }
}
while (approvalResponses.Count > 0);
#pragma warning restore MEAI001

static void DisplayApprovalRequest(FunctionApprovalRequestContent approvalRequest)
{
    Console.WriteLine();
    Console.WriteLine("============================================================");
    Console.WriteLine("APPROVAL REQUIRED");
    Console.WriteLine("============================================================");
    Console.WriteLine($"Function: {approvalRequest.FunctionCall.Name}");

    if (approvalRequest.FunctionCall.Arguments != null)
    {
        Console.WriteLine("Arguments:");
        foreach (var arg in approvalRequest.FunctionCall.Arguments)
        {
            Console.WriteLine($"  {arg.Key} = {arg.Value}");
        }
    }

    Console.WriteLine("============================================================");
}

Exemplo de interação

User (:q or quit to exit): Send an email to user@example.com about the meeting

[Run Started - Thread: thread_abc123, Run: run_xyz789]

============================================================
APPROVAL REQUIRED
============================================================

Function: SendEmail
Arguments: {"to":"user@example.com","subject":"Meeting","body":"..."}
Message: Approve execution of 'SendEmail'?

============================================================

[Waiting for approval to execute SendEmail...]
[Run Finished - Thread: thread_abc123]

Approve this action? (yes/no): yes

[Sending approval response: APPROVED]

[Run Resumed - Thread: thread_abc123]
Email sent to user@example.com with subject 'Meeting'
[Run Finished]

Conceitos-chave

Padrão de Ferramenta do Cliente

A implementação do C# usa um padrão de "chamada de ferramenta do cliente":

• Solicitação de aprovação → chamada de ferramenta nomeada "request_approval" com detalhes de aprovação
• Resposta de aprovação → resultado da ferramenta contendo a decisão do usuário
• Middleware → Faz a tradução entre os tipos da Microsoft.Extensions.AI e o protocolo AG-UI

Isso permite que o padrão padrão ApprovalRequiredAIFunction funcione através do limite HTTP+SSE, mantendo a consistência com o modelo de aprovação da estrutura do agente.

Padrão de middleware bidirecional

O middleware do servidor e do cliente segue um padrão consistente de três etapas:

1. Processar mensagens: transformar mensagens recebidas (respostas de aprovação → FunctionApprovalResponseContent ou resultados da ferramenta)
2. Invoque o agente interno: chame o agente interno com mensagens processadas
3. Atualizações de processo: transforme atualizações de saída (FunctionApprovalRequestContent para chamadas de ferramenta ou vice-versa)

Rastreamento de estado com AdditionalProperties

Em vez de dicionários externos, a implementação usa AdditionalProperties em AIContent objetos para rastrear metadados:

• Cliente: Armazena request_approval_call_id em FunctionApprovalRequestContent.AdditionalProperties
• Preservação da resposta: Copia AdditionalProperties da solicitação para a resposta para manter a correlação
• Conversão: usa o CallId armazenado para criar uma correlação correta FunctionResultContent

Isso mantém todos os dados de correlação dentro dos próprios objetos de conteúdo, evitando a necessidade de gerenciamento de estado externo.

Limpeza de mensagens Server-Side

O middleware do servidor deve remover mensagens de protocolo de aprovação após o processamento:

• Problema: A Azure OpenAI exige que todas as chamadas de ferramentas tenham resultados correspondentes
• Solução: depois de converter as respostas de aprovação, remova a chamada da ferramenta request_approval e a mensagem de resultado
• Motivo: Evita erros de "chamadas_da_ferramenta devem ser seguidas por mensagens de ferramenta"

Passos seguintes

Compatibilidade de Aplicações MCP

Este tutorial mostra como implementar fluxos de trabalho human-in-the-loop com AG-UI, onde os usuários devem aprovar execuções de ferramentas antes que elas sejam executadas. Isso é essencial para operações sensíveis, como transações financeiras, modificações de dados ou ações que tenham consequências significativas.

Pré-requisitos

Antes de começar, certifique-se de ter concluído o tutorial de renderização da ferramenta de back-end e entenda:

• Como criar ferramentas de função
• Como AG-UI transmite eventos da ferramenta
• Configuração básica do servidor e do cliente

O que é Human-in-the-Loop?

Human-in-the-Loop (HITL) é um padrão em que o agente solicita a aprovação do usuário antes de executar determinadas operações. Com AG-UI:

• O agente gera chamadas de ferramenta de forma habitual
• Em vez de executar imediatamente, o servidor envia solicitações de aprovação para o cliente
• O cliente exibe a solicitação e solicita ao usuário
• O usuário aprova ou rejeita a ação
• O servidor recebe a resposta e procede em conformidade

Benefícios

• Segurança: Evitar que ações não intencionais sejam executadas
• Transparência: os usuários veem exatamente o que o agente quer fazer
• Controlo: os utilizadores têm a última palavra sobre operações sensíveis
• Conformidade: Atender aos requisitos regulatórios para supervisão humana

Ferramentas de marcação para aprovação

Para exigir a aprovação de uma ferramenta, use o approval_mode parâmetro no decorador @tool.

from agent_framework import tool
from typing import Annotated
from pydantic import Field


@tool(approval_mode="always_require")
def send_email(
    to: Annotated[str, Field(description="Email recipient address")],
    subject: Annotated[str, Field(description="Email subject line")],
    body: Annotated[str, Field(description="Email body content")],
) -> str:
    """Send an email to the specified recipient."""
    # Send email logic here
    return f"Email sent to {to} with subject '{subject}'"


@tool(approval_mode="always_require")
def delete_file(
    filepath: Annotated[str, Field(description="Path to the file to delete")],
) -> str:
    """Delete a file from the filesystem."""
    # Delete file logic here
    return f"File {filepath} has been deleted"

Modos de aprovação

• always_require: Solicite sempre a aprovação antes da execução
• never_require: Nunca solicite aprovação (comportamento padrão)
• conditional: Solicitar aprovação com base em determinadas condições (lógica personalizada)

Criando um servidor com Human-in-the-Loop

Aqui está uma implementação completa do servidor com ferramentas necessárias para aprovação:

"""AG-UI server with human-in-the-loop."""

import os
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework_ag_ui import AgentFrameworkAgent, add_agent_framework_fastapi_endpoint
from azure.identity import AzureCliCredential
from fastapi import FastAPI
from pydantic import Field


# Tools that require approval
@tool(approval_mode="always_require")
def transfer_money(
    from_account: Annotated[str, Field(description="Source account number")],
    to_account: Annotated[str, Field(description="Destination account number")],
    amount: Annotated[float, Field(description="Amount to transfer")],
    currency: Annotated[str, Field(description="Currency code")] = "USD",
) -> str:
    """Transfer money between accounts."""
    return f"Transferred {amount} {currency} from {from_account} to {to_account}"


@tool(approval_mode="always_require")
def cancel_subscription(
    subscription_id: Annotated[str, Field(description="Subscription identifier")],
) -> str:
    """Cancel a subscription."""
    return f"Subscription {subscription_id} has been cancelled"


# Regular tools (no approval required)
@tool
def check_balance(
    account: Annotated[str, Field(description="Account number")],
) -> str:
    """Check account balance."""
    # Simulated balance check
    return f"Account {account} balance: $5,432.10 USD"


# Read required configuration
endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
deployment_name = os.environ.get("AZURE_OPENAI_CHAT_COMPLETION_MODEL")

if not endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is required")
if not deployment_name:
    raise ValueError("AZURE_OPENAI_CHAT_COMPLETION_MODEL environment variable is required")

chat_client = OpenAIChatCompletionClient(
    model=deployment_name,
    azure_endpoint=endpoint,
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

# Create agent with tools
agent = Agent(
    name="BankingAssistant",
    instructions="You are a banking assistant. Help users with their banking needs. Always confirm details before performing transfers.",
    client=chat_client,
    tools=[transfer_money, cancel_subscription, check_balance],
)

# Wrap agent to enable human-in-the-loop
wrapped_agent = AgentFrameworkAgent(
    agent=agent,
    require_confirmation=True,  # Enable human-in-the-loop
)

# Create FastAPI app
app = FastAPI(title="AG-UI Banking Assistant")
add_agent_framework_fastapi_endpoint(app, wrapped_agent, "/")

if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="127.0.0.1", port=8888)

Conceitos-chave

• AgentFrameworkAgent wrapper: Habilita funcionalidades do protocolo AG-UI, como human-in-the-loop
• require_confirmation=True: Ativa o fluxo de trabalho de aprovação para ferramentas marcadas
• Controle no nível da ferramenta: somente as ferramentas marcadas com approval_mode="always_require" solicitarão aprovação

Noções básicas sobre eventos de aprovação

Quando uma ferramenta requer aprovação, o cliente recebe estes eventos:

Evento de solicitação de aprovação

{
    "type": "APPROVAL_REQUEST",
    "approvalId": "approval_abc123",
    "steps": [
        {
            "toolCallId": "call_xyz789",
            "toolCallName": "transfer_money",
            "arguments": {
                "from_account": "1234567890",
                "to_account": "0987654321",
                "amount": 500.00,
                "currency": "USD"
            }
        }
    ],
    "message": "Do you approve the following actions?"
}

Formato de resposta de aprovação

O cliente deve enviar uma resposta de aprovação:

# Approve
{
    "type": "APPROVAL_RESPONSE",
    "approvalId": "approval_abc123",
    "approved": True
}

# Reject
{
    "type": "APPROVAL_RESPONSE",
    "approvalId": "approval_abc123",
    "approved": False
}

Cliente com Suporte de Aprovação

Aqui está um cliente usando AGUIChatClient que lida com solicitações de aprovação:

"""AG-UI client with human-in-the-loop support."""

import asyncio
import os

from agent_framework import Agent, ToolCallContent, ToolResultContent
from agent_framework_ag_ui import AGUIChatClient


def display_approval_request(update) -> None:
    """Display approval request details to the user."""
    print("\n\033[93m" + "=" * 60 + "\033[0m")
    print("\033[93mAPPROVAL REQUIRED\033[0m")
    print("\033[93m" + "=" * 60 + "\033[0m")

    # Display tool call details from update contents
    for i, content in enumerate(update.contents, 1):
        if isinstance(content, ToolCallContent):
            print(f"\nAction {i}:")
            print(f"  Tool: \033[95m{content.name}\033[0m")
            print(f"  Arguments:")
            for key, value in (content.arguments or {}).items():
                print(f"    {key}: {value}")

    print("\n\033[93m" + "=" * 60 + "\033[0m")


async def main():
    """Main client loop with approval handling."""
    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:8888/")
    print(f"Connecting to AG-UI server at: {server_url}\n")

    # Create AG-UI chat client
    chat_client = AGUIChatClient(server_url=server_url)

    # Create agent with the chat client
    agent = Agent(
        name="ClientAgent",
        client=chat_client,
        instructions="You are a helpful assistant.",
    )

    # Get a thread for conversation continuity
    thread = agent.create_session()

    try:
        while True:
            message = input("\nUser (:q or quit to exit): ")
            if not message.strip():
                continue

            if message.lower() in (":q", "quit"):
                break

            print("\nAssistant: ", end="", flush=True)
            pending_approval_update = None

            async for update in agent.run(message, session=thread, stream=True):
                # Check if this is an approval request
                # (Approval requests are detected by specific metadata or content markers)
                if update.additional_properties and update.additional_properties.get("requires_approval"):
                    pending_approval_update = update
                    display_approval_request(update)
                    break  # Exit the loop to handle approval

                elif event_type == "RUN_FINISHED":
                    print(f"\n\033[92m[Run Finished]\033[0m")

                elif event_type == "RUN_ERROR":
                    error_msg = event.get("message", "Unknown error")
                    print(f"\n\033[91m[Error: {error_msg}]\033[0m")

            # Handle approval request
            if pending_approval:
                approval_id = pending_approval.get("approvalId")
                user_choice = input("\nApprove this action? (yes/no): ").strip().lower()
                approved = user_choice in ("yes", "y")

                print(f"\n\033[93m[Sending approval response: {approved}]\033[0m\n")

                async for event in client.send_approval_response(approval_id, approved):
                    event_type = event.get("type", "")

                    if event_type == "TEXT_MESSAGE_CONTENT":
                        print(f"\033[96m{event.get('delta', '')}\033[0m", end="", flush=True)

                    elif event_type == "TOOL_CALL_RESULT":
                        content = event.get("content", "")
                        print(f"\033[94m[Tool Result: {content}]\033[0m")

                    elif event_type == "RUN_FINISHED":
                        print(f"\n\033[92m[Run Finished]\033[0m")

                    elif event_type == "RUN_ERROR":
                        error_msg = event.get("message", "Unknown error")
                        print(f"\n\033[91m[Error: {error_msg}]\033[0m")

            print()

    except KeyboardInterrupt:
        print("\n\nExiting...")
    except Exception as e:
        print(f"\n\033[91mError: {e}\033[0m")


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

Exemplo de interação

Com o servidor e o cliente em execução:

User (:q or quit to exit): Transfer $500 from account 1234567890 to account 0987654321

[Run Started]
============================================================
APPROVAL REQUIRED
============================================================

Action 1:
  Tool: transfer_money
  Arguments:
    from_account: 1234567890
    to_account: 0987654321
    amount: 500.0
    currency: USD

============================================================

Approve this action? (yes/no): yes

[Sending approval response: True]

[Tool Result: Transferred 500.0 USD from 1234567890 to 0987654321]
The transfer of $500 from account 1234567890 to account 0987654321 has been completed successfully.
[Run Finished]

Se o usuário rejeitar:

Approve this action? (yes/no): no

[Sending approval response: False]

I understand. The transfer has been cancelled and no money was moved.
[Run Finished]

Mensagens de confirmação personalizadas

Você pode personalizar as mensagens de aprovação fornecendo uma estratégia de confirmação personalizada:

from typing import Any
from agent_framework_ag_ui import AgentFrameworkAgent, ConfirmationStrategy


class BankingConfirmationStrategy(ConfirmationStrategy):
    """Custom confirmation messages for banking operations."""

    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
        """Message when user approves the action."""
        tool_name = steps[0].get("toolCallName", "action")
        return f"Thank you for confirming. Proceeding with {tool_name}..."

    def on_approval_rejected(self, steps: list[dict[str, Any]]) -> str:
        """Message when user rejects the action."""
        return "Action cancelled. No changes have been made to your account."

    def on_state_confirmed(self) -> str:
        """Message when state changes are confirmed."""
        return "Changes confirmed and applied."

    def on_state_rejected(self) -> str:
        """Message when state changes are rejected."""
        return "Changes discarded."


# Use custom strategy
wrapped_agent = AgentFrameworkAgent(
    agent=agent,
    require_confirmation=True,
    confirmation_strategy=BankingConfirmationStrategy(),
)

Melhores práticas

Limpar descrições de ferramentas

Forneça descrições detalhadas para que os usuários entendam o que estão aprovando:

@tool(approval_mode="always_require")
def delete_database(
    database_name: Annotated[str, Field(description="Name of the database to permanently delete")],
) -> str:
    """
    Permanently delete a database and all its contents.

    WARNING: This action cannot be undone. All data in the database will be lost.
    Use with extreme caution.
    """
    # Implementation
    pass

Aprovação granular

Solicitar aprovação para ações sensíveis individuais em vez de lotes:

# Good: Individual approval per transfer
@tool(approval_mode="always_require")
def transfer_money(...): pass

# Avoid: Batching multiple sensitive operations
# Users should approve each operation separately

Argumentos informativos

Use nomes de parâmetros descritivos e forneça contexto:

@tool(approval_mode="always_require")
def purchase_item(
    item_name: Annotated[str, Field(description="Name of the item to purchase")],
    quantity: Annotated[int, Field(description="Number of items to purchase")],
    price_per_item: Annotated[float, Field(description="Price per item in USD")],
    total_cost: Annotated[float, Field(description="Total cost including tax and shipping")],
) -> str:
    """Purchase items from the store."""
    pass

Gestão de tempo limite

Defina tempos limite apropriados para solicitações de aprovação:

# Client side
async with httpx.AsyncClient(timeout=120.0) as client:  # 2 minutes for user to respond
    # Handle approval
    pass

Aprovação seletiva

Você pode misturar ferramentas que exigem aprovação com aquelas que não exigem:

# No approval needed for read-only operations
@tool
def get_account_balance(...): pass

@tool
def list_transactions(...): pass

# Approval required for write operations
@tool(approval_mode="always_require")
def transfer_funds(...): pass

@tool(approval_mode="always_require")
def close_account(...): pass

Passos seguintes

Compatibilidade de Aplicações MCP

Recursos adicionais

• Visão geral do AG-UI
• Renderização de ferramentas de back-end
• Ferramentas de funcionalidade com aprovações