Approvals (Human-in-the-Loop)

Require human approval before sensitive tool calls execute. When an agent tries to call a gated tool, the run pauses until a team member approves or rejects the action.

How It Works

Add an approval block to your agent YAML to gate specific tools behind human approval. When the agent calls a gated tool, the run pauses and your team is notified.

Quick Start

Add an approval block to any agent YAML to gate specific tools:

approval:
  tools:
    - order_tools.delete_order
    - db_delete
  timeout: 3600
  message: "This action requires human approval before proceeding."

Deploy and any call to order_tools.delete_order or db_delete will pause the run and notify your team. See the full agent configuration reference for all available options.

Full Example

A complete agent with safe tools (no approval needed) and destructive tools (approval required):

version: "1.0"
name: order-manager
type: llm
model: gemini/gemini-2.5-flash
description: "Manages orders with approval-gated destructive actions"

system_prompt: |
  You are an order management assistant.
  Use lookup_order to find orders, process_refund for refunds,
  and cancel_order for cancellations.

  If a tool responds with "awaiting_approval", tell the user
  the action is pending human review.

temperature: 0.3

tools:
  - order_tools.lookup_order
  - order_tools.process_refund
  - order_tools.cancel_order

approval:
  tools:
    - order_tools.cancel_order
    - order_tools.process_refund
  timeout: 600
  message: "This order action requires manager approval."

In this example, lookup_order runs freely. Only cancel_order and process_refund are gated. The agent can look up order details first, then pauses only when it tries to perform a destructive action.

Conditional Approvals

Approval tools support condition expressions, the same syntax as conditional tools. When a condition is set, approval is only required when the expression evaluates to true. This lets you gate on the actual parameters of the tool call and middleware context values.

approval:
  tools:
    - order_tools.cancel_order                                          # always requires approval
    - order_tools.process_refund: param.amount > 50 and not context.is_admin  # conditional
  timeout: 600
  message: "This order action requires manager approval."

Rejection Behavior

By default, a rejected approval terminates the run with a FAILED status. Set on_rejection: continue to let the agent adapt instead. The tool call returns a rejection message to the LLM, and the agent can try an alternative approach, inform the user, or skip the action.

approval:
  tools:
    - order_tools.cancel_order
    - order_tools.process_refund: param.amount > 50
  timeout: 600
  message: "This order action requires manager approval."
  on_rejection: continue   # agent adapts instead of failing

Managing Approvals

The Approvals page in the sidebar shows all approval requests for the current environment. Pending approvals appear at the top.

You can also approve or reject from the run detail drawer. Click any row in the approvals table or open a run with “Awaiting Approval” status from the Agent Runs page. The approval card shows the tool name, parameters, and action buttons.

Notifications

When an approval is needed, all project members receive an email and in-app notification by default. Customize notification routing in the Notification Config drawer on the Approvals page:

• Choose which team members get notified for which agents (or all agents)
• Enable or disable notifications per member
• Members can also override their preferences in project notification settings

Webhook Integration

Add a webhook URL in the Notification Config to receive a POST request whenever an approval is needed. Use this to integrate with Slack, Teams, PagerDuty, or your own approval workflows.

{
  "type": "approval_requested",
  "approval_id": "a1b2c3d4-...",
  "run_id": "e5f6a7b8-...",
  "agent_name": "order-manager",
  "tool_name": "order_tools.cancel_order",
  "tool_params": {
    "order_id": "ORD-1234",
    "reason": "Customer requested cancellation"
  },
  "message": "This order action requires manager approval.",
  "timeout": 600,
  "created_at": "2026-04-05T10:30:00Z"
}

Multiple Approvals

If an agent calls multiple gated tools in sequence, each triggers a separate pause-approve cycle. The run status goes through:

Each resume loads the full conversation history including all previously executed and approved tools, so nothing is ever re-executed.

API

Approvals can be managed programmatically via the REST API. List pending approvals, approve or reject them, and configure notifications, all via API key authentication.

Audit Trail

Every approval decision is recorded in the audit log with the action, who made the decision, the tool name, and parameters. Approval traces also appear in the run's trace view, showing the wait duration and reviewer details.