Configure custom nodes and marks

The AI Agent extension understands the content of the document and the possible elements (nodes and marks) that can be in it.

For example, the AI Agent extension detects the Table extension and knows how to generate tables. If the Table extension is not enabled and the user asks it to generate a table, the AI Agent will respond that the document doesn't support this type of element.

This is automatically done for all built-in Tiptap extensions. However, if you have an editor with custom nodes and marks, you need to configure the AI Agent extension so that it can generate and understand them.

Configure custom nodes

To configure custom nodes for the AI Agent, you need to follow these steps:

Define your custom Tiptap node extension
Configure the AI Agent with schema awareness information

Let's walk through each step with a practical example.

Step 1: Define a custom Tiptap node extension

First, create your custom node extension. Here's an example of a custom "Alert" node:

import { Node, mergeAttributes } from '@tiptap/core'

export const AlertNode = Node.create({
  name: 'alert',

  addOptions() {
    return {
      HTMLAttributes: {},
    }
  },

  addAttributes() {
    return {
      type: {
        default: 'info',
        parseHTML: (element) => element.getAttribute('data-type'),
        renderHTML: (attributes) => {
          if (!attributes.type) {
            return {}
          }
          return {
            'data-type': attributes.type,
          }
        },
      },
    }
  },

  parseHTML() {
    return [
      {
        tag: 'div[data-alert]',
      },
    ]
  },

  renderHTML({ HTMLAttributes }) {
    return [
      'div',
      mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {
        'data-alert': '',
      }),
      0,
    ]
  },
})

Add the extension to your editor:

import { Editor } from '@tiptap/core'
import { AlertNode } from './AlertNode'

const editor = new Editor({
  extensions: [
    // ... other extensions
    AlertNode,
  ],
})

Step 2: Configure the AI Agent

Now configure the AI Agent extension with schema awareness information about your custom node:

const provider = new AiAgentProvider({
  schemaAwarenessCustomElements: [
    {
      extensionName: 'alert',
      tag: 'div[data-alert]',
      name: 'Alert Box',
      description:
        'A highlighted box used to display important information, warnings, or tips to the user',
      // Describe the HTML attributes of the node as it is rendered in HTML
      attributes: [
        {
          name: 'data-alert',
          // Specify the "value" property if the attribute always has that value
          value: '',
          description: 'Indicates that this is an alert box',
        },
        {
          name: 'data-type',
          description: 'The type of alert: info, warning, error, or success',
        },
      ],
    },
  ],
})

Multiple custom elements

You can configure multiple custom nodes and marks at once. Here's an example with both an Alert node and a custom highlight marks:

const provider = new AiAgentProvider({
  schemaAwarenessCustomElements: [
    {
      extensionName: 'alert',
      tag: 'div[data-alert]',
      name: 'Alert Box',
      description: 'A highlighted box used to display important information, warnings, or tips',
      attributes: [
        {
          name: 'data-alert',
          value: '',
          description: 'Indicates that this is an alert box',
        }
        {
          name: 'data-type',
          description: 'The type of alert: info, warning, error, or success',
        },
      ],
    },
    // Custom marks are also configured in the same way
    {
      extensionName: 'customHighlight',
      tag: 'span',
      name: 'Custom Highlight',
      description: 'Highlights text with a special background',
      attributes: [
        {
          name: 'data-custom-highlight',
          value: '',
          description: 'Indicates that this is a custom highlight',
        }
      ],
    },
  ],
})

Best practices

When configuring custom nodes and marks for the AI Agent extension:

Use descriptive names: Choose clear, descriptive names that help the AI model understand what the element represents.
Provide detailed descriptions: Include comprehensive descriptions that explain both what the element is and how it's displayed or used.
Document all attributes: List all possible HTML attributes with their purposes and expected values.
Use consistent naming: Match the extensionName with your actual Tiptap extension name.
Specify HTML structure: Ensure tag and atributes match exactly how your extension renders HTML.

API Reference

The schemaAwarenessCustomElements option accepts an array of SchemaAwarenessItem objects with the following properties:

Property	Type	Required	Description
`extensionName`	`string`	Yes	The name of the Tiptap extension (must match exactly)
`tag`	`string`	Yes	The HTML tag or selector that represents this element
`name`	`string`	Yes	A human-readable name for the element
`description`	`string \| null`	No	Explanation of what the element is and how it's displayed
`attributes`	`SchemaAwarenessItemAttribute[]`	No	Array of possible HTML attributes for this element

SchemaAwarenessItemAttribute

Each attribute object in the attributes array has the following properties:

Property	Type	Required	Description
`name`	`string`	Yes	The name of the attribute in the HTML code
`value`	`string`	No	If specified, the attribute always has this exact value
`description`	`string \| null`	No	Explanation of the attribute's purpose and expected values