Human-in-the-loop (HITL)

HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. It’s powered by two dependencies working together: the HITL integration (the transport to a helpdesk or agent platform) and the HITL plugin (the actions your code calls).

Add HITL to your agent

Add both from the CLI:

adk integrations add hitl
adk plugins add hitl

The plugin wires itself to the HITL integration automatically. If your project has more than one HITL-capable integration, point the plugin at the one to use with --dep <interface>=<integrationAlias>:

adk plugins add hitl --dep hitl=hitl

Set plugin-wide behavior with adk plugins configure hitl --set <key>=<value>, and connect the integration to your helpdesk from the Dev Console. Dependencies and their configuration live in Botpress Cloud, not in your project files. See Managing dependencies.

Start a handoff

Import plugins from @botpress/runtime and call startHitl from a conversation handler. All inputs are typed against the plugin:

import { Conversation, plugins } from '@botpress/runtime'

export default new Conversation({
  channel: ['chat.channel', 'webchat.channel'],
  handler: async ({ execute, conversation, message }) => {
    if (message.payload.text.toLowerCase() === '/starthitl') {
      await plugins.hitl.actions.startHitl({
        title: 'Support HITL',
        description: 'Escalate to support agent',
        conversationId: conversation.id,
        userId: message.userId,
        configurationOverrides: {
          onHitlHandoffMessage: 'Escalating to support...',
          userHitlCloseCommand: '/end',
          agentAssignedTimeoutSeconds: 100,
        },
      })
      return
    }

    await execute({
      instructions: 'You are a helpful assistant. If the user asks for a human, tell them to type /starthitl.',
    })
  },
})

The fields passed to startHitl:

Field	Description
title	Short label shown to the human agent when the ticket opens
description	Longer context the human agent sees alongside the conversation
conversationId	The conversation to hand off (use conversation.id from the handler)
userId	The user initiating the handoff
configurationOverrides	Optional per-handoff overrides of the plugin config

Common override fields:

Field	Description
onHitlHandoffMessage	Message sent to the user when the handoff begins
userHitlCloseCommand	Message text the user can send to close the session
agentAssignedTimeoutSeconds	How long to wait for a human agent to pick up before timing out

For the full set of override fields, see the HITL plugin’s Hub listing.

Use a different provider

The HITL plugin works with any integration that implements the HITL interface. To use Zendesk instead of the generic HITL integration, add it and point the plugin at it:

adk integrations add zendesk
adk plugins configure hitl --map hitl=zendesk

Your application code doesn’t change. plugins.hitl.actions.startHitl works the same regardless of which integration is wired underneath.

Deploy and test

Run adk deploy to push the agent to Botpress Cloud. See the CLI reference for all deploy flags:

adk deploy