AzureAICommunity.Agent.Middleware.ApprovalMiddleware 1.1.0

<div align="center">

🔐 AzureAICommunity - Agent - Approval Middleware

Add a human-in-the-loop approval gate to AI agent tool calls with a single method call.

Getting Started · Callback Contract · How It Works · Contributing

</div>

Overview

AzureAICommunity.Agent.Middleware.ApprovalMiddleware adds an approval gate directly into the AIAgentBuilder function-invocation pipeline. You pass only the tools that need approval — all other tools registered on the agent execute freely without interruption. Before any gated tool executes, your callback is called with the pending FunctionCallContent; you decide whether to approve or deny using any UI: console, desktop dialog, HTTP call to a remote approver, etc. The middleware itself contains no UI code.

✨ Features

📦 Installation

dotnet add package AzureAICommunity.Agent.Middleware.ApprovalMiddleware

🚀 Quick Start

using AzureAICommunity.Agent.Middleware.ApprovalMiddleware;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Read-only tool — no approval needed
var getStatusTool = AIFunctionFactory.Create(GetDeviceStatus);

// Destructive tools — require approval before executing
var turnOnTool  = AIFunctionFactory.Create(TurnOnDevice);
var turnOffTool = AIFunctionFactory.Create(TurnOffDevice);

// All tools are registered on the agent
AIAgent baseAgent = new ChatClientAgent(
    chatClient,
    instructions: "You are a helpful smart-home assistant.",
    tools: [getStatusTool, turnOnTool, turnOffTool]);

// Only the destructive tools are passed to UseApprovalMiddleware.
// GetDeviceStatus is intentionally omitted — it bypasses the approval gate.
AIAgent agent = new AIAgentBuilder(baseAgent)
    .UseApprovalMiddleware(
        [turnOnTool, turnOffTool],
        async fc =>
        {
            // Return true          → approved
            // Return false or null → denied, a denial message is returned to the LLM
            Console.Write($"Allow '{fc.Name}'? (y/n): ");
            bool approved = Console.ReadLine()?.Trim() == "y";
            return (bool?)approved;
        },
        denialMessageFactory: fc => fc.Name switch
        {
            "TurnOnDevice"  => $"User refused to turn ON '{fc.Arguments?["deviceName"]}'. Do not retry.",
            "TurnOffDevice" => $"User refused to turn OFF '{fc.Arguments?["deviceName"]}'. Do not retry.",
            _               => $"User refused '{fc.Name}'. Do not retry this action."
        })
    .Build();

// Gate ALL tools — no list needed
AIAgent agentGateAll = new AIAgentBuilder(baseAgent)
    .UseApprovalMiddleware(async fc =>
    {
        Console.Write($"Allow '{fc.Name}'? (y/n): ");
        return (bool?)(Console.ReadLine()?.Trim() == "y");
    })
    .Build();

AgentResponse response = await agent.RunAsync("Check the lights, then turn them on.");
Console.WriteLine(response);

🔔 Callback Contract

The approvalCallback receives a FunctionCallContent with the tool name and arguments.

The callback is Func<FunctionCallContent, Task<bool?>>, so it can be async and use any UI or remote call.

⚙️ How It Works

LLM decides to call a tool
    └─► FunctionInvocationContext intercepted by ApprovalMiddleware
            │
            ├─ gate-all mode OR tool name in approvalTools?
            │       ├─ YES → approvalCallback(FunctionCallContent) called
            │       │           ├─ returns true         → next(context, ct)  ← tool executes normally
            │       │           └─ returns false/null   → denialMessageFactory(fc) → text returned to LLM
            │       └─ NO  → next(context, ct)    ← tool executes freely, no approval prompt
            │
            └─ agent continues with the result

📋 Type Reference

Extension methods

// Overload 1 — gate specific tools
builder.UseApprovalMiddleware(
    IEnumerable<AITool> approvalTools,                        // Tools that require approval
    Func<FunctionCallContent, Task<bool?>> approvalCallback,  // Approval decision callback
    Func<FunctionCallContent, string>? denialMessageFactory = null  // Optional: custom denial text
);

// Overload 2 — gate ALL tools
builder.UseApprovalMiddleware(
    Func<FunctionCallContent, Task<bool?>> approvalCallback,  // Approval decision callback
    Func<FunctionCallContent, string>? denialMessageFactory = null  // Optional: custom denial text
);

denialMessageFactory

Optional factory that produces the text returned to the LLM as the tool result when a call is denied. Receives the FunctionCallContent of the denied call. If omitted, defaults to "User denied the call to '{name}'.".

denialMessageFactory: fc => fc.Name switch
{
    "TurnOnDevice"  => $"User refused to turn ON '{fc.Arguments?["deviceName"]}'. Do not retry.",
    "TurnOffDevice" => $"User refused to turn OFF '{fc.Arguments?["deviceName"]}'. Do not retry.",
    _               => $"User refused '{fc.Name}'. Do not retry this action."
}

🤝 Contributing

Contributions are welcome! Please open an issue to discuss what you'd like to change before submitting a pull request.

📁 Repository: https://github.com/rvinothrajendran/AgentFramework

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

👤 Author

Built and maintained by Vinoth Rajendran.

• 🐙 GitHub: github.com/rvinothrajendran — follow for more projects!
• 📺 YouTube: youtube.com/@VinothRajendran — subscribe for tutorials and demos!
• 💼 LinkedIn: linkedin.com/in/rvinothrajendran — let's connect!

📄 License

MIT