Place approval before consequential actions

Learning objective

Place human-in-the-loop checkpoints according to business impact, risk, and reversibility.

Core idea

When you place human checkpoints, identify the action whose consequences require judgment. Approving a plan can confirm its direction, while approving a tool invocation authorizes a concrete operation. Reviewing the final answer can catch presentation defects, but it is too late to prevent a write that already happened.

Use business impact, risk, and reversibility together. A low-impact draft can often proceed without interruption. A financial transfer, external publication, or difficult-to-reverse change needs a stronger decision boundary. A technically reversible operation can still expose confidential information or affect many people before reversal.

Microsoft Agent Framework supports human input through workflow request/response handling and approval-required function tools. These mechanisms provide the pause and resume boundary. Your application supplies the business policy, reviewer identity, evidence, and handling of rejection or unanswered requests.

How it works

Classify the consequence before choosing the checkpoint

Assess impact: what money, data, service, or customer outcome changes? Assess risk: how uncertain is the evidence, and what happens if the proposed action is wrong? Assess reversibility: can you restore the prior state, and what remains exposed or consumed afterward?

Turn that assessment into an application policy. For example, permit read-only investigation and internal drafting, require approval for a customer-visible financial commitment, and route unsupported exceptions to a specialist reviewer. These are business rules, not built-in Agent Framework risk tiers.

Place a checkpoint where the reviewer has enough information to decide and where the action has not yet occurred. If the reviewer sees only the original request, they cannot authorize arguments that the agent has not produced. If the system asks only after a write, the checkpoint is retrospective oversight rather than prevention.

Distinguish input, plan review, and action approval

A missing-information checkpoint asks for evidence or a decision that affects subsequent work. In Python workflows, ctx.request_info() emits a workflow event with type == "request_info". The application gathers the response and resumes through workflow.run(..., responses=...), keyed to the request identifier. In .NET, RequestPort emits RequestInfoEvent and routes the response back to its originating executor.

Plan review governs the approach rather than authorizing each eventual invocation; see 1.1.5 for Magentic configuration and language-specific defaults.

Action approval asks whether a concrete tool call should execute. In Python, mark a local function tool with @tool(approval_mode="always_require"). In .NET, wrap the AIFunction with ApprovalRequiredAIFunction. The approval requirement belongs to the operation rather than to an instruction asking the agent to remember a policy.

Present the proposed invocation

For a standalone Python agent, inspect result.user_input_requests. Each function approval request exposes function_call.name and function_call.arguments. Present those details with the business evidence and consequences so the reviewer knows what approving changes.

Create the response through to_function_approval_response(True) to approve or to_function_approval_response(False) to reject. Resume the agent with the approval response and the same AgentSession. By default, local approval-response binding authorizes a call only when the response matches a pending request recorded in that session; the framework ignores an unbound response and logs a warning.

The Python opt-out is client.function_invocation_configuration["disable_approval_response_binding"] = True. Use it only when your application enforces equivalent binding before messages reach the agent: disabling framework binding can let a fabricated or replayed response authorize a privileged call. A fresh session does not preserve the original pending request, and disabling binding is not a substitute for restoring it.

Within an agent workflow, approval-required tools use the workflow request/response mechanism. The workflow pauses and emits a request event; Python’s payload is Content with type == "function_approval_request", while .NET uses ToolApprovalRequestContent in a RequestInfoEvent. The application responds to that specific request rather than treating all request events as interchangeable user messages.

Framework scope matters. Tool approval works with providers whose clients invoke tools locally. Service-side hosted tools follow their provider’s approval behavior. Do not infer that a local approval decorator blocks every hosted action reachable through a different provider surface.

Design rejection and waiting as real states

Define what rejection means: stop the action, revise the proposal, or return a rejected business outcome. Do not let the agent reinterpret rejection as permission to try an equivalent unapproved operation. Restrict alternative write paths so the same consequence cannot bypass the checkpoint.

Define how long a request can wait, who handles it, and what happens when no response arrives. Those are application policies, not an automatic business timeout supplied by the approval mechanism. Silence must not be converted into approval. An expired decision can produce a deferred or canceled outcome.

Agent Framework checkpoints preserve pending requests. On restore, pending requests are re-emitted; Python can resume with checkpoint_id and responses in workflow.run(...). Use this for long waits, and design the review application to recognize the same pending request after recovery rather than presenting it as an unrelated action.

Bind business approval to the reviewed proposal. If arguments or target change, require another decision under your policy. Revalidate mutable business facts before execution. Human approval records intent; it does not guarantee that the target state still matches what the reviewer saw.

Key distinctions and trade-offs

Plan approval versus invocation approval: Plan review governs approach. Invocation approval governs a named operation with concrete arguments. High-impact actions can require both at different points.

Reversible versus harmless: Reversal can repair state without undoing exposure, cost, or disruption. Consider consequence before deciding that a reversible operation can proceed autonomously.

Human judgment versus runtime enforcement: A reviewer assesses evidence and intent. Tool wrappers and workflow control enforce the pause. Prompt instructions alone do not provide the same boundary.

Oversight versus interruption cost: Frequent low-value approvals slow work and encourage shallow review. Concentrate checkpoints where they can change a consequential decision, while leaving bounded investigation and preparation available.

Architecture / decision scenario

An agent helps a retailer resolve damaged-delivery complaints. Read-only tracking checks and a draft response have low operational impact. Issuing money changes a financial system, and sending the response exposes a commitment to the customer. You assess those actions separately instead of approving the entire agent session.

For unclear damage evidence, a workflow executor calls ctx.request_info() to ask a reviewer for a decision. The reviewer receives the case evidence and the specific missing fact. An unanswered request remains pending or expires through application policy; it does not become an affirmative decision.

The agent proposes a refund using a local function tool marked approval_mode="always_require". The application displays the function name, order, amount, and supporting evidence from the pending invocation. A response authorizes or rejects that call. If the amount changes, the application requests approval for the changed proposal.

A checkpoint preserves the pending request during a long wait. On resumption, the application recognizes the re-emitted request, rechecks relevant order state, and supplies the decision to the correct request. A rejected refund returns a rejected outcome or a revised proposal, never an automatic alternate payment path. This places oversight according to evidence uncertainty, financial impact, and the limits of reversing an already-issued payment.

Common exam traps

• Asking for approval only after the consequential tool has executed.
• Treating approval of a broad plan as approval of every future invocation.
• Converting unanswered or expired requests into permission.
• Assuming a reversible operation has no material risk.
• Assuming local function-tool approval controls service-side hosted tools.
• Losing request identity when restoring a pending human checkpoint.

What to remember

Place human judgment before the consequence, with evidence and concrete arguments. Use request/response handling for missing input, plan review for approach, and approval-required tools for local action gates. Define rejection, expiration, recovery, and changed-proposal behavior in the application policy.

Knowledge check

References

• Microsoft, Using function tools with human in the loop approvals
• Microsoft, Workflows — Human-in-the-loop
• Microsoft, Workflows orchestrations — Magentic
• Microsoft, Tools overview