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' | 'activeNodeRange'): 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
    • 'activeNodeRange': Replace the content of the active node range with the HTML content

applyPatch

Make small precise edits to the document.

Parameters

  • patch (string): A string in the Universal Patch Format, a language developed by Tiptap for AI document editing. The Universal Patch Format is optimized for small, precise edits, and minimizes token costs when compared to other formats. A string in the Universal Patch Format encodes these operations:
    • jump: Goes to a specific position in the document
    • replace: Deletes some content and inserts new content in its place

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, and inform the AI model of the position of the selection.

Parameters

No parameters required.

Result

  • selection (string): The selected HTML content
  • activeNodeRange: The range of nodes where the selection is located

getThreads

Retrieve all threads and comments in the document. This tool provides comprehensive information about existing discussions and feedback in the document.

Parameters

No parameters required.

Result

The data of all the threads and comments in the document, including their content and location.

editThreads

Perform operations on threads and comments in the document. This tool enables comprehensive thread and comment management including creating, updating, and deleting threads and comments.

Parameters

  • operations (array): Array of operations to perform, each with a type field and operation-specific parameters.

Result

A success message if the operations were successful, or an error message if they were not.

Requirements

These tools require the Comments extension to be configured in the editor with a CommentsProvider. The tools are deactivated by default and need to be explicitly enabled.

PreviouslyAI agent tools