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): Tool-specific input payload
    • currentChunk (number): Current chunk index when reading/editing chunked content
    • 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

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
  • currentChunk (number): The current chunk index after execution, may be updated by some tools
  • 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',
  },
  currentChunk: 0,
})

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