Skip to Content
Approvals

Approvals

Keep a human in the loop before an agent does something it cannot undo. When an autonomous agent needs sign-off before a non-reversible action (a payment, an external send, a destructive operation) it calls the built-in request_approval tool. The run pauses, an approval request appears in the Approvals page, and an authorized reviewer approves or rejects. The run then resumes (on approve) or terminates (on reject).

A pending approval: a paused run with its escalation reason and Approve/Reject

How it works

  1. Agent requests approval. While running, the agent invokes the built-in tool:

    request_approval(reason="Send a $500 wire to ACME Corp", payload={...})

    The runtime creates an ApprovalRequest row, flips the run to waiting_approval, and emits an event.

  2. Reviewer is notified. The Approvals page polls every 10 seconds. Org admins and team_admins of the requesting agent’s team see the pending request in their queue.

  3. Reviewer decides. They click Approve or Reject in the UI, optionally adding a decision reason. The decision is recorded with decidedBy, decidedAt, decisionReason.

  4. Run resumes or terminates. On approve, the run goes back to running and continues from where it paused, with the approval result available as the tool call’s return value. On reject (or expiry), the run is cancelled with the rejection reason recorded as the cancellation reason.

Reviewing a refund approval with its reason and amount

Authorization

Who can approve depends on the resource’s team scoping:

  • Org-wide agents (visibility='org'): org owner or admin can approve.
  • Team-scoped agents (visibility='team'): org owner/admin OR the team’s team_admin (TeamRole.LEAD) can approve. Plain team members can see the pending request but not act on it.

This is enforced server-side via AccessPolicyService.canAccess(user, approvalRequest, 'manage').

Expiration

By default a pending approval times out after 24 hours (configurable up to 7 days when creating it via the API). A scheduled sweep flips expired requests to 'expired' and the corresponding run is cancelled with reason "approval expired".

Agent-side usage

Inside an autonomous agent’s instructions, instruct the model to gate sensitive actions:

You are a billing assistant. Before issuing any refund, transfer, or other
non-reversible action, call request_approval with a clear reason summarizing
what you intend to do and the relevant amounts/parties.

The tool returns when the human decides. Treat the returned value as the authorization to proceed.

Multi-step policies (Enterprise)

A single authorized reviewer is the free, default gate. If you need finance-then-admin chains, amount-conditional rules, or a two-reviewer quorum, approval policies (Enterprise) layer that on top of this flow.

API

List pending approvals, approve, and reject over REST. Responses are filtered to approvals the caller can see. See the API reference.

CredentialsOrganizations