Skip to main content

Human approval

Before an agent calls a tool that can change data, such as sending an email or creating a CRM record, its run stops and waits for a person. The call happens only if someone approves it.

When a tool call waits​

Each step of an agent has an approval mode:

ModeWhat waits
policy (the default)Calls that can write, and calls a policy says need approval.
alwaysEvery tool call in the step, including reads.
neverNothing. Calls still go through the policy check.

In policy mode, a call waits when:

  • the tool can change data, judged from the connector as it is configured at the time of the call. See Writes and approval.
  • the tool is on the baseline policy's write-tool list
  • a custom policy with the Require approval effect matches it. See Policy.

Agents created in the console use policy. You can set always or never, and the approval window, on each step through the Agents API. Editing an agent in the console keeps the mode it had.

Who can approve​

Any developer or admin on the run's project can approve or reject, including the person who started the run. The audit log records who asked and who decided as separate fields, so you can find anyone who approved their own request.

Where to approve​

  • In the Playground, the turn shows Waiting for your approval with the tool and its arguments.
  • On the run's page in Runs & Traces, under Approvals on this run.
  • On the Governance page, Pending approvals lists waiting calls in every project from the last 7 days, including code agents' tool calls. This list is for platform admins.
  • Through the API: GET and POST /workflow-runs/{workflow_id}/approvals.

The request shows the step, the tool, the exact arguments, why it was stopped, and when it expires. Add a reason when you decide. It is kept in the audit log.

What happens next​

DecisionResult
ApproveThe tool call runs and the agent carries on.
RejectThe run stops. It does not continue without the tool.
Nobody decides in timeThe request expires and counts as a rejection. The run stops.

The default approval window is one hour. A stopped run shows as Failed with the reason, so a refusal is never hidden in a confident answer.

The first decision on a request wins. Deciding on a request that has already been decided, or has expired, returns a conflict that says what happened.

While a run waits, it holds no resources. The API's run call returns awaiting_approval after two minutes and the run carries on waiting.

What is recorded​

Audit actionWhen
request_tool_approvalA tool call stops for approval.
approve_tool_callSomeone approves it.
reject_tool_callSomeone rejects it, or it expires. An expiry is marked timed_out, and one expired by the end of a call says so.

Approvals on every surface​

The same gate applies wherever the agent runs, and the run waits the same way:

SurfaceWhat the caller sees while it waits
PlaygroundWaiting for your approval, with Approve and Reject on the turn.
Agent API202 with the run, or awaiting_approval in the stream. The answer arrives on GET /v1/runs/{id} and the webhook. See Agent API.
Hosted chat and widgetThe tool's name and that the agent is waiting. The answer appears when someone decides.
Teams, Slack, WhatsAppOne message that the agent needs a person to approve an action. The answer follows in the conversation.
A2AThe task stays TASK_STATE_WORKING, with pending_approvals.
Voice and phone callsThe agent says it is waiting on the line, and reminds the caller every 30 seconds. The wait is the agent's Approval wait, 2 minutes by default. When the call ends, open approvals expire. See Voice agents.
Code agentsA platform tool call through the MCP tool server waits at the same gate. The tool call returns its result once approved, or a resumable handle while it waits.

Approvers always decide in the console or through the API.

Evals​

Evals never run write tools. In an eval run, a call that would wait for approval is not run and not waited for. The agent is told it was not executed, and the case can still check that the agent tried. See Evals.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →