Skip to content

defineBotCommand.mdx

Latest commit

 

History

History
96 lines (70 loc) · 3.93 KB

defineBotCommand.mdx

File metadata and controls

96 lines (70 loc) · 3.93 KB
Raw
title defineBotCommand
description Define a typed slash command — name, optional Standard Schema options, and a handler receiving CommandContext.

Overview

defineBotCommand defines a slash command with full type inference: ctx.options is inferred from the options schema. Commands are registered via createBot({ commands }) or bot.onCommand, and routed to the matching handler when the platform delivers an invocation.

Signature

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

function defineBotCommand<Schema extends ObjectSchema>(
  command: BotCommand<Schema>,
): BotCommand<Schema>;

Parameters

The command definition. Command name without the leading slash (e.g. `"triage"`). Matched case-insensitively. Help text; also the registration label on surfaces that register commands up front (e.g. a Discord-style application-command API). Optional Standard Schema for typed options. Used natively on surfaces that deliver structured args; on text-only surfaces (Slack) it's unused — read `ctx.text`. The command handler.

CommandContext

The conversation the command was invoked in. The invoked command name, normalized (no leading slash, lower-cased). Raw argument string after the command name — the form Slack delivers. Parsed, typed options. Populated on surfaces with native structured args; empty on text-only surfaces. The invoking user, when the surface provides it. The active surface, e.g. `"slack"`.

Usage

import { defineBotCommand } from "@copilotkit/bot";
import { z } from "zod";

const triage = defineBotCommand({
  name: "triage",
  description: "Summarize and file the current thread.",
  options: z.object({ priority: z.enum(["low", "high"]).optional() }),
  async handler({ thread, text }) {
    await thread.runAgent({ prompt: `Triage: ${text}` });
  },
});

A slash command's text is never posted to the channel, so it isn't in the history the adapter reconstructs — pass it to the agent explicitly with runAgent({ prompt }).

Behavior

  • Declare commands with the platform — platforms only deliver commands they know about. On Slack, every command must also be declared in the app configuration (the manifest's slash_commands section, or "Slash Commands" in the app settings); an undeclared command is silently dropped, even over Socket Mode. See the Slack quickstart.
  • Matching is case-insensitive and ignores the leading slash; commands delivered by the platform but not registered on the bot are ignored.
  • Up-front registration — on start(), declared commands are forwarded to adapters that implement registerCommands (e.g. a Discord-style application-command API); adapters without it, including Slack, are skipped.

Related