AI Agent extension configuration options

The AI Agent extension for Tiptap accepts different configuration options. These settings are supplied to the AiAgentProvider when creating a new instance.

Authentication

To use the AI Agent extension, you need to provide authentication credentials for Tiptap Cloud.

const provider = new AiAgentProvider({
  // Your Tiptap Content AI app id
  appId: 'APP_ID_HERE',
  // Your generated JWT token
  token: 'YOUR_TOKEN',
})

Model selection

Configure the OpenAI model that is used in Tiptap Cloud by setting the modelName option. The AI Agent works best with the gpt-4.1 model, as it provides the best performance for complex document editing tasks. Note that the model needs to support function calling.

const provider = new AiAgentProvider({
  modelName: 'gpt-4.1',
  // ... Other options
})

System prompt

You can define a custom system prompt for the AI Agent when using it with Tiptap Cloud.

const provider = new AiAgentProvider({
  systemPrompt: 'You are an AI agent that edits rich text documents...',
  // ... Other options
})

Auto accept settings

The autoAccept option controls whether the AI Agent should automatically accept a tool call and continue running, or whether it should stop and wait for user review.

• "always": Automatically accepts all tool calls
• "never": Never automatically accepts tool calls
• "onlyRead": Automatically accepts tool calls that don't modify content (default)

const provider = new AiAgentProvider({
  autoAccept: 'onlyRead',
  // ... Other options
})

Initial chat messages

You can provide initial chat messages to populate the conversation when the AI Agent is first loaded.

const provider = new AiAgentProvider({
  initialChatMessages: [
    {
      type: 'ai',
      text: 'Hello! I am your AI assistant. How can I help you today?',
    },
  ],
  // ... Other options
})

Automatic checkpoint saving

The autoSaveCheckpoints option allows you to automatically save checkpoints when the user sends a message.

const provider = new AiAgentProvider({
  autoSaveCheckpoints: true,
  // ... Other options
})

When the autoSaveCheckpoints option is enabled, checkpoints are saved before a user message is sent and before a tool is called. If you want to customize how and when checkpoints are saved, you can disable this option and use the setCheckpoint() method manually. Learn more about checkpoints in the Checkpoints guide.

Document chunking

The chunkSize option controls the maximum size of document chunks when reading (in characters). The chunkHtml option allows you to customize how the document is split into chunks.

const provider = new AiAgentProvider({
  chunkSize: 2000,
  chunkHtml: ({ html, chunkSize }) => {
    // Custom logic to split HTML into chunks
    // Must return an array of HTML strings
    return customSplitFunction(html, chunkSize)
  },
  // ... Other options
})

AI changes extension integration

The useAiChangesExtension option determines whether to use the AI Changes extension for tracking changes.

const provider = new AiAgentProvider({
  useAiChangesExtension: false,
  // ... Other options
})

Remember to import and configure the AI Changes extension when you instantiate the Editor instance, otherwise the integration will not work.

Event handlers

The AI Agent provider supports several event handlers to help you respond to different states and actions:

State change handler

The onStateChange handler is called whenever the state of the AI Agent changes.

const provider = new AiAgentProvider({
  onStateChange: (newState, previousState, context) => {
    console.log('State changed:', newState)
    updateUI(newState)
  },
  // ... Other options
})

Loading error handler

The onLoadingError handler is called when there's an error loading the AI Agent.

const provider = new AiAgentProvider({
  onLoadingError: (error, context) => {
    console.error('Loading error:', error)
    showErrorNotification(error.message)
  },
  // ... Other options
})

Tool call handlers

The onBeforeToolCall and onAfterToolCall handlers are called before and after a tool call is executed.

const provider = new AiAgentProvider({
  onBeforeToolCall: (toolCall, context) => {
    console.log('Before tool call:', toolCall)
    showLoadingIndicator()
  },
  onAfterToolCall: (toolCall, context) => {
    console.log('After tool call:', toolCall)
    hideLoadingIndicator()
  },
  // ... Other options
})

Stop running handler

The onStopRunning handler is called when the AI Agent stops running and its lifecycle is finished.

const provider = new AiAgentProvider({
  onStopRunning: (context) => {
    console.log('The AI Agent finished running')
    playCompletionSound()
  },
  // ... Other options
})

Custom API endpoint

You can specify a custom API endpoint for the AI Agent by setting the baseUrl option. This is useful if you're running your own instance of the Tiptap Content AI service.

const provider = new AiAgentProvider({
  baseUrl: 'https://your-custom-api-endpoint.com',
  // ... Other options
})

Custom AI Agent integration options

These configuration options let you integrate the AI Agent extension with your custom AI Agent instead of Tiptap Cloud's managed AI Agent. To learn more, read the Custom AI Agent integration guide.

Custom resolver

The resolver option allows you to integrate the AI Agent with your own backend service. This function is responsible for sending the chat messages to the LLM and returning the response.

const provider = new AiAgentProvider({
  resolver: async (options) => {
    // Your custom logic to send the chat messages to the LLM
    // and return the response
    const response = await yourCustomBackend.sendChatMessages(options)
    return response
  },
  // ... Other options
})

By default, the AI Agent uses the defaultAiAgentResolver which sends the chat messages to Tiptap Cloud.

Custom tools

The toolHandlers option allows you to define custom client-side tools that the AI Agent can call. This option only works when you're using the AI Agent with your own backend. To learn how to set up custom tools, read the Custom AI Agent integration guide.

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

const provider = new AiAgentProvider({
  toolHandlers: [
    toolHandlersStarterKit(),
    // ... custom tool handlers
  ],
  // ... Other options
})

Custom nodes

Configure the AI Agent extension so that it can generate and understand custom nodes.

const provider = new AiAgentProvider({
  schemaAwarenessCustomElements: [
    /* Custom node configuration */
  ],
})

Key configuration options