AI Agent 扩展配置选项

Tiptap 的 AI Agent 扩展接受多种配置选项。这些设置在创建新实例时传递给 AiAgentProvider。

认证

要使用 AI Agent 扩展，您需要提供 Tiptap Cloud 的认证凭证。

const provider = new AiAgentProvider({
  // 您的 Tiptap 内容 AI 应用 ID
  appId: 'APP_ID_HERE',
  // 您生成的 JWT 令牌
  token: 'YOUR_TOKEN',
})

模型选择

通过设置 modelName 选项，配置在 Tiptap Cloud 中使用的 OpenAI 模型。AI Agent 在使用 gpt-4.1 模型时表现最佳，因为它在复杂文档编辑任务中提供最佳性能。请注意，模型需要支持函数调用。

const provider = new AiAgentProvider({
  modelName: 'gpt-4.1',
  // ... 其他选项
})

系统提示 (System prompt)

您可以为 AI Agent 定义一个自定义系统提示，当与 Tiptap Cloud 一起使用时生效。

const provider = new AiAgentProvider({
  systemPrompt: 'You are an AI agent that edits rich text documents...',
  // ... 其他选项
})

自动接受设置

autoAccept 选项控制 AI Agent 是否自动接受工具调用并继续运行，或停止并等待用户审核。

"always"：自动接受所有工具调用
"never"：从不自动接受工具调用
"onlyRead"：自动接受不修改内容的工具调用（默认）

const provider = new AiAgentProvider({
  autoAccept: 'onlyRead',
  // ... 其他选项
})

初始聊天消息

您可以提供初始聊天消息，以在 AI Agent 首次加载时填充对话。

const provider = new AiAgentProvider({
  initialChatMessages: [
    {
      type: 'ai',
      text: '您好！我是您的 AI 助手。今天我能帮您做些什么？',
    },
  ],
  // ... 其他选项
})

自动检查点保存

autoSaveCheckpoints 选项允许在用户发送消息时自动保存检查点。

const provider = new AiAgentProvider({
  autoSaveCheckpoints: true,
  // ... 其他选项
})

当启用 autoSaveCheckpoints 选项时，检查点会在用户发送消息和调用工具前保存。如果您想自定义检查点的保存方式和时间，可以禁用此选项并手动使用 setCheckpoint() 方法。更多关于检查点的内容，请参阅检查点指南。

文档分块

chunkSize 选项控制读取时文档块的最大大小（以字符计）。chunkHtml 选项允许您自定义文档如何被分块。

const provider = new AiAgentProvider({
  chunkSize: 2000,
  chunkHtml: ({ html, chunkSize }) => {
    // 自定义逻辑将 HTML 分割成块
    // 必须返回 HTML 字符串数组
    return customSplitFunction(html, chunkSize)
  },
  // ... 其他选项
})

AI 变更扩展集成

useAiChangesExtension 选项决定是否使用 AI Changes 扩展来跟踪变更。

const provider = new AiAgentProvider({
  useAiChangesExtension: false,
  // ... 其他选项
})

请确保在实例化 Editor 实例时导入并配置 AI Changes 扩展，否则集成将无法正常工作。

事件处理程序

AI Agent 提供者支持多个事件处理程序，帮助您响应不同状态和操作：

状态变化处理器

onStateChange 处理器在 AI Agent 状态发生变化时调用。

const provider = new AiAgentProvider({
  onStateChange: (newState, previousState, context) => {
    console.log('状态变化:', newState)
    updateUI(newState)
  },
  // ... 其他选项
})

加载错误处理器

onLoadingError 处理器在加载 AI Agent 出错时调用。

const provider = new AiAgentProvider({
  onLoadingError: (error, context) => {
    console.error('加载错误:', error)
    showErrorNotification(error.message)
  },
  // ... 其他选项
})

工具调用处理器

onBeforeToolCall 和 onAfterToolCall 处理器分别在执行工具调用之前和之后调用。

const provider = new AiAgentProvider({
  onBeforeToolCall: (toolCall, context) => {
    console.log('工具调用前:', toolCall)
    showLoadingIndicator()
  },
  onAfterToolCall: (toolCall, context) => {
    console.log('工具调用后:', toolCall)
    hideLoadingIndicator()
  },
  // ... 其他选项
})

停止运行处理程序

当 AI 代理停止运行并且其生命周期完成时，将调用 onStopRunning 处理程序。

const provider = new AiAgentProvider({
  onStopRunning: (context) => {
    console.log('AI Agent 运行已结束')
    playCompletionSound()
  },
  // ... 其他选项
})

自定义 API 端点

您可以通过设置 baseUrl 选项指定 AI Agent 的自定义 API 端点。如果您正在运行自己的 Tiptap 内容 AI 服务实例，这将非常有用。

const provider = new AiAgentProvider({
  baseUrl: 'https://your-custom-api-endpoint.com',
  // ... 其他选项
})

自定义 AI Agent 集成选项

这些配置选项让您可以将 AI Agent 扩展集成到您自己的 AI Agent 中，而非 Tiptap Cloud 管理的 AI Agent。想了解更多，请阅读自定义 AI Agent 集成指南。

自定义解析器

resolver 选项允许您将 AI Agent 与自己的后端服务集成。该函数负责将聊天消息发送至 LLM 并返回响应。

const provider = new AiAgentProvider({
  resolver: async (options) => {
    // 您的自定义逻辑，将聊天消息发送给 LLM
    // 并返回响应
    const response = await yourCustomBackend.sendChatMessages(options)
    return response
  },
  // ... 其他选项
})

默认情况下，AI 代理使用 defaultAiAgentResolver，该解析器将聊天消息发送到 Tiptap Cloud。

自定义工具

toolHandlers 选项允许您定义 AI 代理可以调用的自定义客户端工具。此选项仅在您使用自己的后端与 AI 代理时有效。要了解如何设置自定义工具，请阅读自定义 AI 代理集成指南。

import { toolHandlersStarterKit } from '@tiptap-pro/extension-ai-agent'

const provider = new AiAgentProvider({
  toolHandlers: [
    toolHandlersStarterKit(),
    // ... 自定义工具处理器
  ],
  // ... 其他选项
})

自定义节点 (Custom nodes)

配置 AI Agent 扩展，使其能够生成和理解自定义节点。

const provider = new AiAgentProvider({
  schemaAwarenessCustomElements: [
    /* 自定义节点配置 */
  ],
})

关键配置选项

选项	类型	默认值	描述
`appId`	`string`	`""`	您的 Tiptap 内容 AI 应用 ID
`token`	`string`	`""`	用于认证的 JWT 令牌
`baseUrl`	`string`	`""`	AI 服务 API 的基础 URL
`modelName`	`AiAgentModelName`	`"gpt-4.1"`	要使用的 OpenAI 模型（推荐 gpt-4.1 和 gpt-4o）
`autoAccept`	`"always" \| "never" \| "onlyRead"`	`"onlyRead"`	控制是否自动接受 AI 变更
`autoSaveCheckpoints`	`boolean`	`false`	当用户发送消息时是否自动保存检查点
`chunkSize`	`number`	`1000`	读取文档时的块大小（以字符计）
`chunkHtml`	`Function`	`defaultChunkHtmlFunction`	自定义如何将文档拆分成块
`useAiChangesExtension`	`boolean`	`true`	是否使用 AI Changes 扩展
`initialChatMessages`	`ChatMessage[]`	`[]`	用于填充对话的初始聊天消息
`resolver`	`Function`	`defaultAiAgentResolver`	用于通过自定义后端解析 AI Agent 请求的函数
`toolHandlers`	`AiAgentToolCallHandler[]`	`toolHandlersStarterKit()`	自定义工具的处理器
`onStateChange`	`Function`	`undefined`	当 AI Agent 状态变化时调用的函数
`onLoadingError`	`Function`	`undefined`	加载 AI Agent 出错时调用的函数
`onBeforeToolCall`	`Function`	`undefined`	在执行工具调用之前调用的函数
`onAfterToolCall`	`Function`	`undefined`	在执行工具调用之后调用的函数
`onStopRunning`	`Function`	`undefined`	当 AI Agent 停止运行时调用的函数
`systemPrompt`	`string`	`undefined`	使用 Tiptap Cloud 时为 AI Agent 定义的自定义系统提示
`schemaAwarenessCustomElements`	`SchemaAwarenessItem[]`	`[]`	关于文档中可能包含的自定义节点的 AI 模型信息