Skip to main content

​
Prerequisites

This document assumes you have already implemented basic Envole API integration following our API Integration Guide, including:
  • Authentication setup with Bearer tokens and X-Envole-User-Id headers
  • Thread creation and basic message posting
  • EventSource setup for SSE streaming
  • Basic event processing (AGENT_RESPONSE_CHUNK, AGENT_RESPONSE_COMPLETE)

​
Overview

Human-in-the-Loop (HITL) enables oversight and approval controls for AI agent tool executions. When agents attempt to execute sensitive tools (like sending emails, creating calendar events, or modifying databases), the system can pause execution and request human approval before proceeding. This approval system operates through Server-Sent Events (SSE) and provides fine-grained control over agent actions while maintaining a smooth user experience.

​
How Tool Approval Works

​
Basic Flow

  1. Agent Action: An agent attempts to execute a tool requiring approval
  2. Approval Request: System emits TOOL_EXECUTION_APPROVAL_REQUEST event
  3. Human Decision: User reviews tool arguments and decides to approve, deny, or abort
  4. Batch Response: All approvals in the batch are responded to simultaneously
  5. Tool Execution: Approved tools execute; denied/aborted tools are skipped
  6. Agent Response: Agent continues with execution results

​
Key Concepts

Tool Execution Batches: Multiple tool calls requiring approval are grouped by toolExecutionBatchId. All tools in a batch must be responded to together - individual responses will cause premature batch completion. Approval States: Each tool can be approved, denied, or aborted with feedback. Mixed states are allowed (approve some, deny others) except for aborts, which must stand alone. Content Integration: Tool approval responses are sent through the standard message API, with approval results included in the content field.

​
When to Use Human-in-the-Loop

Human oversight is valuable for:
  • High-stakes actions: Database modifications, financial transactions, external communications
  • Compliance requirements: Actions requiring audit trails or explicit approval
  • Learning systems: Allowing users to guide agent behavior through feedback
  • Quality control: Ensuring agent actions meet organizational standards

​
Next Steps

⌘I