Principle:Microsoft Agent framework Approval Request Detection

Template:Microsoft Agent framework Sidebar

Overview

Approval Request Detection is a pattern for determining when an agent's response contains pending tool approval requests that must be resolved before the agent can continue execution. After running an agent configured with approval-mode tools, the AgentResponse.user_input_requests property returns a list of Content objects of type "function_approval_request" that represent pending tool calls awaiting human decision.

Property	Value
Category	Agent Architecture, Safety
Source	python/packages/core/agent_framework/_types.py (lines L2341-2348)
API	AgentResponse.user_input_requests property
Import	Access via AgentResponse returned from agent.run()
Related Implementation	AgentResponse User Input Requests

Description

When an agent is configured with tools that require human approval (e.g., via approval_mode="always_require" on the @tool decorator), the LLM may generate tool calls that are intercepted before execution. Rather than executing these tool calls immediately, the framework pauses and marks them as pending approval requests within the agent's response.

The AgentResponse.user_input_requests property provides a clean, filtered view of these pending requests. It scans the response's message list and returns only those Content objects where user_input_request is True. This allows the caller to quickly determine whether the agent is waiting for human intervention without manually iterating through the full message history.

Theoretical Basis

The Human-in-the-Loop Gate

In safety-critical agent workflows, certain tool invocations must not proceed without explicit human authorization. The Approval Request Detection pattern implements a gate in the agent execution pipeline: the agent proposes an action (a tool call), the framework intercepts it before execution, and the human operator inspects and either approves or rejects the proposal.

This pattern decouples the intent to use a tool (the LLM's decision) from the authorization to use it (the human's decision), creating an explicit checkpoint in the execution flow.

Detection via Property Filtering

The detection mechanism works by filtering the response's messages for Content objects that have their user_input_request flag set to True. Each such object represents one pending tool call and carries:

• .id: A unique request identifier used to correlate approval or rejection decisions back to the specific pending call.
• .function_call: A nested Content object containing .name (the tool name) and .arguments (the serialized arguments the LLM proposed), allowing the human reviewer to inspect exactly what the agent intends to do.
• .user_input_request: Always True for these objects, serving as the filter predicate.

Non-Empty Check as Control Flow

The idiomatic usage pattern is a truthiness check on the returned list:

result = await agent.run("Delete all old records")
if result.user_input_requests:
    # Agent is waiting for approval -- present requests to user
    ...
else:
    # Agent completed without needing approval
    print(result.text)

When the list is non-empty, the caller knows the agent cannot proceed until each request is resolved (approved or rejected). When the list is empty, the agent has completed its execution normally.

Multiple Pending Requests

A single agent turn may produce multiple tool calls that each require approval. The user_input_requests property returns all of them in a single list, allowing the caller to present a batch of approval decisions to the human operator. Each request is independent and can be approved or rejected individually.

Usage

from agent_framework import Agent, tool

@tool(approval_mode="always_require")
def delete_records(table: str, older_than_days: int) -> str:
    """Delete records older than the specified number of days."""
    ...

agent = Agent(
    name="db_admin",
    instructions="Manage the database as requested.",
    tools=[delete_records],
)

result = await agent.run("Delete all old records from the logs table")

if result.user_input_requests:
    for request in result.user_input_requests:
        print(f"Pending tool: {request.function_call.name}")
        print(f"Arguments: {request.function_call.arguments}")
        print(f"Request ID: {request.id}")

Related Pages

• Implementation:Microsoft_Agent_framework_AgentResponse_User_Input_Requests
• Function Tool Definition -- for configuring tools with approval_mode
• Agent Execution -- the agent.run() method that returns AgentResponse