Human in the loop

Human-in-the-loop (HITL) enables human oversight of AI agent actions. When an agent needs to perform sensitive operations, such as modifying data, performing sensitive actions, or accessing restricted resources, the action is paused and routed to an authorized human for approval before execution.

This pattern ensures humans remain in control of high-stakes AI operations, providing safety, compliance, and trust in agentic workflows.

Why human-in-the-loop matters

AI agents are increasingly capable of taking autonomous actions, but certain operations require human judgement:

• Safety: Prevent unintended consequences from AI decisions.
• Compliance: Meet regulatory requirements for human oversight in sensitive domains.
• Trust: Build user confidence by keeping humans in control of critical actions.
• Accountability: Create clear audit trails of who approved what actions.
• Clarification: Allow the agent to request more information or guidance from users before proceeding.

HITL puts a human approval step in front of agent actions that carry risk or uncertainty.

How it works

Human-in-the-loop authorization follows a request-approval pattern over Ably channels:

1. The AI agent determines a tool call requires human approval.
2. The agent publishes an authorization request to the channel.
3. An authorized user receives and reviews the request.
4. The human approves or rejects the request.
5. The agent receives the decision, verifies the responder's identity or role and proceeds accordingly.

Request human approval

When an agent identifies an action requiring human oversight, it publishes a request to the channel. The request should include sufficient context for the approver to make an informed decision. The toolCallId in the message extras enables correlation between requests and responses when handling multiple concurrent approval flows.

The agent stores each pending request in some local state before publishing. When an approval response arrives, the agent uses the toolCallId to retrieve the original tool call details, verify the approver's permissions for that specific action, execute the tool if approved, and resolve the pending approval.

const channel = realtime.channels.get('job-map-new');
const pendingApprovals = new Map();

async function requestHumanApproval(toolCall) {
  pendingApprovals.set(toolCall.id, { toolCall });

  await channel.publish({
    name: 'approval-request',
    data: {
      name: toolCall.name,
      arguments: toolCall.arguments
    },
    extras: {
      headers: {
        toolCallId: toolCall.id
      }
    }
  });
}

Review and decide

Authorized humans subscribe to approval requests on the conversation channel and publish their decisions. The toolCallId correlates the response with the original request.

Use identified clients or user claims to establish a verified identity or role for the approver. For example, when a user authenticates with Ably, embed their identity and role in the JWT:

const claims = {
  'x-ably-clientId': 'user-123',
  'ably.channel.*': 'user'
};

The clientId and user claims are automatically attached to every message the user publishes and cannot be forged, so agents can trust this identity and role information.

const channel = realtime.channels.get('job-map-new');

await channel.subscribe('approval-request', (message) => {
  const request = message.data;
  const toolCallId = message.extras?.headers?.toolCallId;
  // Display request for human review
  displayApprovalUI(request, toolCallId);
});

async function approve(toolCallId) {
  await channel.publish({
    name: 'approval-response',
    data: {
      decision: 'approved'
    },
    extras: {
      headers: {
        toolCallId: toolCallId
      }
    }
  });
}

async function reject(toolCallId) {
  await channel.publish({
    name: 'approval-response',
    data: {
      decision: 'rejected'
    },
    extras: {
      headers: {
        toolCallId: toolCallId
      }
    }
  });
}

Process the decision

The agent listens for human decisions and acts accordingly. When a response arrives, the agent retrieves the pending request using the toolCallId, verifies that the user is permitted to approve that specific action, and either executes the action or handles the rejection.

Verify by user identity

Use the clientId to identify the approver and look up their permissions in your database or access control system. This approach is useful when permissions are managed externally or change frequently.

const pendingApprovals = new Map();

await channel.subscribe('approval-response', async (message) => {
  const response = message.data;
  const toolCallId = message.extras?.headers?.toolCallId;
  const pending = pendingApprovals.get(toolCallId);

  if (!pending) return;

  // The clientId is the trusted approver identity
  const approverId = message.clientId;

  // Look up user-specific permissions from your database
  const userPermissions = await getUserPermissions(approverId);

  if (!userPermissions.canApprove(pending.toolCall.name)) {
    console.log(`User ${approverId} not authorized to approve ${pending.toolCall.name}`);
    return;
  }

  if (response.decision === 'approved') {
    const result = await executeToolCall(pending.toolCall);
    console.log(`Action approved by ${approverId}`);
  } else {
    console.log(`Action rejected by ${approverId}`);
  }

  pendingApprovals.delete(toolCallId);
});

Verify by role

Use user claims to embed roles directly in the JWT for role-based access control (RBAC). This approach is useful when permissions are role-based rather than user-specific, allowing you to make authorization decisions based on the user's role without looking up individual user permissions.

Different actions may require different authorization levels. For example, an editor might be able to create drafts for review, but only a publisher or admin can approve publishing a blog post. Define approval policies that map tool names to minimum required roles, and when an approval arrives, compare the approver's role against the required role for that action type:

const roleHierarchy = ['editor', 'publisher', 'admin'];

const approvalPolicies = {
  publish_blog_post: 'publisher'
};

function canApprove(approverRole, requiredRole) {
  const approverLevel = roleHierarchy.indexOf(approverRole);
  const requiredLevel = roleHierarchy.indexOf(requiredRole);

  return approverLevel >= requiredLevel;
}

// When processing approval response
await channel.subscribe('approval-response', async (message) => {
  const response = message.data;
  const toolCallId = message.extras?.headers?.toolCallId;
  const pending = pendingApprovals.get(toolCallId);

  if (!pending) return;

  const policy = approvalPolicies[pending.toolCall.name];

  // Get the trusted role from the JWT claim
  const approverRole = message.extras?.userClaim;

  // Verify the approver's role meets the minimum required role for this action
  if (!canApprove(approverRole, policy)) {
    console.log(`Approver role '${approverRole}' insufficient: minimum required role is '${policy}'`);
    return;
  }

  if (response.decision === 'approved') {
    const result = await executeToolCall(pending.toolCall);
    console.log(`Action approved by role ${approverRole}`);
  } else {
    console.log(`Action rejected by role ${approverRole}`);
  }

  pendingApprovals.delete(toolCallId);
});