SSE Events for Tool Approval

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

Learn about Batch Management for handling multiple approvals
Understand Approval States and their constraints
See Implementation Examples for complete code samples

Getting Started

Team Personal Assistants

Sub Assistants

Human-in-the-Loop API Guide

Multi-Assistant Collaboration API Guide

Core Approval Events

`TOOL_EXECUTION_APPROVAL_REQUEST`

Notification Events

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_REQUIRED`

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_ACCEPTED`

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_DENIED`

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_ABORTED`

`NOTIFICATION_TOOL_EXECUTION_INITIATED`

`NOTIFICATION_TOOL_EXECUTION_IN_PROGRESS`

Event Handling Implementation

Next Steps

​Core Approval Events

​TOOL_EXECUTION_APPROVAL_REQUEST

​Notification Events

​NOTIFICATION_TOOL_EXECUTION_APPROVAL_REQUIRED

​NOTIFICATION_TOOL_EXECUTION_APPROVAL_ACCEPTED

​NOTIFICATION_TOOL_EXECUTION_APPROVAL_DENIED

​NOTIFICATION_TOOL_EXECUTION_APPROVAL_ABORTED

​Related Tool Execution Events

​NOTIFICATION_TOOL_EXECUTION_INITIATED

​NOTIFICATION_TOOL_EXECUTION_IN_PROGRESS

​Event Handling Implementation

​Next Steps

Core Approval Events

`TOOL_EXECUTION_APPROVAL_REQUEST`

Notification Events

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_REQUIRED`

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_ACCEPTED`

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_DENIED`

`NOTIFICATION_TOOL_EXECUTION_APPROVAL_ABORTED`

Related Tool Execution Events

`NOTIFICATION_TOOL_EXECUTION_INITIATED`

`NOTIFICATION_TOOL_EXECUTION_IN_PROGRESS`

Event Handling Implementation

Next Steps