Human-in-the-Loop Approval for AI Agent Actions

Human-in-the-loop approval for an AI agent should be a transaction gate, not a generic confirmation dialog. The agent proposes one API write. A reviewer sees the resolved destination, method, path, query, and body. The system then binds the decision to that exact request and refuses to reuse it if the request or connection changes.

That distinction matters because “a human is involved” says nothing about what the human saw, what authority they exercised, or whether the executed request still matched the reviewed one. A useful approval boundary makes those facts explicit and keeps the write pending until a separate approval authority releases it.

This article explains the pattern ActionDock uses for a supervised API write, where it helps, and where the current product boundary stops.

What human-in-the-loop approval should control

The purpose of approval is not to ask whether an agent is generally trusted. It is to decide whether one consequential change should happen now.

The NIST AI Risk Management Framework Core calls for organizations to define roles and responsibilities for human-AI configurations and to document processes for human oversight. OWASP’s guidance on Excessive Agency similarly recommends human approval for high-impact actions and authorization checks outside the model.

Those principles become operational only when the approval system answers four questions:

1. What exact change did the agent request?
2. Which policy allowed the request to reach review?
3. Who approved or rejected it?
4. Did execution still match the reviewed request?

A weak confirmation answers none of them. An exact-request gate answers all four.

The approval sequence starts before the review screen

An approval dialog cannot repair an unbounded execution path. The system must establish the request boundary first.

In ActionDock, the external agent calls integration.execute with a connection ID, HTTP method, path, optional query, and optional body. The connection already defines a public HTTPS base URL, allowed methods, and a runtime write-policy mode. In the default manual mode, it also defines allowed path prefixes.

The sequence is:

1. Submit intent. The agent submits one proposed write and receives a durable job.
2. Apply deterministic controls. ActionDock checks the configured destination, method, network route, path policy when applicable, and execution limits.
3. Create the exact preview. The permitted request enters awaiting_approval with its connection version and resolved request data.
4. Record the owner’s decision. A signed-in workspace owner approves or rejects the job in the dashboard.
5. Recheck the binding. Before dispatch, ActionDock verifies that the connection and request still match the preview.
6. Execute or stop. A matching request can proceed; a changed connection or request requires a new submission and review.

The external API has not been changed while the job is awaiting_approval. The state is not a loading indicator and does not mean the agent will eventually succeed. It is a durable stop in the transaction.

This is why an agent integration should never translate awaiting_approval into “completed” or “approved.” It should show the preview, direct the owner to the dashboard, and wait for a later state. The ActionDock agent guide documents the exact job contract.

Show the whole request that can affect the decision

A reviewer needs enough context to recognize the operation and its consequences. For an API write, the minimum useful preview includes:

The preview should not imply more certainty than it contains. It can show that ActionDock intends to send a particular request. It cannot prove that the provider will complete the expected business process after accepting it.

For example, an API may return a successful transport response while downstream processing continues asynchronously. Conversely, a network interruption may prevent ActionDock from learning whether the provider accepted the write. That reliability boundary is covered in AI agent API retries, idempotency, and uncertain outcomes.

Connection changes must invalidate pending approval

A common time-of-check/time-of-use failure occurs when a request is reviewed under one policy and executed after that policy changes.

Suppose an owner reviews a request against version 4 of a project-system connection. Before approval, someone changes the base URL, credential, allowed methods, path prefixes, or reasonableness policy. Executing the old preview under the new connection would combine a previous human decision with a different technical boundary.

ActionDock rejects that combination. The preview is bound to the connection version and resolved destination. A connection edit makes the proposal stale, so the agent must submit the write again. The owner then reviews a new preview under the current policy.

The same rule applies when the proposed query or body changes. Approval is not a reusable capability token. It is evidence that the owner released one exact transaction version.

Separate submission authority from approval authority

An agent that can both propose and approve its own write does not have a meaningful human gate. The submission and approval paths should use different credentials and interfaces.

ActionDock workspace API keys can submit jobs over MCP or HTTP, read non-secret connection metadata, and retrieve job state. They cannot call the dashboard approval or rejection routes. Approval requires a signed-in dashboard session, and the workspace email used for the decision is stored with the job.

That is a real separation between an agent credential and the current approval channel, but it is not enterprise separation of duties. Today, ActionDock has a single-owner approval model. It does not provide multi-user RBAC, named approver routing, multiple required approvals, SSO, or a policy that prevents the same person from controlling both the agent host and the owner mailbox.

Teams that require those controls should treat them as deployment requirements, not infer them from the phrase “human in the loop.” The first-safe-write security model explains how the current boundary fits into a wider architecture.

Optional AI reasonableness is not the human decision

ActionDock can add a probabilistic reasonableness check to the deterministic request boundary. In the recommended combined mode, path prefixes apply first, then the owner’s written business rule is evaluated. An advanced mode removes write path prefixes and relies on the rule, while still enforcing the HTTPS destination, allowed methods, public-network controls, exact-request approval, and execution limits.

The order is important: for writes, the runtime AI check runs after the owner approves the exact preview. It can allow the request or fail closed, but it cannot approve a job. It does not search the web at runtime, does not receive the stored connection credential, and is not a general chat interface.

Because the check is probabilistic, it should be described as an additional gate, not as proof that a request is reasonable or correct. Manual method and path controls remain the clearer choice when the permitted operation can be expressed deterministically.

A practical approval checklist

Before you put an agent-controlled write into production, verify the complete path:

• The agent submits one bounded operation rather than arbitrary code or headers.
• Deterministic destination and method checks run before review.
• The reviewer sees the resolved target, method, path, query, and body.
• The pending state is visible and cannot be mistaken for success.
• Approval uses a different credential and channel from agent submission.
• Connection or request changes invalidate the pending preview.
• Rejection is durable and releases any reserved work.
• Execution returns a terminal state and the response observed by the gateway.
• Ambiguous outcomes stop automatic write retry and require reconciliation.
• Direct browser, native-connector, and credential paths are addressed outside the approval product.

The last item is essential. ActionDock controls only writes routed through its MCP or HTTP API. If the agent also holds a target-system credential or authenticated browser session, it can bypass the review boundary entirely. The MCP write-tool security guide covers that deployment concern in more detail.

When per-write approval is the wrong design

Human review is useful for low- to moderate-volume changes where a wrong or repeated write has a meaningful cost. It is a poor fit when thousands of routine operations must run unattended, when reviewers cannot understand the payload, or when approval becomes a reflexive click.

It is also unnecessary for read-only analysis that has no external side effect. ActionDock’s supporting read, validation, extraction, research, document, and report actions do not enter the write-approval state. The product applies mandatory owner approval specifically to integration.execute.

Start with one concrete POST, PUT, PATCH, or DELETE that an existing agent can prepare but should not execute alone. If a person can review its exact preview and make a real decision, it is a suitable First Safe Write candidate.

Frequently asked questions

Does human approval make an AI agent safe?

No. It reduces one class of execution risk when the reviewer sees and releases the exact action. It does not control the agent’s reasoning, direct credentials, browser sessions, or other tools.

Should every AI-agent action require approval?

Not necessarily. Approval should follow consequence and risk. ActionDock requires it for external API writes, while its read-only and supporting actions run without that gate.

Can an ActionDock API key approve its own request?

No. The API key can submit and inspect jobs, but approval or rejection requires a signed-in workspace owner in the dashboard. The current model is one owner, not multi-user RBAC.

If you have one agent-prepared write still completed by hand, describe the blocked write. To inspect the MCP and HTTP contract first, read the agent integration guide.