Implementation:Microsoft Agent framework AgentResponse User Input Requests

Property	Value
Implementation Name	AgentResponse User Input Requests
SDK	Microsoft Agent Framework
Repository	Microsoft Agent Framework
Source File	python/packages/core/agent_framework/_types.py
Line Range	L2341-2348
Import	Access via AgentResponse returned from agent.run()
Type	Read-only property
Domains	Agent_Architecture, Safety

Overview

The AgentResponse.user_input_requests property filters the response's messages to return only those Content objects that represent pending tool approval requests. It provides a direct mechanism for detecting when an agent's execution has been paused because one or more tool calls require human authorization before proceeding.

Code Reference

Source Location

Property	Value
File	python/packages/core/agent_framework/_types.py
Class	AgentResponse
Member	user_input_requests (property)
Lines	2341-2348

Signature

@property
def user_input_requests(self) -> list[Content]:

Import Statement

# AgentResponse is returned by agent.run(), not imported directly for construction.
from agent_framework import Agent

agent = Agent(...)
result = await agent.run("some message")
# result is an AgentResponse; access .user_input_requests on it

I/O Contract

Input

This is a read-only property with no parameters. It operates on the internal message list of the AgentResponse instance.

Output

Return Type	Description
list[Content]	A list of Content objects where user_input_request is True. Each object represents a single pending tool approval request. Returns an empty list when no approvals are pending.

Content Object Fields (per request)

Field	Type	Description
.id	str	A unique request identifier used to correlate approval or rejection decisions back to this specific pending tool call.
.function_call	Content	A nested Content object containing the tool call details.
.function_call.name	str	The name of the tool that the LLM is requesting to invoke.
.function_call.arguments	str	The serialized JSON arguments the LLM proposed for the tool call.
.user_input_request	bool	Always True for objects returned by this property (this is the filter predicate).

Internal Behavior

The property iterates over the response's internal message collection and selects only those Content objects where the user_input_request attribute is True. This filtering mechanism provides a clean separation between normal response content (text, tool results, etc.) and pending approval requests, without requiring the caller to understand the internal message structure.

The filtering is performed on each access (not cached), so the returned list always reflects the current state of the response's messages.

Usage Examples

Basic Approval Detection

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

if result.user_input_requests:
    for request in result.user_input_requests:
        print(f"Tool: {request.function_call.name}")
        print(f"Args: {request.function_call.arguments}")

Iterating Multiple Pending Requests

result = await agent.run("Clean up the database and archive old logs")

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

# Example output:
# Request ID: req_abc123
# Tool: delete_records
# Arguments: {"table": "logs", "older_than_days": 90}
# ---
# Request ID: req_def456
# Tool: archive_records
# Arguments: {"table": "logs", "destination": "cold_storage"}
# ---

Conditional Flow Based on Approval State

from agent_framework import Agent, AgentThread

agent = Agent(
    name="admin",
    instructions="Execute administrative tasks.",
    tools=[delete_records, archive_records],
)

thread = AgentThread()
result = await agent.run("Delete all old records from logs", thread=thread)

if result.user_input_requests:
    # Present to user for review
    pending = []
    for req in result.user_input_requests:
        pending.append({
            "id": req.id,
            "tool": req.function_call.name,
            "args": req.function_call.arguments,
        })
    # In a real application, send `pending` to a UI for human review
    print(f"{len(pending)} tool call(s) awaiting approval")
else:
    # No approval needed -- agent completed normally
    print(result.text)

Related Pages

• Principle:Microsoft_Agent_framework_Approval_Request_Detection
• Implementation: Agent Run -- the agent.run() method that produces the AgentResponse
• Principle: Function Tool Definition -- configuring tools with approval_mode