azureaicommunity-agent-approval 0.1.0

Human-in-the-loop approval gate middleware for AI agent tool calls

🔐 AzureAICommunity - Agent - Approval Middleware

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

Getting Started · Callback Contract · How It Works · Contributing

---

Overview

azureaicommunity-agent-approval adds an approval gate directly into the agent-framework 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 FunctionInvocationContext; 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.

This mirrors the pattern established by the C# ApprovalMiddleware in the AzureAICommunity Agent Framework.

---

✨ Features

	Feature
🎯	Selective gating — only the tools you specify are intercepted; others run freely
🔔	Simple callback — receives the full FunctionInvocationContext with tool name and arguments
💬	LLM-aware denial — when denied, a descriptive message is set as the tool result so the model can reason about the refusal
🖥️	UI agnostic — use any approval UI: console, GUI, HTTP, webhooks
🔀	Sync & async callbacks — both synchronous and asynchronous callbacks are supported
🔗	Composable — stacks with other agent-framework middleware in the same pipeline

---

📦 Installation

pip install azureaicommunity-agent-approval

Or install directly from source:

cd AgentFramework/Python/Middleware/ApprovalMiddleware
pip install -e .

---

🚀 Quick Start

import asyncio
from agent_framework import tool, FunctionInvocationContext
from agent_framework.openai import OpenAIChatCompletionClient
from approval_middleware import ApprovalMiddleware


@tool
def get_device_status(device_name: str) -> str:
    """Get the current status of a smart-home device. Does not change device state."""
    return f"{device_name} is currently OFF."


@tool
def turn_on_device(device_name: str) -> str:
    """Turn on a smart-home device."""
    return f"{device_name} is now ON."


@tool
def turn_off_device(device_name: str) -> str:
    """Turn off a smart-home device."""
    return f"{device_name} is now OFF."


async def console_approve(context: FunctionInvocationContext) -> bool | None:
    print(f"\n[Approval Required] Tool: {context.function.name}")
    answer = input("  Allow? [y/N] ").strip().lower()
    return answer == "y"


async def main():
    client = OpenAIChatCompletionClient(model="gpt-4o", api_key="...", base_url="...")

    # Only the destructive tools are gated.
    # get_device_status is intentionally omitted — it runs freely without prompting.
    middleware = ApprovalMiddleware(
        approval_tools=["turn_on_device", "turn_off_device"],
        approval_callback=console_approve,
    )

    agent = client.as_agent(
        name="HomeAssistant",
        instructions="You are a helpful smart-home assistant.",
        tools=[get_device_status, turn_on_device, turn_off_device],
        middleware=[middleware],
    )

    response = await agent.run(
        "Check the living room lights, then turn them on and turn off the bedroom fan."
    )
    print(response.text)


asyncio.run(main())

---

🔔 Callback Contract

The approval_callback receives the full FunctionInvocationContext.

Return value	Effect
True	Approved — the tool executes and its real result is returned to the LLM
False or None	Denied — a denial message is set as the tool result so the LLM can reason about the refusal

The callback can be sync or async — both are supported automatically:

# Async callback
async def my_callback(context: FunctionInvocationContext) -> bool | None:
    # context.function.name  — tool name
    # context.arguments      — validated arguments (dict or Pydantic model)
    return True   # approve
    return False  # deny
    return None   # deny

# Sync callback
def my_callback(context: FunctionInvocationContext) -> bool | None:
    return True

---

⚙️ Configuration

ApprovalMiddleware

Parameter	Type	Default	Description
approval_tools	list[str]	required	Tool names that require approval before execution
approval_callback	Callable[[FunctionInvocationContext], bool | None]	required	Sync or async callback invoked before each gated tool call
denial_message	str	"User denied the call to '{tool_name}'."	Template string for the denial result. Use {tool_name} as a placeholder

---

⚙️ How It Works

LLM decides to call a tool
    └─► FunctionInvocationContext intercepted by ApprovalMiddleware
            │
            ├─ tool name in approval_tools?
            │       ├─ YES → approval_callback(context) called
            │       │           ├─ returns True         → call_next()  ← tool executes normally
            │       │           └─ returns False/None   → context.result = denial message
            │       └─ NO  → call_next()    ← tool executes freely, no approval prompt
            │
            └─ agent continues with the result

---

🤝 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