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'
      • showDiff? (boolean): Whether to diff the documents before and after the change to display the change as a detailed diff. Default: false
      • 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.

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'
      • showDiff? (boolean): Whether to diff the documents before and after the change to display the change as a detailed diff. Default: false
      • 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.

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.