Skip to main content
Human-in-the-Loop functionality operates through Server-Sent Events (SSE) that notify your application when tool approvals are required and provide status updates throughout the approval process.

​
Core Approval Events

​
TOOL_EXECUTION_APPROVAL_REQUEST

Emitted when an agent requires human approval to execute one or more tools. This is the primary event that triggers approval UI in your application. 
{
  "type": "TOOL_EXECUTION_APPROVAL_REQUEST",
  "eventId": "evt_5",
  "threadId": "thread_456",
  "requestId": "req_1",
  "eventMessage": {
    "agent": null,
    "content": "",
    "collaborationId": null,
    "activeAssistantCollaborationRequired": null,
    "toolExecutionApprovalRequest": [
      {
        "toolId": "tool_123",
        "toolName": "google_calendar_create_event",
        "toolProvider": "GOOGLE_CALENDAR",
        "toolCategory": "CALENDAR",
        "toolExecutionId": "exec_123",
        "toolExecutionBatchId": "batch_456",
        "toolMemoryId": "mem_789",
        "toolArguments": {
          "event_title": "Project Review Meeting",
          "start_time": "2024-01-15T14:00:00Z",
          "end_time": "2024-01-15T15:00:00Z",
          "attendees": "john@company.com,mary@company.com",
          "location": "Conference Room A"
        },
        "approvalResult": "PENDING_HUMAN_APPROVAL"
      }
    ],
    "timestamp": "2025-08-12T00:00:03"
  }
}
Key Fields:
  • toolExecutionBatchId: Groups related tool executions that must be approved together
  • toolExecutionId: Unique identifier for this specific tool execution
  • toolArguments: The actual parameters the agent wants to pass to the tool
  • approvalResult: Always “PENDING_HUMAN_APPROVAL” for request events

​
Notification Events

These events provide status updates during the approval lifecycle:

​
NOTIFICATION_TOOL_EXECUTION_APPROVAL_REQUIRED

General notification that tool approval is needed. 
{
  "type": "NOTIFICATION_TOOL_EXECUTION_APPROVAL_REQUIRED",
  "eventId": "evt_1",
  "threadId": "thread_456", 
  "requestId": "req_1",
  "eventMessage": {
    "agent": null,
    "content": "tool execution requires approval",
    "collaborationId": null,
    "activeAssistantCollaborationRequired": null,
    "toolExecutionApprovalRequest": null,
    "timestamp": "2025-08-12T00:00:00"
  }
}

​
NOTIFICATION_TOOL_EXECUTION_APPROVAL_ACCEPTED

Emitted when a tool execution has been approved. 
{
  "type": "NOTIFICATION_TOOL_EXECUTION_APPROVAL_ACCEPTED",
  "eventId": "evt_1", 
  "threadId": "thread_456",
  "requestId": "req_1",
  "eventMessage": {
    "agent": null,
    "content": "tool execution approved",
    "collaborationId": null,
    "activeAssistantCollaborationRequired": null,
    "toolExecutionApprovalRequest": null,
    "timestamp": "2025-08-12T00:00:00"
  }
}

​
NOTIFICATION_TOOL_EXECUTION_APPROVAL_DENIED

Emitted when a tool execution has been denied. 
{
  "type": "NOTIFICATION_TOOL_EXECUTION_APPROVAL_DENIED",
  "eventId": "evt_1",
  "threadId": "thread_456",
  "requestId": "req_1", 
  "eventMessage": {
    "agent": null,
    "content": "tool execution denied",
    "collaborationId": null,
    "activeAssistantCollaborationRequired": null,
    "toolExecutionApprovalRequest": null,
    "timestamp": "2025-08-12T00:00:00"
  }
}

​
NOTIFICATION_TOOL_EXECUTION_APPROVAL_ABORTED

Emitted when a tool execution has been aborted with feedback. 
{
  "type": "NOTIFICATION_TOOL_EXECUTION_APPROVAL_ABORTED",
  "eventId": "evt_1",
  "threadId": "thread_456",
  "requestId": "req_1",
  "eventMessage": {
    "agent": null,
    "content": "tool execution aborted with feedback", 
    "collaborationId": null,
    "activeAssistantCollaborationRequired": null,
    "toolExecutionApprovalRequest": null,
    "timestamp": "2025-08-12T00:00:00"
  }
}

​
NOTIFICATION_TOOL_EXECUTION_INITIATED

Tool execution has started (after approval, if required). 
{
  "type": "NOTIFICATION_TOOL_EXECUTION_INITIATED",
  "eventId": "evt_1",
  "threadId": "thread_456",
  "requestId": "req_1",
  "eventMessage": {
    "agent": null,
    "content": "tool execution started",
    "collaborationId": null,
    "activeAssistantCollaborationRequired": null,
    "toolExecutionApprovalRequest": null,
    "timestamp": "2025-08-12T00:00:00"
  }
}

​
NOTIFICATION_TOOL_EXECUTION_IN_PROGRESS

Tool execution is currently running. 
{
  "type": "NOTIFICATION_TOOL_EXECUTION_IN_PROGRESS",
  "eventId": "evt_1",
  "threadId": "thread_456",
  "requestId": "req_1",
  "eventMessage": {
    "agent": null,
    "content": "tool execution in progress",
    "collaborationId": null,
    "activeAssistantCollaborationRequired": null,
    "toolExecutionApprovalRequest": null,
    "timestamp": "2025-08-12T00:00:00"
  }
}

​
Event Handling Implementation

const eventSource = new EventSource(`${API_BASE_URL}/${threadId}/stream`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  
  switch (data.type) {
    case 'TOOL_EXECUTION_APPROVAL_REQUEST':
      handleApprovalRequest(data.eventMessage.toolExecutionApprovalRequest);
      break;
      
    case 'NOTIFICATION_TOOL_EXECUTION_APPROVAL_REQUIRED':
      showApprovalRequiredNotification();
      break;
      
    case 'NOTIFICATION_TOOL_EXECUTION_APPROVAL_ACCEPTED':
      updateToolStatus('approved');
      break;
      
    case 'NOTIFICATION_TOOL_EXECUTION_APPROVAL_DENIED':
      updateToolStatus('denied');
      break;
      
    case 'NOTIFICATION_TOOL_EXECUTION_APPROVAL_ABORTED':
      updateToolStatus('aborted');
      break;
      
    case 'NOTIFICATION_TOOL_EXECUTION_INITIATED':
      showToolExecutionStarted();
      break;
      
    case 'NOTIFICATION_TOOL_EXECUTION_IN_PROGRESS':
      updateExecutionProgress();
      break;
  }
});

​
Next Steps

⌘I