Human-in-the-loop (HITL)

This covers the HITL integration and plugin, which works with Botpress’s built-in HITL dashboard and external helpdesk platforms (Zendesk, Intercom, etc.). This is separate from Botpress Desk.

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 the integration and the plugin to agent.config.ts. The plugin’s dependencies block points at the integration by alias:

import { defineConfig } from "@botpress/runtime"

export default defineConfig({
  name: "my-agent",

  defaultModels: {
    autonomous: "openai:gpt-4.1-mini-2025-04-14",
    zai: "openai:gpt-4.1-mini-2025-04-14",
  },

  dependencies: {
    integrations: {
      chat: "chat@1.0.0",
      webchat: "webchat@0.3.0",
      hitl: "hitl@2.0.2",
    },

    plugins: {
      hitl: {
        version: "hitl@1.3.0",
        dependencies: {
          hitl: {
            integrationAlias: "hitl",
            integrationInterfaceAlias: "hitl<hitlSession>",
          },
        },
      },
    },
  },
})

integrationAlias must match a key in dependencies.integrations. The ADK validates this at build time, so a typo here fails fast. integrationInterfaceAlias tells the plugin which interface entity the integration implements (hitlSession for the generic HITL integration, hitlTicket for Zendesk, and so on). The HITL plugin also accepts a top-level config object for plugin-wide behavior. See the HITL plugin’s Hub listing for the full set of fields.

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 swap the generic HITL integration for Zendesk, change the integration and update the alias. hitlTicket replaces hitlSession because Zendesk implements the interface with tickets instead of sessions:

dependencies: {
  integrations: {
    zendesk: "zendesk@1.0.0",
  },
  plugins: {
    hitl: {
      version: "hitl@1.3.0",
      dependencies: {
        hitl: {
          integrationAlias: "zendesk",
          integrationInterfaceAlias: "hitl<hitlTicket>",
        },
      },
    },
  },
},

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

HITL only works against a deployed bot. adk dev downloads the plugin into bp_modules/ and generates types, but handoffs need the integration’s real connection to your helpdesk, which is configured on the production bot.

​Add HITL to your agent

​Start a handoff

​Use a different provider

​Deploy and test

Add HITL to your agent

Start a handoff

Use a different provider

Deploy and test