Tiptap Docs

Execute tool (AI agents)

Use executeTool to apply a tool call from your AI agent to the editor.

Once you've added tool definitions to your AI agent, the AI agent will generate tool calls. Use the executeTool method to apply the tool calls to the editor.

executeTool

Executes a supported tool by name and input.

Parameters (ExecuteToolOptions)

  • toolName (string): Tool to execute. Can be one of the available tools.
  • input (unknown): A JSON object that matches the input schema of the tool parameters. If no parameters are required for this tool, pass an empty object ({}).
  • chunkSize? (number): The maximum size of a string that can be passed as input to the AI model. Prevents the AI from reading too much content at once so that the context window of the AI model is not exceeded. Default: 32000. This parameter is used by reading tools to control how the document is split into chunks.
  • reviewOptions? (ReviewOptions): Control preview/review behavior. See available options.
  • commentsOptions? (CommentsOptions): Options for comment and thread operations. This allows passing custom data to comment and thread creation/update operations. The data property is used for thread data, while commentData is used for comment data.
    • threadData? (Record<string, any>): Extra metadata for the AI-generated threads that are created with the editThreads tool
    • commentData? (Record<string, any>): Extra metadata for the AI-generated comments that are created with the editThreads tool
  • tiptapEditHooks? (TiptapEditHooks): Hooks for intercepting and modifying Tiptap Edit operations. See the Tiptap Edit hooks guide for details.
    • beforeOperation? ((context: BeforeOperationContext) => BeforeOperationResult): Called before each operation is applied. Return { action: 'accept' } to apply the operation (optionally with fragment or operationType overrides), or { action: 'reject', error } to skip it.

Returns (ExecuteToolResult)

  • output (object): Response object from the tool execution, to be read by the AI agent. The object structure varies depending on the tool executed.
  • hasError (boolean): Whether there was an error during execution
  • unknownTool (boolean): Whether the toolName is not recognized by the AI Toolkit
  • docChanged (boolean): Whether the tool call modifies the document.

Example 

// Handle the tiptapRead tool call
const result = toolkit.executeTool({
  toolName: 'tiptapRead',
  input: {
    from: 0,
  },
})

For a complete hands-on tutorial, see the AI agent chatbot guide.

streamTool

Updates the document in real-time while a tool call is streaming.

This method has the same effect as calling the executeTool method, but it edits the document incrementally while the tool call is streaming, instead of editing the document all at once when the tool call has finished streaming.

Parameters (StreamToolOptions)

  • toolCallId (unknown): The id of the tool call
  • toolName (string): Tool to execute. Can be one of the available tools.
  • input (unknown): A JSON object that matches the input schema of the tool parameters. If no parameters are required for this tool, pass an empty object ({}). If the tool has not finished streaming, this parameter should be a partial object with part of the parameters, but still a valid JSON object.
  • hasFinished? (boolean): Whether the tool has finished streaming. Default: false
  • chunkSize? (number): The maximum size of a string that can be passed as input to the AI model. Prevents the AI from reading too much content at once so that the context window of the AI model is not exceeded. Default: 32000. This parameter is used by reading tools to control how the document is split into chunks.
  • reviewOptions? (ReviewOptions): Control preview/review behavior. See available options.
  • commentsOptions? (CommentsOptions): Options for comment and thread operations. This allows passing custom data to comment and thread creation/update operations. The data property is used for thread data, while commentData is used for comment data.
    • threadData? (Record<string, any>): Extra metadata for the AI-generated threads that are created with the editThreads tool
    • commentData? (Record<string, any>): Extra metadata for the AI-generated comments that are created with the editThreads tool
  • tiptapEditHooks? (TiptapEditHooks): Hooks for intercepting and modifying Tiptap Edit operations. See the Tiptap Edit hooks guide for details.
    • beforeOperation? ((context: BeforeOperationContext) => BeforeOperationResult): Called before each operation is applied. Return { action: 'accept' } to apply the operation (optionally with fragment or operationType overrides), or { action: 'reject', error } to skip it.

Returns (StreamToolResult)

  • output (object): Response object from the tool execution, to be read by the AI agent. The object structure varies depending on the tool executed.
  • hasError (boolean): Whether there was an error during execution
  • unknownTool (boolean): Whether the toolName is not recognized by the AI Toolkit
  • docChanged (boolean): Whether the tool call modifies the document.

Example

The streamTool method is called repeatedly while the tool call is streaming. When the tool call has finished streaming, the streamTool method is called again with hasFinished: true to indicate that the tool call has finished streaming.

// Stream a tool call while it's being generated.
// Call `streamTool` again every time a new streaming part is received.
const result = toolkit.streamTool({
  // Tool is still streaming, so tool streaming has not finished yet
  hasFinished: false,
  toolCallId: 'call_123',
  toolName: 'tiptapEdit',
  // Content is still streaming, so we pass a partial object.
  input,
})

// When the tool call is complete, call it again with hasFinished: true
const finalResult = toolkit.streamTool({
  // Tool streaming has finished
  hasFinished: true,
  toolCallId: 'call_123',
  toolName: 'tiptapEdit',
  // Streaming is complete, so we can pass the full object
  input,
})

For a complete hands-on tutorial on streaming, see the streaming guide.

getActiveSelection

Returns the value of the activeSelection variable.

The active selection is the range that has been set by the AI Toolkit. When set, this range is used instead of the current editor selection in operations like tiptapReadSelection. The range is automatically mapped through transactions to maintain correct positions as the document changes.

Returns

  • Range | null: The active selection range with from and to properties, or null if no active selection is set.

Example 

const toolkit = getAiToolkit(editor)
const activeSelection = toolkit.getActiveSelection()

setActiveSelection

Sets the activeSelection variable. This variable is used when executing tool calls with the executeTool or streamTool methods, to determine what range the AI will use instead of the current editor selection in operations like tiptapReadSelection.

The active selection is the range that the AI should use instead of the current editor selection. The range is automatically mapped through transactions to maintain correct positions as the document changes.

Parameters

  • selection (Range | null): The range to set, with from and to properties indicating the start and end positions, or null to clear the active selection.

Example 

const toolkit = getAiToolkit(editor)
// Set the active selection to the current selection
toolkit.setActiveSelection(editor.state.selection)

// Set the active selection to a specific range
toolkit.setActiveSelection({ from: 10, to: 50 })

// Clear the active selection
toolkit.setActiveSelection(null)
PreviouslyEdit the document