AI Powered Commands

Introduction

CommandKit's @commandkit/ai plugin allows you to execute your bot commands using large language models. This enables you to use your bot's features entirely through natural language.

warning

This is an experimental feature and is subject to change.

Installation

npm install @commandkit/ai

You also need to install the AI SDK for the model you want to use. For example, if you want to use Google Gemini, you can install the @ai-sdk/google package:

npm install @ai-sdk/google

Refer to the AI SDKs documentation for more information on how to set up the AI SDK for your model.

Usage

commandkit.config.ts

import { defineConfig } from 'commandkit';
import { ai } from '@commandkit/ai';

export default defineConfig({
  plugins: [ai()],
});

Setting up the AI model

CommandKit allows you to dynamically specify the AI model to use for your bot.

src/ai.ts

import { createGoogleGenerativeAI } from '@ai-sdk/google';
import { configureAI } from '@commandkit/ai';

const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_API_KEY,
});

const model = google.languageModel('gemini-2.0-flash');

configureAI({
  // commandkit will call this function
  // to determine which AI model to use
  selectAiModel: async () => {
    return {
      model,
      // OPTIONAL: provider specific options
      options,
      // OPTIONAL: whether to use the object mode. Default is false.
      // If set to true, the AI will be able to generate object responses, such as creating polls or sending embeds.
      objectMode: false,
    };
  },
  messageFilter: async (message) => {
    // only respond to messages in guilds that mention the bot
    return (
      message.inGuild() && message.mentions.users.has(message.client.user.id)
    );
  },
  // OPTIONAL: set your own system prompt
  systemPrompt: async (message) => {
    return `You are a helpful AI discord bot. Your name is ${message.client.user.username} and your id is ${message.client.user.id}.
      You are designed to assist users with their questions and tasks. You also have access to various tools that can help you perform tasks.
      Tools are basically like commands that you can execute to perform specific actions based on user input.
      Keep the response short and concise, and only use tools when necessary. Keep the response length under 2000 characters.
      Do not include your own text in the response unless necessary. For text formatting, you can use discord's markdown syntax.
      ${
        // If the message is in a guild, include the guild name and id
        // Otherwise, mention that the message is in a direct message
        message.inGuild()
          ? `\nYou are currently in a guild named ${message.guild.name} whose id is ${message.guildId}. While in guild, you can fetch member information if needed.`
          : '\nYou are currently in a direct message with the user.'
      }`;
  },
});

Now you can simply import this file in your app.ts,

src/app.ts

import { Client } from 'discord.js';
// simply import the ai file
import './ai';

const client = new Client({...});

export default client;

Creating AI commands

AI commands can be created by exporting a function called ai from your command file. You can also export aiConfig object along with the ai function to specify the parameters for the command.

src/app/commands/balance.ts

import { ApplicationCommandOptionType } from 'discord.js';
import { CommandData, ChatInputCommand } from 'commandkit';
import { AiCommand } from '@commandkit/ai';
import { z } from 'zod';

export const command: CommandData = {
  name: 'balance',
  description: 'Get the current balance of the user.',
  options: [
    {
      name: 'user',
      description: 'The user to get the balance for.',
      type: ApplicationCommandOptionType.User,
    },
  ],
};

export const aiConfig: AiConfig = {
  parameters: z.object({
    userId: z.string().describe('The ID of the user to get the balance of'),
  }),
};

export const chatInput: ChatInputCommand = async (ctx) => {
  const { interaction } = ctx;
  const user = interaction.options.getUser('user');
  const balance = await db.getBalance(user.id);

  await interaction.reply({
    content: `The balance of ${user.username} is ${balance}`,
  });
};

// AI will call this function to get the balance of the user
export const ai: AiCommand = async (ctx) => {
  const { userId } = ctx.params;
  const balance = await db.getBalance(userId);

  // return object with the balance
  return {
    userId,
    balance,
  };
};

Now, you can simply mention the bot in a message to get the balance of the user. Eg:

@bot what is the balance of @user?

AI can also call multiple commands in a single message. Eg:

@bot show me the basic details of the user @user and also include the balance of that user.

The above prompt will call the built-in getUserInfo tool and the balance command.

Object Mode Example

Simply set the objectMode to true in the configureAI function to enable object mode. This allows the AI to generate object responses, such as creating polls or sending embeds.

@bot create a poll titled "What's your favorite game?" and answers should be
- minecraft
- fortnite
- pubg
- clash of clans