Approvals

Human-in-the-loop checkpoint for sensitive agent actions

Overview

The Approvals page (ApprovalsPage) implements the human-in-the-loop approval workflow for AgenticMail Enterprise. When agents attempt actions that match configured approval policies (based on risk level or side effect type), the action is paused, a request is created, and it appears in the pending queue for human review. The page has two tabs: Pending (requests awaiting decision) and History (past decisions).

The page is organization-aware — when an org is selected via the context switcher, only agents from that org show approval requests.

How It Works

1. Agent triggers a sensitive action — For example, sending an email, executing code, or making a financial API call.
2. System checks approval policy — Based on the agent's permission configuration (risk level thresholds and side effect types).
3. Request is created — If approval is required, the action is paused and a request appears in the Pending tab with full context.
4. Admin reviews and decides — Click Approve or Reject. A rejection prompts a confirmation dialog.
5. Agent resumes or aborts — Approved actions are executed; rejected actions are cancelled. The agent receives the decision and adapts accordingly.

Key Concepts

Risk Levels

Approval Request Fields

Pending Approvals

The Pending tab shows all requests awaiting a decision. Each request is rendered as a card with:

• Action type — Bold header showing what the agent wants to do
• Description — Detailed explanation or JSON context of the action
• Agent badge — Shows which agent made the request (with avatar and name)
• Risk level badge — Color-coded risk assessment
• Approve button — Green, immediately approves and resumes the agent
• Reject button — Red, shows a confirmation dialog before rejecting

When no pending requests exist, an empty state is displayed: "No pending approvals — When agents need approval for sensitive actions, they'll appear here."

Approval History

The History tab shows the last 50 resolved requests in a table format:

Configuration

Approval policies are configured per-agent during creation (Step 4: Permissions in the Create Agent Wizard) or in the agent detail view. Key settings:

// Agent permission configuration
{
  "requireApproval": {
    "enabled": true,
    "forRiskLevels": ["high", "critical"],
    "forSideEffects": ["sends-email", "sends-message", "financial"],
    "approvers": [],
    "timeoutMinutes": 60
  }
}

API Reference

Decision Payload

POST /api/engine/approvals/{requestId}/decide
Content-Type: application/json

{
  "decision": "approved",     // or "rejected"
  "decidedBy": "admin",
  "reason": "Optional explanation for the decision"
}

Best Practices

• Start strict, loosen gradually — Begin with approvals required for all medium+ risk levels. As you build trust with specific agents, lower the threshold.
• Check the pending queue regularly — Agents are blocked while waiting for approval. Long waits degrade the agent's responsiveness.
• Use per-agent policies — A well-tested support agent may need fewer approvals than a newly created agent.
• Review history periodically — Patterns in approvals/rejections reveal whether permission settings need adjustment.
• Set appropriate timeouts — 60 minutes is the default. For time-sensitive actions, consider shorter timeouts with fallback behavior.
• Use the org context switcher — If managing multiple clients, filter by organization to focus on one client's requests at a time.

Troubleshooting