# Tracked changes demo

Ask the AI to improve this document. AI edits are written as tracked changes so you can accept or reject them one by one.

## Experimental

The [Tracked Changes](/content/docs/tracked-changes/getting-started/overview/index.html) extension is currently in Alpha phase.

### Continuation from the AI agent chatbot guide

This guide continues the [AI agent chatbot guide](/content/docs/content-ai/capabilities/server-ai-toolkit/agents/ai-agent-chatbot/index.html). Read it first.

## How it works

1. The AI reads the document with `tiptapRead`.
2. The AI edits the document with `tiptapEdit` in `trackedChanges` mode.
3. The server writes tracked change marks instead of directly mutating the document.
4. The client displays the tracked changes and lets users accept or reject them.

## Show tracked changes

To display server-side AI edits as tracked changes, configure `reviewOptions` for `trackedChanges` mode when executing tools. See the [review options reference](/content/docs/content-ai/capabilities/server-ai-toolkit/api-reference/review-options/index.html) for all available settings.

### Execute tools with tracked changes

Pass `reviewOptions` when calling `execute-tool`:

```javascript
import { getAuthHeaders } from '@/lib/server-ai-toolkit/get-auth-headers'

const result = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    schemaAwarenessData,
    sessionId,
    experimental_documentOptions: {
      documentId: 'your-document-id',
      userId: 'ai-assistant',
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
  }),
})
```

See the [review options reference](/content/docs/content-ai/capabilities/server-ai-toolkit/api-reference/review-options/index.html) for the full `reviewOptions` shape, including `trackedChangesOptions` and `diffUtilityOptions`.

### Client-side setup

On the client, add the `ServerAiToolkit` and `TrackedChanges` extensions. The `TrackedChanges` extension must be configured with `enabled: false` because the server enables it automatically when writing tracked changes.

```javascript
import { useChat } from '@ai-sdk/react'
import { Collaboration } from '@tiptap/extension-collaboration'
import { EditorContent, useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'
import { TiptapCollabProvider } from '@tiptap-pro/provider'
import { ServerAiToolkit } from '@tiptap-pro/server-ai-toolkit'

export default function Page() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit.configure({ undoRedo: false }),
      Collaboration.configure({ document: doc }),
      TrackedChanges.configure({ enabled: false }),
      ServerAiToolkit,
    ],
  })

// ... render editor and chat UI
}
```

After the AI edits the document, the changes appear as tracked changes. Users can accept or reject them using the `acceptSuggestion`, `rejectSuggestion`, `acceptAllSuggestions`, and `rejectAllSuggestions` commands from the Tracked Changes extension.

## Add comments with tracked changes

You can make the AI provide a justification for each change. Each justification becomes a comment thread linked to its tracked change, using the [Comments](/content/docs/comments/getting-started/overview/index.html) extension.

### API endpoint

When fetching tool definitions, pass the top-level `operationMeta` option to add a `meta` field to `tiptapEdit` operations. Then instruct the AI to provide a justification in that `meta` field.

```javascript
const response = await fetch(`${apiBaseUrl}/toolkit/tools`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    schemaAwarenessData,
    tools: {
      tiptapEdit: true,
    },
    operationMeta: 'Brief justification explaining why this change improves the document.',
  }),
})
```

### Execute tools with comments

Pass `experimental_commentsOptions` alongside `reviewOptions` when calling `execute-tool`:

```javascript
const result = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    schemaAwarenessData,
    sessionId,
    experimental_documentOptions: {
      documentId: 'your-document-id',
      userId: 'ai-assistant',
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
    experimental_commentsOptions: {
      threadData: { userName: 'Tiptap AI' },
      commentData: { userName: 'Tiptap AI' },
    },
  }),
})
```

Each non-empty `meta` field in the edit operations becomes a comment thread linked to its tracked change. The justification is stored as the thread's first comment content and as `suggestionReason` in the thread data.

### Client-side setup

On the client, add the `CommentsKit` extension with a `TiptapCollabProvider`:

```javascript
import { CommentsKit } from '@tiptap-pro/extension-comments'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'
import { ServerAiToolkit } from '@tiptap-pro/server-ai-toolkit'

const editor = useEditor({
  extensions: [
    StarterKit.configure({ undoRedo: false }),
    Collaboration.configure({ document: doc }),
    TrackedChanges.configure({ enabled: false }),
    ServerAiToolkit,
    CommentsKit.configure({
      provider, // Your TiptapCollabProvider instance
    }),
  ],
})
```

Users can review the tracked change and read the AI's justification in the comments sidebar.

## Next steps

- Learn about all available [tool definitions](/content/docs/content-ai/capabilities/server-ai-toolkit/agents/tools/index.html)
- Learn more about [review options](/content/docs/content-ai/capabilities/server-ai-toolkit/api-reference/review-options/index.html)
- Explore the [REST API reference](/content/docs/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api/index.html)
- Learn more about the [Tracked Changes](/content/docs/tracked-changes/getting-started/overview/index.html) extension