Client-side tools

Client-side tools are tools that run in the browser. Use them to interact with the editor's content. For example:

Count the number of words in the document
Replace all instances of a word in the document
Format the document.

All built-in tools are client-side tools.

This guide shows how to implement a tool that replaces all occurrences of a word in the document with another word.

Client-side setup

Declare a tool call handler for your tool. Tool handlers are functions that apply the tool call in the editor. They must implement the AiAgentToolHandler interface.

import { z } from 'zod'

import type { AiAgentToolHandler } from '@tiptap-pro/extension-ai-agent'
import { ToolCallError, invalidArgumentsResponseFormatter } from '@tiptap-pro/extension-ai-agent'

// Schema for validating tool arguments
const replaceToolSchema = z.object({
  find: z.string(),
  replace: z.string(),
})

export const replaceToolHandler = (): AiAgentToolHandler => ({
  // Unique identifier for the tool
  name: 'replace',
  modifiesEditor: true,
  handleToolCall: ({ editor, state, toolCall }) => {
    // Validate the arguments
    const result = replaceToolSchema.safeParse(toolCall.arguments)
    if (!result.success) {
      // Return an error message to the AI
      throw new ToolCallError(invalidArgumentsResponseFormatter(result.error))
    }
    const args = result.data

    // Replace the word in the document
    const html = editor.getHTML()
    const replacedHtml = html.replaceAll(args.find, args.replace)
    const newHtml = editor.commands.setContent(replacedHtml)

    // Return a success message
    return 'Tool called successfully.'
  },
})

Then, add the tool to your AI Agent provider:

import { AiAgentProvider, toolHandlersStarterKit } from '@tiptap-pro/extension-ai-agent'

const provider = new AiAgentProvider({
  toolHandlers: [...toolHandlersStarterKit(), replaceToolHandler()],
})

The toolHandlersStarterKit contains the tool handlers for all the built-in tools. You can add your custom tool handlers to the array.

Server-side setup

On the server-side, define the tool. The tool definition contains the tool's ID, description, and JSON schema. This data is sent to the LLM to generate the tool calls. It must implement the AiAgentTool interface.

import type { AiAgentTool } from '@tiptap-pro/extension-ai-agent'

export const replaceTool = (): AiAgentTool => ({
  // Unique identifier for the tool. Must match the one in the tool handler
  name: 'replace',
  description: 'Replaces all occurrences of a word in the document with another word',
  parameters: {
    type: 'object',
    properties: {
      find: {
        type: 'string',
      },
      replace: {
        type: 'string',
      },
    },
    required: ['find', 'replace'],
  },
})

Then, add the tool to your AI Agent toolkit:

import { AiAgentToolkit, toolsStarterKit } from '@tiptap-pro/extension-ai-agent'

const toolkit = new AiAgentToolkit({
  tools: [...toolsStarterKit(), replaceTool()],
})

The toolsStarterKit contains the tool definitions for all the built-in tools. You can add your custom tool definitions to the array.