Three places to put a person in the loop
Human gates pause work, record the exact request, and resume only after a decision. Where the gate is declared determines its reach. An organization requirement always creates an approval; an agent-selected tool can instead ask the person in the conversation for a confirmation. These decisions have different answerers and deadlines. The three places to declare gates are below; an agent cannot remove an organization requirement.
| Layer | Set by | Reaches | Gates |
|---|---|---|---|
| Organization - Tool approvals on an integration | Organization admin | Every agent in the organization | Any tool, reads included |
| Agent - Approvals in the Setup | The agent's editors | This agent only | Any tool it holds |
| Flow - an approval gate or human task step | The flow's editors | That step of that flow | The work after the step |
Organization: require approval on a tool
Open an integration under Integrations, then Tool approvals in the Tools section. Switching Require approval on for a tool suspends every agent in the organization that calls it, on every call, until a person approves. The badge Approval required then follows the tool wherever it is listed.
Both this layer and the agent layer can gate a read. A read cannot change the external system, but a query shaped to pull out everything it can reach is still worth a look. What makes this layer distinct is reach and removability, not which tools it covers: it is the only one an agent's author cannot loosen. The Setup's own list is unioned with the organization's, and the agent's Approvals drawer shows the organization-mandated tools as a fixed line above the ones the author can choose.
It applies to agent turns. A flow's tool steps are governed by the flow's own gates, not by this switch.
More than one approver
Beside Require approval, Approvers needed sets how many different people must approve each call - up to five. With two or more, the call waits until that many people have approved it; any one of them can reject it, which stops it at once, and the same person never counts twice. Each approval is recorded in the audit log as it arrives, and the final one lists every approver. The tool's badge then reads, for example, 2 approvers required.
- Approvers are whoever the domain's approval policy admits, exactly as for a single approver.
- When the call uses one person's own credentials, that person must be one of the approvers; the others come from the domain's approvers.
- Agent confirmations stay a single answer from the person who asked, and an agent or flow that calls this one cannot stand in for one of the approvers.
- The number is fixed when the call pauses: changing it later applies to new pauses, not to ones already waiting.
This setting covers agent turns only. A flow's approval gate is decided by one qualifying person; to require two sign-offs in a flow, place two approval gates in sequence.
Agent: gate a tool
Under Setup → Settings → Approvals, domain Editors and Owners pick which of an agent's tools pause for a decision. The list offers every tool the agent reaches, reads and writes alike, grouped by integration and badged Read or Write per row. Gating a read also stops that call running in parallel with its neighbours, which is the only cost the badge is there to tell you about.
In an attended conversation, a selected tool asks the person who initiated that turn for confirmation, provided it uses their own credentials or the domain's credentials. Only that person can answer, including a Viewer. Confirmations stay in the conversation and never enter the Approvals inbox.
For unattended work, work using someone else's credentials, or a tool the organization requires to be approved, the pause is an approval routed by credential authority. An organization requirement always takes precedence over the agent's confirmation setting.
Four settings live in the same drawer.
- How long a pause waits - one field per class, because the people waiting are different. In a chat defaults to 4 hours, with approvers to 72. Setting one never moves the other. The floor is a minute and the ceiling thirty days. Expiry fails the turn rather than running the call without a decision.
- Before a pause expires - an optional reminder, sent once, a number of hours before the deadline, to the audience you pick: the people who can decide it, the domain's owners, the organization's owners and admins, or any combination. Who those people are is worked out when the reminder is sent, so it never reaches somebody who could not decide. It does not extend the deadline or add a decider - on expiry the turn still fails. A confirmation in a chat reminds only the person who was asked. The reminder must be shorter than the with approvers window, and a pause whose whole window is shorter than the reminder gets none.
- Skip the pause when a condition holds - shown under each gated tool. Name one argument of the call (such as
amount, orrefund.amountfor a nested one), a comparison and a value, and calls that meet it run without pausing - for example, refunds under 200. Calls that miss it, or whose argument is missing or not a number, pause as usual. The rule checks only the argument it names and ignores the call's others, and it checks a list only at the position named - a rule on an email's first recipient (to.0) does not look at the other recipients,ccorbcc. If those matter, keep the pause. Every skipped pause is recorded in the audit log and on the call itself, so the activity shows it ran without anyone being asked. A tool your organization requires approval for always pauses, whatever the rule says. - An agent or flow that calls this agent may approve it too - shown under each gated tool. When another agent or flow runs this agent, that caller becomes an additional decider for the gate. The request still lands in Approvals for anyone who could always decide it, and whichever comes first wins. Off by default, per tool, because a model authorizing a model's side effect is a standing decision an agent editor makes about one specific write. See Calling other agents.
- The Setup's Delegation row sets how many questions a called agent may ask this one - related, but a question authorizes nothing and never enters Approvals.
The published Setup is what runs. Editing the list in a draft changes nothing until you publish; a test drive uses the draft.
Flow: an approval gate or a human task
A flow declares its own pauses as steps. An approval gate carries a message for the approver, a role floor (operator or higher by default), an approve outlet and a reject outlet, an option to block the run's initiator from approving their own gate, and a timeout that defaults to 24 hours. The step's role floor applies in addition to the domain's approval policy. A reject with no outlet fails the run with the rejection. A human task pauses for an Operator, Editor or Owner who meets its assignee-role floor to fill in declared fields, and their answers become step outputs.
A flow's approval gate has no amount threshold of its own. Put the threshold in a condition step instead - for example, a refund flow can branch on the amount and send only larger refunds to the gate, so the limit is visible in the flow and versioned with it. (An agent's gated tool can carry a threshold, described above, because an agent has no condition step to hold one.)
Who may decide
Authority follows the credentials the gated work runs on, not seniority.
- Domain-routed approvals follow the domain's approval policy: Operator or above by default. A domain Owner can set another minimum role or a list of named domain members. A nonempty list replaces that domain role floor, so a named Viewer can decide an agent approval. A Flow gate's own role floor still applies in addition to either policy.
- Your credentials marks work using a person's own sign-in or a credential they supplied on an API request. Only that person may decide it, whatever their role, while they retain domain access. Neither organization nor domain seniority overrides this identity.
- Confirmations can be answered only by the recorded initiator of the attended turn, including a Viewer. Other session participants cannot answer on their behalf.
- Human tasks require the domain approval action (Operator or above) and the step's assignee-role floor. A named Viewer on the domain's approval list does not gain this separate action.
- A gate configured to block self-approval refuses the run's initiator even at the right role.
- A tool your organization requires more than one approver for needs that many different qualifying people; see More than one approver.
Being allowed to view or participate in a session does not by itself grant approval authority. See the full Roles and permissions reference.
A row can also be blocked - its credential became unavailable while it waited, or the person it was routed to left the domain or was deactivated. A blocked item cannot be decided until the credential is restored; it keeps its original expiry. Cancelling a parked run or turn withdraws its approval, and the audit trail keeps why.
Support staff signed in to your workspace under a grant cannot decide approvals unless the grant is full write mode.
The inbox, and the history
Sessions → Approvals shows approvals and human tasks you may decide, with filters by type, authority and readiness, and a decision drawer with an optional comment. The same decision can be made inline in the session, where the pending call sits with its exact arguments. Confirmations appear only in their conversation. See Approvals.
History is the permanent record of past decisions: approved, rejected, timed out or withdrawn, by whom, when, with the comment or the reason. It is built from the audit trail, which is never pruned and survives the deletion of the run or conversation it came from, and it covers the domains you currently belong to.
Expiry and notification
| Layer | Default window | On expiry |
|---|---|---|
| Agent confirmation | 4 h (per agent) | The call fails and the turn ends with an error; the timeout is audited |
| Agent approval | 72 h (per agent) | The call fails, the turn ends with an error, the audit trail records the timeout |
| Flow gate | 24 h (per step) | The step fails with APPROVAL_TIMEOUT and the run times out, or the branch closes |
| Human task | 24 h (per step) | The step fails with HUMAN_TASK_TIMEOUT and the run times out |
A call still waiting for more approvers expires the same way: the approvals already given do not run it.
When a gate parks work that nobody is watching - a scheduled or API-started turn, or any flow gate - the people who can decide it are emailed with the request and its deadline, and emailed again if it expires. A gate reached in a conversation someone is sitting in sends nothing; the person is already there. An agent whose Setup asks for it also sends one reminder a chosen time before an agent gate expires, to the audience the Setup names (a confirmation reminds only the person who was asked); flow gates have no reminder. See Notifications.
Missed schedules need a decision too
A schedule that could not fire on time - the platform was down, or the backlog ran past two minutes - does not silently run its missed occurrences later. They are parked as a catch-up batch on the trigger's own Approvals tab, with the window they cover, how many runs they would start against the organization's queue, and the schedule and input as they were saved. Anyone who manages the domain's triggers can approve all of them, a range, or just the first, or discard the rest. The trigger must be active to approve. These never appear in the Approvals inbox, because they are a decision about a schedule rather than about a side effect.
