createBot

Overview

createBot is the entry point of @copilotkit/bot. It wires one or more platform adapters to an AG-UI agent and returns a Bot — the surface for registering turn handlers, interaction handlers, interrupt handlers, slash commands, and tools, plus start() / stop() lifecycle control.

For a complete walkthrough, see the Slack quickstart.

Signature

import { createBot } from "@copilotkit/bot";

function createBot(opts: CreateBotOptions): Bot;

Parameters

<PropertyReference name="opts" type="CreateBotOptions" required> Bot configuration. <PropertyReference name="adapters" type="PlatformAdapter[]" required> The platform adapters to run, e.g. [`slack(...)`](/reference/bot/slack). `start()` brings every adapter up; `stop()` brings them down. </PropertyReference> <PropertyReference name="agent" type="AbstractAgent | ((threadId: string) => AbstractAgent)"> The AG-UI agent behind [`thread.runAgent()`](/reference/bot/classes/Thread) — a single instance or a per-conversation factory receiving the conversation's thread id. Optional: when omitted, calling `thread.runAgent()` throws. </PropertyReference> <PropertyReference name="actionStore" type="ActionStore" default="new InMemoryActionStore()"> Where snapshots of inline JSX handlers are persisted. The in-memory default loses actions on restart — see [ActionStore](/reference/bot/types/ActionStore) for the contract and durability tiers. </PropertyReference> <PropertyReference name="tools" type="BotTool[]"> Tools forwarded to the agent as frontend tools on every run. See [defineBotTool](/reference/bot/functions/defineBotTool). </PropertyReference> <PropertyReference name="context" type="ContextEntry[]"> Knowledge folded into the agent's context on each run. A `ContextEntry` is `{ description: string; value: string }`. </PropertyReference> <PropertyReference name="commands" type="BotCommand[]"> Slash commands to register up front — equivalent to calling `bot.onCommand` per command. See [defineBotCommand](/reference/bot/functions/defineBotCommand). </PropertyReference> </PropertyReference>

Return Value

<PropertyReference name="Bot" type="Bot"> The bot's registration and lifecycle surface. <PropertyReference name="onMention" type="(h: BotHandler) => void"> Register a turn handler. `BotHandler` receives `{ thread, message }` — a [`Thread`](/reference/bot/classes/Thread) and the incoming message (`{ text, user, ref, platform }`). On Slack one mention handler covers @-mentions, replies in threads the bot owns, and DMs. </PropertyReference> <PropertyReference name="onMessage" type="(h: BotHandler) => void"> Register a turn handler that fires only when **no** mention handler is registered — routing is mention-preferred (see Behavior). </PropertyReference> <PropertyReference name="onInteraction" type="<TValue>(id: string, h: (ctx: InteractionContext<TValue>) => void | Promise<void>) => void"> Escape-hatch handler for a known action `id`, bypassing the action registry. `ctx.action.value` is typed as `TValue`. Most bots don't need this — inline `onClick` handlers on [`Button`](/reference/bot/components/Button) are bound automatically. </PropertyReference> <PropertyReference name="onInterrupt" type="<TPayload>(eventName: string, h: (args: { payload: TPayload; thread: Thread }) => void | Promise<void>) => void"> Handle a captured agent interrupt (a LangGraph-style `on_interrupt` custom event). The handler typically posts a picker and resumes the run with [`thread.resume(value)`](/reference/bot/classes/Thread) when the user answers. </PropertyReference> <PropertyReference name="onCommand" type="(command: BotCommand) => void"> Register a slash command — a full [`BotCommand`](/reference/bot/functions/defineBotCommand), or the shorthand overload `onCommand(name, handler)` for a free-text command. Commands delivered by the platform but not registered here are ignored. </PropertyReference> <PropertyReference name="tool" type="(t: BotTool) => void"> Register a tool (alternative to `opts.tools`). Must be called before `start()` — the tool descriptors handed to the agent are computed at startup. </PropertyReference> <PropertyReference name="start" type="() => Promise<void>"> Bring all adapters up. Also forwards declared commands to adapters that implement `registerCommands` (e.g. a Discord-style application-command API); adapters without it — including Slack — are skipped. </PropertyReference> <PropertyReference name="stop" type="() => Promise<void>"> Bring all adapters down. </PropertyReference> </PropertyReference>

Usage

tsx

import { createBot } from "@copilotkit/bot";
import { slack, defaultSlackTools, defaultSlackContext } from "@copilotkit/bot-slack";

const bot = createBot({
  adapters: [
    slack({
      botToken: process.env.SLACK_BOT_TOKEN!,
      appToken: process.env.SLACK_APP_TOKEN!,
    }),
  ],
  agent: (threadId) => makeAgent(threadId),
  tools: [...defaultSlackTools, ...appTools],
  context: [...defaultSlackContext, ...appContext],
});

bot.onMention(async ({ thread }) => {
  await thread.runAgent();
});

await bot.start();

Behavior

Mention-preferred routing — there is no per-turn "kind": when any onMention handler is registered, all turns route to the mention handlers; otherwise onMessage handlers fire. Registering identical handlers on both never double-fires.
Expired actions are swallowed — a click whose snapshot is gone (e.g. after a restart with the in-memory store) raises ActionExpiredError internally; createBot swallows it, so the click is acked but ignored and no message is posted.
Commands are matched case-insensitively and without the leading slash.
No agent, no runAgent — omitting agent is fine for bots that only post UI, but thread.runAgent() will throw.

Thread — the per-conversation handle your handlers receive
defineBotTool — tools the agent can call
defineBotCommand — slash commands
ActionStore — action binding and durability
Slack quickstart — zero to a working bot