Human-in-the-Loop Design for AI Agents: Tool Approval Callbacks, Structured Prompting, and Bidirectional Message Protocols

1. Why Agents Need Human Intervention

Classic LLM interaction is essentially single-turn question-and-answer: the model receives input and produces text, a one-directional, read-only flow. An agent, by contrast, is a “machine that takes action” — it not only generates content, it calls tools, reads and writes files, issues network requests, and runs external commands. This leap from “generation” to “execution” turns the control flow from one-way into two-way: the agent emits output downward, but it can also interrupt itself at any node and reach back up to the user for an instruction or an authorization.

That property raises two engineering problems that have to be faced directly:

1. Actions are irreversible. One accidental deletion, one wrong write, one erroneous submission can cause real damage that is hard to roll back. When a single hallucination gets amplified into a real action, the cost far exceeds that of generating a piece of wrong text.
2. Decisions are uncertain. An agent’s intermediate judgments in a long-chain task are not always reliable, especially when information is insufficient or ambiguous, and a human is needed as the final backstop and calibrator.

Introducing human confirmation and guidance at critical operation nodes — Human-in-the-Loop — is therefore the necessary path for agents to move from “concept demo” to “production-ready.” How well that intervention is designed directly determines the system’s safety, controllability, and user trust.

2. Design Goals and Core Principles

A mature human-machine interaction mechanism should serve three typical scenarios at once:

• Tool approval — a human confirms before a high-risk or high-impact operation runs;
• User Q&A — when information is missing or ambiguous, the agent proactively asks the human to remove the uncertainty;
• Information supplementation — when a task needs extra parameters, credentials, or business context, the agent requests human input.

Around these scenarios, the design should follow these core principles:

Principle 1: One unified mechanism, not several parallel ones. Every interaction type — approval, single-select, multi-select, or free-form input — should be implemented through the same callback entry point, rather than building a separate flow for each. A single entry means single logging, single timeout handling, single permission validation, which significantly reduces system complexity and maintenance cost. The common industry approach is to converge all interactions onto one “tool-call interception/approval callback”: model “asking a question” as a special kind of tool call, so it reuses the same interaction pipeline.

Principle 2: Non-blocking execution. Once an interaction request is issued, the main execution thread should not be stuck waiting. A sound design lets the execution flow enter a suspendable state and hand control back to the outer runtime, resuming only when the human response arrives. This is what makes long waits, timeout fallback, and concurrent multi-task scenarios possible.

Principle 3: Auditable and traceable. Every approval decision and every user answer should be recorded in full, forming a replayable audit trail. This matters especially in production environments with strict compliance requirements.

3. The Unified Interaction Mechanism: A Tool-Call Approval Callback

To put the “single entry” principle into practice, the most typical design is the tool-call approval callback. The core idea: before the agent actually executes any tool, it submits “what is about to run, and with which parameters” to a callback function where a human can intervene; a human (or a higher-level policy) then decides whether to release or block the call.

Such a callback usually supports three return strategies:

• approve — let the tool run as-is and continue the execution flow;
• deny — block the tool and attach a rejection reason, based on which the agent aborts or adjusts;
• feedback — block the call and pass back a correction. This effectively turns the human into the agent’s real-time mentor: the agent receives that reason and revises its subsequent behavior, which is often much closer to real collaboration than a simple approve/deny.

Below is an illustrative callback structure (pseudocode, meant to explain the mechanism rather than a specific interface):

async def on_tool_use(tool_name: str, tool_input: dict, context: dict) -> dict:
    """Unified tool-call interception / approval callback.
    All interactions that need human involvement are dispatched from here:
    - high-risk tool -> approval UI
    - missing information -> Q&A UI
    - everything else -> allow directly
    """
    # 1. Determine the risk level
    if is_high_risk(tool_name):
        decision = await ask_human_for_approval(tool_name, tool_input)
    # 2. Return different results based on the human decision
    if decision.action == "approve":
        return {"behavior": "allow", "updated_input": tool_input}
    elif decision.action == "deny":
        return {"behavior": "deny", "message": decision.reason}
    elif decision.action == "feedback":
        return {"behavior": "deny", "message": decision.suggestion}
    # 3. Allow low-risk calls by default
    return {"behavior": "allow"}

The value of this design: whether the frontend is a CLI, a web console, or a mobile app, the interaction logic converges in one place. The frontend only has to focus on rendering a “confirmation dialog” or an “input field,” without implementing an independent communication path for every interaction type.

4. Structured User Q&A

Beyond binary approve/deny approval, agents often need to proactively request structured information from the user. A dedicated “structured question tool” can serve this purpose: modeling “asking a question” as a tool call lets it reuse the same unified interaction pipeline.

A typical question payload can carry the following fields:

{
    "question": "Which environment would you like to deploy to?",
    "options": ["development", "staging", "production"],  # optional, used to render choices
    "multiple": False,                                   # optional, whether multiple selections are allowed
    "allow_freeform": True                               # optional, whether free-form input is allowed
}

The multiple field cleanly separates single-select from multi-select:

• Single-select (multiple=false) — mutually exclusive cases, such as “choose a deployment environment” or “confirm whether to continue”;
• Multi-select (multiple=true) — parallel cases, such as “select the set of log levels to enable” or “tick the tables that need backing up.”

One major benefit of abstracting questions as tool calls is consistency of the decision chain: an agent’s “asking” and its “executing a tool” go through the same timeout, audit, and recovery machinery. On top of that, once questions are templated, developers can accumulate a library of high-quality question scripts to test how agents behave in interactive scenarios — for example, verifying that an agent proactively asks when information is missing, or that it correctly handles several tasks in parallel after receiving a multi-select answer.

5. Bidirectional Control Flow and Message Protocol Design

The approval and Q&A discussed so far all happen within a single execution session. In a real distributed deployment, though, the agent runs in the backend while user interaction happens in the frontend, and the two need a reliable message protocol to carry the bidirectional control flow.

The biggest difference between agent interaction and traditional chat is that it is a bidirectional control flow: the agent not only produces downstream output continuously, it can also “interrupt” at any moment to request instructions or authorization upstream. The protocol therefore has to cover both directions:

• Downstream channel (backend → frontend): SSE (Server-Sent Events) is recommended for streaming push. The agent’s text increments, tool-call status, approval requests, and final result can all be delivered to the frontend as different event types, which fits the “generate and display at the same time” experience naturally.
• Upstream channel (frontend → backend): a plain HTTP POST submits the user’s decision and input, such as an approval result, a Q&A answer, or supplementary information.

Messages in the protocol are usually distinguished by type, roughly as follows:

// Downstream: request user approval
{ "type": "approval_request", "tool": "delete_file", "input": {"path": "/data/tmp"} }
// Upstream: user replies to the approval
{ "request_id": "abc123", "action": "feedback", "reason": "Wrong target path, the backup should be kept" }
// Downstream: text increment
{ "type": "text_delta", "content": "Analyzing the logs..." }
// Downstream: task finished
{ "type": "result", "status": "success" }

By linking an upstream reply to the corresponding downstream suspended request with request_id, the backend can resume the interrupted task at the correct execution point. This three-part design — “downstream push + upstream reply + request correlation” — is the key to a robust human-machine interaction protocol.

6. Agent Parameter Assembly

However complete the interaction mechanism, an agent needs a full set of runtime parameters before it can execute. In engineering practice, parameter initialization is usually extracted into a config assembler component that loads from a database, a config file, or the runtime environment and assembles everything into a single configuration dict.

A typical agent config might look like this:

agent_config = {
    "name": "log-analyzer",
    "description": "Log analysis and anomaly alerting assistant",
    "model": "default",
    "tools": ["read_file", "search_log", "ask_user"],
    "permissions": {
        "require_approval_for": ["delete_file", "send_message"]
    },
    "interaction": {
        "approval_callback": "on_tool_use",
        "default_timeout_sec": 300
    }
}

The value of the assembler is separation of concerns: declarative settings — what to read, what to write, which tools are available, which operations need approval — are decoupled from the execution logic. Changing an approval policy or adding a new tool often only requires a config change, with no modification to core code. Making the approval permission list (require_approval_for) explicit also makes it easier for the security team to review and manage it centrally.

7. Engineering Practice Recommendations

Pulling the mechanisms above together, here are a few practical recommendations:

1. Least privilege by default. A newly onboarded tool requires approval by default; only low-risk, read-only tools that have been evaluated may execute automatically. Take a “deny by default” security posture.
2. Timeouts must have a fallback strategy. A human may not respond for a long time, so every interaction request needs a timeout, and the behavior after expiry must be explicit: “auto-deny,” “keep waiting,” or “defer to a preset policy.”
3. Interaction state must be recoverable. After a process restart or a network hiccup, pending interaction requests should be restored from persisted state so tasks never hang permanently.
4. A complete audit trail. Persist the input, decision, and timestamp of every approval and Q&A. This serves compliance and makes it easier to review agent behavior after the fact.
5. Decouple the frontend from the protocol. Let the frontend care only about “which interaction to render,” and converge all interaction-type classification and dispatch into the unified backend callback to reduce coupling.

8. Summary

An agent’s reliability depends largely on whether it can “stop and ask a human” at the right moment. Centered on a unified human-machine interaction mechanism, this article traced the full chain from design principles to concrete implementation: a unified tool-call approval callback to converge all interaction types, the approve / deny / feedback strategies to cover release, rejection, and real-time guidance; structured questioning to eliminate informational ambiguity; an SSE-downstream + HTTP-upstream bidirectional message protocol to support distributed sessions; and config assembly to achieve separation of concerns. With these main threads in place, developers can build agent systems that both dare to “act” and know how to “ask first” — finding the right balance between automation efficiency and human control.