Principle:Microsoft Agent framework Approval Response Handling

Property	Value
Principle Name	Approval Response Handling
SDK	Microsoft Agent Framework
Repository	Microsoft Agent Framework
Source Reference	python/packages/core/agent_framework/_types.py:L1013-1029
Import	Access via Content objects from user_input_requests
Domains	Agent_Architecture, Safety

Overview

Approval Response Handling is the principle of converting a user's approval decision into a response that resumes agent execution. The Content.to_function_approval_response(approved: bool) method transforms an approval request into an approval response, which is then sent back to the agent to either execute or reject the pending tool call.

Description

When an agent encounters a tool call that requires human approval, it pauses execution and surfaces a function_approval_request Content item through the user_input_requests property of the response. The user (or application logic) must then decide whether to approve or deny the pending operation. The Approval Response Handling principle governs the transformation of that binary decision into a well-formed response that the agent can process to resume its execution flow.

The to_function_approval_response() method encapsulates this transformation. It takes the original approval request Content -- which carries the function call details, identifier, annotations, and raw representation -- and produces a new function_approval_response Content object with the same metadata but with the user's approval decision attached. This response is then wrapped in a user message and sent back to the agent via a subsequent run() call.

Human-in-the-Loop Safety Gate

This principle implements a human-in-the-loop safety gate for tool execution. Rather than allowing the agent to autonomously execute every tool call, the framework can be configured to require explicit user consent for sensitive or destructive operations. The approval response mechanism ensures that:

1. The agent cannot proceed with a tool call until the user has rendered a decision.
2. The decision is transmitted in a structured, type-safe format that the agent runtime understands.
3. The original request metadata (function name, arguments, call ID) is preserved in the response, ensuring the agent can match the response to the correct pending tool call.

Approval Flow

The full approval flow follows this sequence:

1. The agent invokes run() and the LLM requests a tool call that requires approval.
2. The agent response contains a function_approval_request Content item in user_input_requests.
3. The application presents the approval request to the user (displaying the function name and arguments).
4. The user decides to approve or reject the operation.
5. The application calls to_function_approval_response(approved=True/False) on the request Content.
6. The resulting function_approval_response Content is sent back to the agent in a new run() call.
7. If approved, the agent executes the tool call and continues. If rejected, the agent skips the tool call and adjusts its response accordingly.

Type Safety

The method enforces type safety by raising a ContentError if called on a Content object whose type is not function_approval_request. This prevents accidental misuse where arbitrary content could be mistakenly treated as an approval request.

Theoretical Basis

The Approval Response Handling pattern is rooted in the broader concept of human-in-the-loop (HITL) systems in AI safety. By requiring explicit human authorization before executing potentially dangerous operations, the system implements a confirmation barrier that mitigates risks associated with autonomous tool invocation.

The pattern follows the Request-Response communication model, where the approval request and response form a matched pair linked by shared metadata (function call ID, function name, and arguments). This ensures that the response is always correctly associated with its originating request, even in multi-turn conversations with multiple pending approvals.

From a design perspective, the method applies the Transformation Pattern: it takes an existing data structure (approval request Content), extracts its essential properties, and constructs a new data structure (approval response Content) that reuses those properties while altering the semantic type and adding the approval decision.

Related Pages

• Implementation:Microsoft_Agent_framework_Content_To_Function_Approval_Response

Sources

Type	Name	URL
Repo	Microsoft Agent Framework	https://github.com/microsoft/agent-framework