Approvals & HITL

How the approval queue works, what triggers human-in-the-loop

Approvals and Human-in-the-Loop (HITL)

This guide explains how the platform's human oversight system works, from triggering approval requests to reviewing and deciding them in the Agent Portal.

What Triggers HITL

A Human-in-the-Loop approval is created when an agent attempts a tool call that meets one or more of the following conditions:

Risk Threshold

Every tool call is assigned a risk score (0--100) based on the action type and context. If the score exceeds the configured threshold, the tool call is paused and an approval request is created instead of executing immediately.

Risk score ranges:

• 0--39 (Low) — within auto-approval threshold; the tool executes without human review.
• 40--69 (Medium) — requires review; approval request is created.
• 70--100 (High) — careful evaluation recommended; flagged as high-priority.

Tool Grant Conditions

When granting a tool to an agent in Agent Studio, builders can configure per-tool conditions:

• requireApproval: true — every invocation of this tool requires human approval, regardless of risk score.
• Rate limits — if a tool has been called too frequently within a time window, subsequent calls require approval.
• HITL requirements — specific parameter combinations or contexts that mandate human review.

Impact Classification

Each approval request is classified by impact type:

Approval Queue UI

The Approval Queue is accessible from the Agent Portal sidebar at /approvals.

Queue Overview

The page displays:

• Pending count badge — shows how many approvals are waiting for review.
• Auto-refresh — the queue refreshes every 30 seconds. A timestamp shows when the last refresh occurred.
• Manual refresh — click the refresh icon to force-reload.

Filtering and Sorting

The filter bar provides:

• Status filter — toggle between All, Pending, Approved, and Rejected.
• Impact filter — dropdown to filter by Financial, Data, External Comms, or Irreversible.
• Sort options — sort by Risk Score (highest first), Newest First, or SLA Deadline (most urgent first).

Approval Table

Each row in the table shows:

SLA Countdown

Each approval has an SLA deadline. The countdown timer:

• Shows hours and minutes remaining.
• Turns red and pulses when under 30 minutes.
• Shows "Expired" when the deadline has passed.
• Updates every 30 seconds.

Detail Modal

Click any row to open the Detail Modal showing:

• Full approval details (agent, action with formatted tool parameters, risk score, impact type).
• Reasoning chain — the platform's explanation of why this tool call was flagged.
• Timestamps (created, SLA deadline with countdown).
• Approve and Reject buttons with inline confirmation.

Making Decisions

Approve

Approving an approval request allows the tool call to execute. The agent proceeds with its task using the tool.

Reject

Rejecting an approval blocks the tool call. The agent is notified and typically provides an alternative response acknowledging the rejection.

Modify (Phase B3)

For supported tools, reviewers can approve with modifications. This sends a modified decision that re-executes the tool call with adjusted parameters specified by the reviewer.

Confirmation Dialog

All decisions require a confirmation step:

• From the table: a confirmation dialog appears asking you to confirm the action.
• From the detail modal: an inline confirmation overlay appears within the modal.

After confirming, the decision is applied optimistically (UI updates immediately) and then persisted to the server. If the server request fails, the optimistic update is reverted.

Email Notifications

The platform sends email notifications for approval requests based on user preferences (configured in the notification service):

• Approval request created — notifies configured approvers when a new request arrives.
• SLA approaching — reminder emails when the deadline is near.
• Decision made — notifies the requesting user when their approval is approved or rejected.

Email notifications are opt-in per user and per notification channel (in-app vs. email). See services/api-gateway/src/lib/notification-service.ts for the implementation.

Authorization: Who Can Decide

Not everyone can approve or reject requests. The authorization model follows a layered approach:

Configurable Approval Policy

If the tool grant has an approvalPolicy configured:

1. Admins — can always decide any approval (hardcoded override).
2. Explicit approvers — user IDs listed in approvalPolicy.approvers.
3. Approver groups — members of groups listed in approvalPolicy.approverGroups.
4. Self-approval — the user who triggered the action can only approve their own request if allowSelfApproval is explicitly set to true.

Legacy Fallback (No Policy)

If no explicit approval policy exists on the tool grant:

1. Admins — can always decide.
2. Agent owners — users listed in the agent's entitlements.owners.
3. Entitled users — users with access to the agent (based on visibility, allowed groups, roles, or users). Self-approval is not allowed in legacy mode.

Tenant Scoping

All approval operations are scoped to the user's tenant. Approvals for agents in other tenants are invisible and inaccessible.

Dimension 1 Filtering

The Portal approval queue applies an additional Dimension 1 filter: users only see approvals for agents they are entitled to access based on the agent's visibility settings and entitlement configuration.

Escalation Chains

Escalation is driven by the SLA mechanism:

1. When an approval is created, it has an SLA deadline (configurable per tool or per agent).
2. If the deadline is approaching and no decision has been made, escalation notifications are sent to backup approvers.
3. If the SLA expires, the platform can be configured to either auto-reject (safe default) or auto-escalate to a higher-tier approver group.

Escalation configuration is part of the tool grant conditions and approval policy setup in Agent Studio.

Temporal Workflow Integration

When an approval is decided, the platform signals the associated Temporal workflow:

1. The workflow is paused at a HITL checkpoint waiting for the approval.
2. The approvalResolved signal is sent to the Temporal workflow handle with the decision, reason, and any modifications.
3. The workflow resumes: if approved, the tool executes; if rejected, the workflow handles the rejection (typically by informing the user).

Audit Trail

Every approval decision is audit-logged with:

• The deciding user, timestamp, and reason.
• The approval ID and associated agent/tool.
• Risk level classification.
• Dimension 2 (Agent-to-Tool) access control dimension.

Audit events are viewable in the Admin Console trace explorer.

Related Guides

• Chat and Conversations — how tool calls appear in the chat UI
• Builder Access Control — configuring tool grants and HITL conditions
• Security and Compliance — audit logging and governance