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

  • options (ExecuteToolOptions): Configuration for tool execution
    • 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
      • mode? ('disabled' | 'review' | 'preview'): Whether to review the changes before or after applying them. 'disabled' means no review, 'review' means review after applying, 'preview' means preview before applying. Default: 'disabled'
      • diffMode? ('detailed' | 'full'): How to display the difference between the original and the modified content, when review mode is enabled. 'detailed' compares the documents before and after the change and displays the deleted content and added content as a rich diff. 'full' displays the deleted content and added content in a whole block, as a single change containing the deleted and added content. Default: 'detailed'
      • displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize how suggestions are displayed
        • showAsDiff? (boolean): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default: true
        • diffPosition? ('before' | 'after'): The position of the diff relative to the suggestion. Default: 'before'
        • attributes? (Record<string, any>): Extra HTML attributes to be added to the suggestion
        • renderDecorations? (RenderDecorations<{ suggestion: Suggestion }>): A function to render the suggestion as ProseMirror decorations
      • metadata? (Record<string, any>): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
    • 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

Returns (ExecuteToolResult)

  • output (string): Response message from the tool execution, to be read by the AI agent.
  • 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 insertContent tool call
const result = toolkit.executeTool({
  toolName: 'insertContent',
  input: {
    html: '<p>Inserted content</p>',
    position: 'documentEnd',
  },
})

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

  • options (StreamToolOptions): Configuration for tool streaming
    • 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
      • mode? ('disabled' | 'review' | 'preview'): Whether to review the changes before or after applying them. 'disabled' means no review, 'review' means review after applying, 'preview' means preview before applying. Default: 'disabled'
      • diffMode? ('detailed' | 'full'): How to display the difference between the original and the modified content, when review mode is enabled. 'detailed' compares the documents before and after the change and displays the deleted content and added content as a rich diff. 'full' displays the deleted content and added content in a whole block, as a single change containing the deleted and added content. Default: 'detailed'
      • displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize how suggestions are displayed
        • showAsDiff? (boolean): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default: true
        • diffPosition? ('before' | 'after'): The position of the diff relative to the suggestion. Default: 'before'
        • attributes? (Record<string, any>): Extra HTML attributes to be added to the suggestion
        • renderDecorations? (RenderDecorations<{ suggestion: Suggestion }>): A function to render the suggestion as ProseMirror decorations
      • metadata? (Record<string, any>): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
    • 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

Returns (StreamToolResult)

  • output (string): Response message from the tool execution, to be read by the AI agent.
  • 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: 'insertContent',
  // Content is still streaming, so we pass a partial object.
  input: {
    position: 'documentEnd',
    // The HTML content has not fully been received yet
    html: '<p>HTML cont',
  },
})

// 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: 'insertContent',
  // Streaming is complete, so we can pass the full object
  input: {
    position: 'documentEnd',
    html: '<p>HTML content</p>',
  },
})

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

getActiveNodeRange

Returns the value of the activeNodeRange variable.

The active node range is the range of nodes that the AI has just read, and will be able to edit in the next tool call. It gives the AI the ability to edit only a specific range of nodes in the document and avoids exceeding the context window of the AI model when the document is too large.

Returns

  • NodeRange: The active node range, with from and to properties indicating the start and end node indices.

Example 

const toolkit = getAiToolkit(editor)
const activeNodeRange = toolkit.getActiveNodeRange()

setActiveNodeRange

Sets the activeNodeRange variable. This variable is used when executing tool calls with the executeTool or streamTool methods, to determine what range of nodes the AI will be able to edit in the next tool call.

The active node range is the range of nodes that the AI has just read, and will be able to edit in the next tool call. It gives the AI the ability to edit only a specific range of nodes in the document and avoids exceeding the context window of the AI model when the document is too large.

Parameters

  • nodeRange (NodeRange): The node range to set, with from and to properties indicating the start and end node indices.

Example 

const toolkit = getAiToolkit(editor)
toolkit.setActiveNodeRange({ from: 0, to: 5 })

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 readSelection. 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 readSelection.

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