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

Open an agent → Tools tab
Find the tool you want to gate and click the lock icon next to it
The lock turns amber and shows a "gated" label — save the agent

When the agent reaches that tool during a run, execution pauses and an in-app notification is sent to workspace members.

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 agent receives an error response for the tool call. How it handles rejection depends on the agent's prompt (it may retry, skip, or fail the run).

Approval expiry

Each approval request expires after 24 hours. If no decision is made before the deadline, the tool call is treated as rejected and the run continues or fails depending on the agent's logic.

Via API

You can approve or reject programmatically using a workspace key.

# List pending approvals
curl https://agentos-ai.dev/api/v1/approvals \
  -H "Authorization: Bearer aos_ws_..."

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

decision options: "approve" | "reject"

Notifications

When a gate fires, an in-app notification is sent to all workspace members with developer role or above. If you have an email channel configured on an alert rule for this agent, email notifications are sent too.

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
Set up an email channel on alert rules so approvers are notified even when not in the dashboard