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
})

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
})

Run finished handler

The onRunFinished handler is called when an AI Agent run is finished.

const provider = new AiAgentProvider({
  onRunFinished: (context) => {
    console.log('Run finished')
    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 LLM integration options

These configuration options let you integrate the AI Agent with your custom LLM and backend service. To learn more, read the Custom LLM 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 message adapter

The adapter option allows you to customize how the LLM messages are converted to a format that can be parsed by the Tiptap AI Agent extension.

const provider = new AiAgentProvider({
  adapter: customAdapter,
  // ... Other options
})

By default, the AI Agent uses the openaiChatCompletionsAdapter which is compatible with the OpenAI Chat Completions API. The library also includes adapters for other LLM providers and AI Agent frameworks.

Custom LLM message format

The createLlmMessages option allows you to customize how the chat messages are converted to a format that can be sent to the LLM. In 99% of the cases, using a custom adapter is enough, so you won't need to customize this option.

const provider = new AiAgentProvider({
  createLlmMessages: (messages, adapter) => {
    // Your custom logic to convert the chat messages to the format
    // expected by your LLM provider
    return messages.map((message) => ({
      role: message.type === 'ai' ? 'assistant' : 'user',
      content: message.text,
    }))
  },
  // ... Other options
})

Custom tools

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

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

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

Key configuration options