Agent Action Approval

The Agent Action Approval feature enables AI peers to request human approval before executing potentially sensitive or critical tool actions. This adds a safety layer for operations that require human oversight.

Overview

Agent Action Approval allows you to:

• Require Confirmation: AI requests approval before executing specific tools
• Custom Messages: Show contextual approval requests to users
• Maintain Flow: Conversation continues seamlessly after approval/rejection
• Audit Trail: Track all approval decisions
• Flexible Control: Configure per-tool or per-action

When to Use

Action Approval is essential for:

• ✅ Database modifications (DELETE, UPDATE operations)
• ✅ Financial transactions (payments, transfers)
• ✅ External API calls with side effects (sending emails, SMS)
• ✅ System changes (user management, settings)
• ✅ Publishing or distribution actions

Quick Start

1. Configure Peer Action

1. Navigate to Peer Settings → Actions
2. Select an action that should require approval
3. Enable "Require Approval" toggle
4. Save settings

2. Test in Chat

1. Send a message that triggers the action
2. AI peer recognizes approval is needed
3. User sees approval request with context
4. Click Approve or Reject
5. Action executes (if approved) and conversation continues

Configuration

Per-Action Approval

Admins can configure approval requirements for specific actions. When a protected action is triggered, the Peer pauses and requests confirmation.

Dynamic Approval Messages

You can use variables in approval messages to include context dynamically from the active request. For example, using parameters like or allows the Peer to automatically fill in details (e.g., "Delete john_doe (john@example.com)? This cannot be undone.").

User Experience

In Chat Interface

When approval is needed:

┌─────────────────────────────────────────────┐
│ AI: I need your approval to proceed.       │
│                                             │
│ 🔧 Action: Delete User                     │
│ Delete john_doe (john@example.com)?        │
│ This cannot be undone.                     │
│                                             │
│  [Approve ✓]    [Reject ✗]                 │
└─────────────────────────────────────────────┘

After decision:

User: [Clicked Approve]
AI: User deleted successfully. ✓

or

User: [Clicked Reject]
AI: Action cancelled. The user account was not deleted.

In WebChat

When using Webchat, approval requests display as interactive cards directly in the conversation window, featuring clear action titles, descriptive details, and Approve / Reject options.

How It Works

Agent Decision Flow

1. User sends message
    ↓
2. AI peer analyzes request
    ↓
3. AI determines action needed (e.g., "delete user")
    ↓
4. System checks if action requires approval
    ├─ Yes → Pause & show approval UI
    │         ↓
    │    User approves/rejects
    │         ↓
    │    Resume agent
    │         ├─ Approved → Execute action → Return result
    │         └─ Rejected → Skip action → Inform user
    └─ No → Execute action directly

Context Preservation

During approval wait:

• The pending action remains tied to the original conversation.
• The user sees the action, context, and decision controls in place.
• Approval continues the action; rejection cancels it cleanly.
• The decision is recorded for review.

For API and SDK integration details, see the Developer Hub.

Configuration Examples

When setting up approval rules, focus on clear messages that describe the action. Examples include:

• Database Operations: "Permanently delete record #{recordId}?" or "Update settings name from {oldValue} to {newValue}?"
• Financial Actions: "Charge {amount} {currency} to card ending in {cardLast4}?" or "Issue refund of {amount} to customer {customerName}?"
• Communication Actions: "Send email to {recipient} with subject '{subject}'?" or "Publish post '{title}'?"

Best Practices

Approval Message Design

✅ Good Messages:

"Delete invoice #12345 (total: $1,250.00)?"
"Send reminder email to 50 overdue customers?"
"Grant admin access to user@example.com?"
"Process refund of $99.99 to card ending in 4242?"

❌ Avoid:

"Continue?" (too vague)
"Execute action?" (no context)
"Are you sure?" (doesn't explain what)
"Approve?" (missing details)

Which Actions Need Approval?

Always Require Approval:

• Irreversible deletions
• Financial transactions
• Publishing/sending communications
• Privilege escalation
• External system changes

Consider Approval:

• Bulk operations
• Cost-incurring API calls
• Compliance-sensitive actions
• Cross-system updates

No Approval Needed:

• Read-only operations
• Internal calculations
• Temporary data changes
• User's own data access

Security Considerations

1. Validate Requests: Always verify the action details before approving
2. Audit Trail: Log all approval decisions for compliance
3. Timeout: Consider implementing approval timeouts for critical actions
4. Permissions: Ensure only authorized users can approve actions
5. Context: Always show sufficient context for informed decisions

Troubleshooting

Approval Not Triggered

Possible Causes:

• Action not configured to require approval
• Peer not using the action
• Configuration not saved

Solutions:

• Verify action settings in Peer configuration
• Check peer is using the correct tool/action
• Ensure changes were saved

Approval Does Not Continue

Possible Causes:

• Approval was not submitted
• User lacks permission to decide
• The original conversation or action changed

Solutions:

• Submit the approval again from the latest approval card
• Confirm the approver has the right role
• Re-run the original request if the approval is stale

Approval Message Missing Variables

Possible Causes:

• Variables not available in agent context
• Typo in variable name
• Tool not providing expected parameters

Solutions:

• Check tool output includes required fields
• Verify variable names match exactly
• Test tool execution separately

Advanced Features

Conditional Approval

Configure approval rules based on conditions:

Use conditional approval when only some cases need review. For example, small refunds might continue automatically, while large refunds pause for a manager.

Multi-Level Approval

Chain approvals for sensitive operations:

User Request
    ↓
AI determines action
    ↓
Manager Approval (via webhook)
    ├─ Approved → Director Approval
    │              ├─ Approved → Execute
    │              └─ Rejected → Cancel
    └─ Rejected → Cancel

Approval History

Track approval decisions:

Review approval history to see who approved or rejected an action, when the decision happened, and which action it applied to.

Integration Patterns

Pattern 1: WebChat with Approval

When a Peer is embedded through WebChat, approval requests appear in the chat experience so users can decide without leaving the conversation.

Pattern 2: Slack Integration

For channel-based workflows, route approval requests to the place where the user is already working and make the consequence clear before they decide.

Pattern 3: Mobile App

For mobile workflows, use approvals for time-sensitive decisions that need to reach a user away from their desk.

Related Documentation

• Peer Settings - General peer configuration
• Developer Hub - API and SDK documentation
• Flow User Approval - Approval in flows

Summary

Agent Action Approval provides essential human oversight for AI-driven operations:

• Safety: Prevent unintended actions
• Compliance: Meet regulatory requirements
• Control: Maintain human authority over critical decisions
• Flexibility: Configure per-action or per-tool
• Seamless: Integrated into chat and API flows

Key Benefits:

• Reduces risk of AI errors
• Provides audit trail
• Maintains user trust
• Enables gradual automation

Use Agent Action Approval to safely automate sensitive operations while keeping humans in control!