Docs contents

Approval gates

Approval gates let you pause a hosted agent before it executes a specific tool and require a human to approve or reject the call. Use them for high-stakes operations — sending emails, writing to a database, making payments — where you want a human in the loop before the action runs.

Enabling a gate

  1. Open an agent → Configuration → Tools
  2. Find the tool you want to gate and switch it from Auto-run to Approval required
  3. Save the agent

When the agent reaches that tool during a run, execution pauses and the agent's owner gets an in-app notification.

Approving or rejecting

Go to the Approvals page (or click the notification) to see pending approval requests. Each request shows:

  • Which agent and run triggered it
  • The tool name and the exact arguments the agent wants to pass
  • When the request expires

Approve — the agent continues and the tool call executes with the shown arguments.
Reject — the call is not executed. The agent is told the call was rejected and must not be retried; it skips that item and continues with the rest of its task.

A run whose every gated call was rejected ends cancelled. Inside a pipeline, its caller (a manager agent through invoke_agent, or a script) still gets its output, as a result with status: "declined", and the pipeline continues.

Approval expiry

Each approval request expires after 24 hours. If no decision is made before the deadline, the call is not executed and the run fails with "Approval request expired without a decision."

Via API

You can list and decide approvals programmatically with a workspace key, through the control plane.

# List pending approvals
curl -X POST https://agentos-ai.dev/api/v1/rpc/approvals_list \
  -H "Authorization: Bearer aos_ws_..." \
  -H "Content-Type: application/json" \
  -d '{}'

# Decide
curl -X POST https://agentos-ai.dev/api/v1/rpc/approvals_decide \
  -H "Authorization: Bearer aos_ws_..." \
  -H "Content-Type: application/json" \
  -d '{ "approval_id": "<approvalId>", "decision": "approved" }'

decision options: "approved" | "rejected". Add an optional decision_note.

Notifications

When a gate fires, the agent's owner gets an in-app notification. Owners, admins and members can all decide approvals from the Approvals page.

Best practices

  • Gate only the tools that actually need human oversight — over-gating creates friction and causes runs to time out
  • Write a clear system prompt describing what the agent should do when a tool call is rejected
  • Give every gated agent an owner, so each approval reaches someone who will answer it