Tiptap Docs

Available tools

The Tiptap AI Toolkit provides a comprehensive set of tools for interacting with Tiptap documents. These tools enable reading content, making edits, and navigating through large documents efficiently.

The tool definitions are available in the format of popular AI provider libraries:

When you add the tool definitions to your AI provider library, your AI agent will generate tool calls. You can then execute the tool calls using the executeTool method.

// Insert content at the current selection
await agent.executeTool({
  toolName: 'insertContent',
  input: {
    html: '<h1>New Document</h1><p>This is completely new content.</p>',
    position: 'selection',
  },
})

insertContent

Insert HTML content at a specific position of the document.

Parameters

  • html (string): The HTML content to insert
  • position ('document' | 'documentStart' | 'documentEnd' | 'selection' | 'selectionStart' | 'selectionEnd'): Where to insert the content
    • 'document': Replace the entire document with the HTML content
    • 'documentStart': Insert the HTML content at the start of the document
    • 'documentEnd': Insert the HTML content at the end of the document
    • 'selection': Replace the current selection with the HTML content
    • 'selectionStart': Insert the HTML content before the selection
    • 'selectionEnd': Insert the HTML content after the selection

applyDiff

Apply targeted edits via diffs to make precise changes to document content.

Parameters

  • diffs (Diff[]): Array of diffs to apply in sequence
    • context (string): Context string to help locate the correct position. Must be an exact match.
    • delete (string): The content to delete from the document. Must be an exact match.
    • insert (string): The content to insert in place of the deleted content. It can be empty for pure deletions.

readNodeRange

Read part of the document by specifying a range of nodes to read. This tool allows efficient processing of large documents, so that, if the document is too large, the context window of the AI model is not exceeded. The AI can precisely jump to specific positions in the document, to see their content and edit them.

Parameters

  • nodeRange (string): A string representing the range of the document to read.

If the provided node range is too large, the AI Toolkit reads the first part of it, and informs the AI of what part of the document was actually read. If the range is outside the bounds of the document, the AI Toolkit handles it gracefully and informs the AI model of the mistake.

Result

  • totalNodeCount: The total number of top-level nodes in the document
  • activeNodeRange: The actual range of nodes that were read
  • content: The HTML content of the nodes that were read

readSelection

Get the currently selected content in the editor.

Parameters

No parameters required.

Result

  • selection (string): The selected HTML content
  • nodeRange: The range of nodes that were read, so that the AI can precisely jump to the place where the selection is located.