diff --git a/adk/advanced/assets/deflecting-bot.png b/adk/advanced/assets/deflecting-bot.png
new file mode 100644
index 00000000..6927d955
Binary files /dev/null and b/adk/advanced/assets/deflecting-bot.png differ
diff --git a/adk/advanced/assets/deflecting-dark.png b/adk/advanced/assets/deflecting-dark.png
new file mode 100644
index 00000000..ed69c9d0
Binary files /dev/null and b/adk/advanced/assets/deflecting-dark.png differ
diff --git a/adk/advanced/assets/deflecting.png b/adk/advanced/assets/deflecting.png
new file mode 100644
index 00000000..4e3e0991
Binary files /dev/null and b/adk/advanced/assets/deflecting.png differ
diff --git a/adk/advanced/assets/desk-main.png b/adk/advanced/assets/desk-main.png
new file mode 100644
index 00000000..b7e9a016
Binary files /dev/null and b/adk/advanced/assets/desk-main.png differ
diff --git a/adk/advanced/assets/desk-ui-dark.png b/adk/advanced/assets/desk-ui-dark.png
new file mode 100644
index 00000000..6b60caf0
Binary files /dev/null and b/adk/advanced/assets/desk-ui-dark.png differ
diff --git a/adk/advanced/assets/desk-ui.png b/adk/advanced/assets/desk-ui.png
new file mode 100644
index 00000000..b651bb9a
Binary files /dev/null and b/adk/advanced/assets/desk-ui.png differ
diff --git a/adk/advanced/desk-hitl.mdx b/adk/advanced/desk-hitl.mdx
new file mode 100644
index 00000000..f4cbc65c
--- /dev/null
+++ b/adk/advanced/desk-hitl.mdx
@@ -0,0 +1,136 @@
+---
+title: HITL with Desk
+description: Escalate conversations to support agents in Botpress Desk.
+---
+
+The `desk-hitl` plugin connects your agent to Botpress Desk for human handoff. When escalated, your agent calls `startHitl` to create a Desk ticket and a support agent takes over from there.
+
+
+ 
+ 
+
+
+## Add `desk-hitl` to your agent
+
+Add the plugin to `agent.config.ts`:
+
+```typescript
+import { defineConfig, z } from "@botpress/runtime"
+
+export default defineConfig({
+ name: "my-agent",
+
+ dependencies: {
+ integrations: {
+ webchat: "webchat@0.3.0",
+ },
+ plugins: {
+ "desk-hitl": {
+ version: "desk-hitl@latest",
+ },
+ },
+ },
+})
+```
+
+### Customize handoff messages
+
+Override the default messages the plugin sends when an agent joins or a session ends:
+
+```typescript
+plugins: {
+ "desk-hitl": {
+ version: "desk-hitl@latest",
+ config: {
+ agentAssignedMessage: "A support agent has joined the conversation.",
+ sessionEndedMessage: "The support session has ended. Is there anything else I can help you with?",
+ },
+ },
+},
+```
+
+## Connect your bot in Botpress Desk
+
+To enable escalations, link your bot to Botpress Desk from the Desk UI. This is a one-time step per bot. Your bot must be deployed at least once before it appears in the list.
+
+
+
+ Run `adk deploy` to deploy your bot.
+
+
+ Open [**Botpress Desk**](/desk/introduction).
+
+
+ Go to **AI Agents → Deflecting Bots**.
+
+
+ Add your bot.
+
+
+
+
+ 
+ 
+
+
+
+ If you skip this step, `startHitl` will fail with: _"This bot is not connected to Botpress Desk. Enable it on the Deflecting Bots page in Botpress Desk, then republish."_
+
+
+
+## Create an escalation tool
+
+Wrap `startHitl` in an `Autonomous.Tool` so the model can decide when to escalate. Create a file called `handToSupport.ts` under `src/tools/`:
+
+```typescript
+import { Autonomous, context, plugins, z } from "@botpress/runtime"
+
+export default new Autonomous.Tool({
+ name: "handToSupport",
+ description:
+ "Transfer the conversation to a support agent. Use when the user explicitly asks for a support agent, or when their issue is beyond the bot's capabilities.",
+ input: z.object({
+ reason: z.string().describe("Why the conversation needs a support agent"),
+ priority: z.enum(["low", "medium", "high", "urgent"]).default("medium"),
+ }),
+ handler: async ({ reason, priority }) => {
+ const conversation = context.get("conversation")
+
+ await plugins["desk-hitl"].actions.startHitl({
+ conversationId: conversation.id,
+ title: reason,
+ priority,
+ })
+ },
+})
+```
+
+Fields passed to `startHitl`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `conversationId` | `string` | The conversation to escalate — required |
+| `title` | `string` | Ticket title shown in Desk |
+| `priority` | `'low' \| 'medium' \| 'high' \| 'urgent'` | Ticket priority (default: `'medium'`) |
+| `userName` | `string` | Customer name shown in the Desk ticket |
+| `userEmail` | `string` | Customer email shown in the Desk ticket |
+
+## Use the tool in a conversation handler
+
+Add the tool to `conversations/index.ts` and instruct the model when to use it:
+
+```typescript
+import { Conversation } from "@botpress/runtime"
+import handToSupport from "../tools/handToSupport"
+
+export default new Conversation({
+ channel: "*",
+ handler: async ({ execute }) => {
+ await execute({
+ instructions: `You are a helpful support assistant.
+If the user needs help beyond your capabilities or explicitly asks for a support agent, use the handToSupport tool. After calling it, do not send any message.`,
+ tools: [handToSupport],
+ })
+ },
+})
+```
diff --git a/adk/advanced/hitl.mdx b/adk/advanced/hitl.mdx
index afce21d5..19ff56e0 100644
--- a/adk/advanced/hitl.mdx
+++ b/adk/advanced/hitl.mdx
@@ -1,10 +1,10 @@
---
-title: Human-in-the-loop
+title: Human-in-the-loop (HITL)
description: Escalate conversations to live human agents.
---
- This covers the HITL integration and plugin, which connects your agent to external helpdesk platforms (Zendesk, Intercom, etc.). This is separate from integrating your ADK agent with [Botpress Desk](/desk/introduction).
+ 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](/adk/advanced/desk-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).
diff --git a/docs.json b/docs.json
index e61161ce..d530c08a 100644
--- a/docs.json
+++ b/docs.json
@@ -523,7 +523,8 @@
{
"group": "Advanced",
"pages": [
- "/adk/advanced/hitl"
+ "/adk/advanced/hitl",
+ "/adk/advanced/desk-hitl"
]
},
{