Use Cases

Workflow Approval Gates (HIL Approvals)

A workflow reaches an approval node. The HumanInLoopNode creates an approval interaction request targeted at the approver's user ID (or their role). The workflow suspends. The approver sees the request in their WorkDesk HIL Inbox and clicks Approve or Reject. The workflow resumes with the decision.

Interaction type: approval — supports Approve, Reject, and Abstain outcomes. The payload can include contextual fields (invoice total, requester name, etc.).

// Server — HIL node publishes the approval
await interactionPublisher.PublishAsync(approverId, new InteractionRequest {
  type: 'approval',
  title: 'Invoice Approval Required',
  payload: {
    context: 'Invoice #INV-2026-0042 for $12,500 requires your approval.',
    fields: [
      { key: 'vendor', label: 'Vendor', value: 'Acme Corp' },
      { key: 'amount', label: 'Amount', value: '$12,500.00' }
    ]
  },
  timeoutMs: 86400000 // 24 hours
});

Destructive Action Confirmation

Before a workflow performs a destructive operation (deleting records, sending bulk emails, wiping a dataset), the system sends a confirmation interaction to the triggering user. The workflow pauses until the user confirms or cancels.

Interaction type: confirmation — simple Yes/No/Cancel dialog. Fast and lightweight.

// Octopus agent requests human confirmation before destructive action
const response = await useInteraction({
  type: 'confirmation',
  targetUserId: currentUser.id,
  title: 'Delete All Test Records?',
  payload: {
    message: 'This will permanently delete 1,432 test records. This cannot be undone.',
    confirmLabel: 'Yes, Delete All',
    cancelLabel: 'Cancel'
  },
  timeoutMs: 300000 // 5 minutes
});

Mid-Workflow Form Collection

A workflow needs structured input from the user at a specific stage — for example, collecting shipping details before generating a dispatch order. The workflow sends a form interaction with an Atlas Form schema. The user fills in the form and submits. The submitted data is returned as the response payload.

Interaction type: form — renders any Atlas Form by formId. Response contains all submitted field values.

Dynamic Option Selection

An agent or workflow generates a dynamic list of options and needs the user to select one or more. For example: "Which of these email templates should I use?" or "Select the target environments for deployment." The picker type renders a list with single or multi-select support.

Interaction type: picker — supports single and multiple selection. Response contains { selectedIds: string[] }.

Acknowledged Notifications

Compliance scenarios require that users explicitly acknowledge receipt of a notification — for example, a policy update, a security alert, or a system maintenance window. The notification type renders a read-only message with an Acknowledge button. The server knows exactly when and who acknowledged.

Interaction type: notification — read-only message with acknowledge button. Supports severity: info, warning, error.

Multi-Party / Role-Based Approvals

When an approval requires any member of a team (e.g., any Finance Manager), the interaction is targeted at a role rather than a specific user. All users with that role receive the interaction. The first to respond closes the interaction for all others. This is the "first-to-respond wins" pattern.

Implementation: Set targetUserId to a role key (e.g., "role:finance-managers"). EdgeInteract fans out to all sessions for users with that role. After the first response, remaining sessions receive a dismissal signal.