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:
| Mode | What waits |
|---|---|
policy (the default) | Calls that can write, and calls a policy says need approval. |
always | Every tool call in the step, including reads. |
never | Nothing. 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:
GETandPOST /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
| Decision | Result |
|---|---|
| Approve | The tool call runs and the agent carries on. |
| Reject | The run stops. It does not continue without the tool. |
| Nobody decides in time | The 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 action | When |
|---|---|
request_tool_approval | A tool call stops for approval. |
approve_tool_call | Someone approves it. |
reject_tool_call | Someone 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:
| Surface | What the caller sees while it waits |
|---|---|
| Playground | Waiting for your approval, with Approve and Reject on the turn. |
| Agent API | 202 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 widget | The tool's name and that the agent is waiting. The answer appears when someone decides. |
| Teams, Slack, WhatsApp | One message that the agent needs a person to approve an action. The answer follows in the conversation. |
| A2A | The task stays TASK_STATE_WORKING, with pending_approvals. |
| Voice and phone calls | The 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 agents | A 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.