Writing the Approval Request a Human Can Answer in Ten Seconds

A useful test for any field: does it change the decision for at least one reviewer? If the answer is no for every reviewer, cut it. Here is a comparison of what belongs in a request and what belongs behind a link or in the audit record.

Take a refund. The request says: "Refund $180.00 to the card ending 4417 for order 4471, all three line items. This cannot be cancelled once processed; the customer sees the credit in 3 to 5 business days." The evidence line says: "Return scanned on day 4, within the 30-day policy." The reviewer needs nothing else, and the reasoning trace about which policy paragraph the agent retrieved stays in the audit record.

Now take a production database write. The request says: "Update 1,204 rows in customers.region for accounts tagged EU to 'eu-west'. A rollback script exists and the snapshot was taken 4 minutes ago." That short request contains the three facts that decide it: volume, blast radius and rollback. A request that instead says "Execute SQL statement per plan" has shifted the work onto the reviewer without telling them what they are approving.

The distinction scales to IT operations, finance and customer-facing messages. Provisioning admin access, rotating keys, disabling accounts and emailing customers all sit in the supervised bucket because the cost of a wrong action is high and the reversibility is low Stack AI's approval workflow guide. Read-only retrieval and drafting can usually run unattended.

The buttons carry as much of the decision as the text. Two design choices do most of the work.

First, the confirm button names the action rather than saying "OK." "Refund $180.00 to card ending 4417" is harder to click by reflex than "Yes." A generic label is a pattern match; a specific label forces one second of reading, which is exactly the second you want.

Second, the safe option should be the default in every mechanical sense: it has focus, it sits in the position the hand expects, and it never moves. When two options are ambiguous, the one that is easier to click wins in practice, so make the reversible choice the easy one. The UX literature on confirmation dialogues frames the whole interaction as deliberate friction that loops the user back to the moment of choice, and it recommends an undo instead of a confirmation when the action is truly reversible Kinneret Yifrah on confirmation microcopy. That logic runs in both directions: if you are adding friction, add it to the irreversible path only.

Third, offer more than two outcomes when the situation calls for it. Approve and reject is often too limited; modify and escalate are useful decision types, and approve-with-edits lets a reviewer fix a small parameter without restarting the workflow Promptessor's HITL design guide. A three-button request ("Refund $180.00", "Refund a different amount", "Reject") beats a two-button one when the common failure is a slightly wrong number.

Wording rules that hold up under time pressure:

• Use the active voice with the actor implied: "Send the email to 42 recipients." Not "The email will be sent."
• State the irreversible part plainly and without hedging: "This deletes the records permanently." Not "This action may not be recoverable."
• Put the amount, count and identifier in the sentence itself, not in an image, tooltip or expandable panel.
• Name the recipient's domain or team when the reviewer has no way to recognize the target ("the production cluster used by billing").
• Drop adverbs. "Urgent", "important" and "critical" carry no information for a reviewer who sees requests all day.

One phrase to avoid entirely: "Are you sure?" It asks the reviewer to redo the judgment they just made and tells the next reviewer nothing. Replace it with the consequence sentence.

The most common mistake in agent approval design is attaching the agent's chain of thought to the request. Reasoning traces are written for debugging, not for deciding. They are long, they mix exploration with conclusion, and they invite the reviewer to audit the agent's thinking instead of judging the proposed action. The evidence pack exists to make the decision obvious, not to prove the agent worked hard.

Logs have the same problem at larger scale. A 400-line stack trace does not tell a reviewer whether to rotate a key; the line "key used by the public API, last rotated 11 months ago, 2 downstream services" does. Keep the log one click away for the cases where the reviewer wants it, and keep it out of the default view.

There is a security reason too. Reasoning traces and tool outputs can contain customer data, credentials and internal identifiers that the approver's role was never scoped to see. Asynchronous approval systems built on standards such as Client Initiated Backchannel Authentication deliberately keep the agent, the authorization server and the user's device separate, with the user approving on a different device from the one the agent runs on Auth0 on secure human-in-the-loop interactions. Shipping the whole context to the approval channel widens the surface for no decision benefit.

The same principle governs what a pause event should contain at the framework level. When a tool call is marked as requiring confirmation, the run pauses and surfaces a structured request that describes the pending action, and the application decides what to present Agno's HITL documentation. Structured fields are the right container; a rendered paragraph of agent narration is not.

A yes is only true at the moment it is given. Between the request and the execution, the order may have been cancelled, the price may have changed, the account may have been flagged, or a second agent may have already acted. A request without an expiry and without a revalidation step can authorize an action that no longer matches the world it was approved for.

The design implication is that approval is a workflow state, not a sentence in a prompt. The strongest systems revalidate state after approval and request a new decision when the conditions no longer hold Promptessor's HITL design guide. Operationally that means three things on the request screen itself: a visible expiry, a short statement of what the agent will check before acting, and a rule for what happens when the check fails.

Approval requested  14:02
Expires             14:32 (30 min)
Before acting, the agent re-checks:
  - order 4471 status is still "returned"
  - refund amount has not been changed by another agent
If either check fails: request is withdrawn and reissued with a new summary

Idempotency belongs in the same design. If a reviewer double-clicks, or the approval is delivered twice by a retry, the action should run once. An approval that carries an idempotency key and a single-use token is safe to retry; one that does not will eventually process the same refund twice, and that failure will look like a human error when it is an interface error.

Timeouts and missing reviewers need a defined path as well. When the request expires, the safe outcome is not "auto-approve because the reviewer was slow." Escalate to a backup approver, or drop the action and tell the requesting user. Approval queues should be routed by role so the right person sees the request, and the request should say who that is if it is waiting.

Usability testing for an approval request is cheap and almost nobody does it. The protocol takes fifteen minutes per reviewer and needs no instrumentation.

1. Give the reviewer five real requests, including one with a deliberately missing field.
2. Start a timer and ask them to decide each one.
3. After the decision, ask them to repeat back, in one sentence, what will happen if they approve.
4. Record the decision time and whether the restatement matches the actual effect.

The pass condition comes from the original framing: if the reviewer cannot repeat back what will happen after ten seconds of reading, the request is not ready. The evidence pack should make the decision obvious in 10 to 30 seconds Stack AI's approval workflow guide, so a request that takes two minutes is a defect in the request, not in the reviewer.

The restatement step is the one that catches real bugs. Reviewers reliably restate what they expected to see rather than what was written, so compare their sentence to the action's actual effect. When they diverge, the gap tells you which field is doing too little work.

Track approval quality after launch, not just approval volume. Two numbers are worth watching: the share of approvals that were later reversed or found to be wrong, and the share of requests that expired without a decision. High reversal rates point at missing evidence or a misstated consequence. High expiry rates point at routing or at a queue that is too long for the reviewer's day. A request format that produces fast, confident, correct decisions is doing its job; one that produces fast clicks is not.

Two pieces of the stack need to agree for any of this to hold. The runtime must pause at the right boundary and resume from a durable state, and the message must carry the right fields. Frameworks already expose the first half: Agno marks a tool as requiring confirmation so the run pauses and returns a structured request, with an approvals layer on top for sign-off that must survive an audit Agno's HITL documentation. AWS documents the same pattern for agents that can modify business-critical data, where repeated tool execution is acceptable for read paths but risky for writes AWS on human-in-the-loop confirmation.

The second half is composition, and it is where most of the effort actually goes. If the agent calls several model types to assemble a request (a vision model to read a returned item photo, an embedding model to match the order, a text model to draft the summary), one API key for all of them removes a whole class of integration work. Quanta Inference exposes text, image, video, audio and embedding models behind an OpenAI-compatible endpoint with prepaid pricing in US dollars, which keeps the request-generation step in one place.

Once the format is stable, the format itself becomes the durable asset. A request template with the five fields, the two buttons and the expiry rule can be reused across every gated action your agents take, and reviewed once by the people who own the risk.