AI Agent extension API reference

export interface AiAgentEventContext {
  editor: Editor
  provider: AiAgentProvider
}

export type EventHandlers = {
  loadingError: (error: unknown, context: AiAgentEventContext) => void
  stateChange: (
    state: AiAgentProviderState,
    previousState: AiAgentProviderState,
    context: AiAgentEventContext,
  ) => void
  beforeToolCall: (toolCall: AiAgentToolCall, context: AiAgentEventContext) => void
  afterToolCall: (toolCall: AiAgentToolCall, context: AiAgentEventContext) => void
  stopRunning: (context: AiAgentEventContext) => void
}

/**
 * Configuration options for the AI Agent provider
 */
export interface AiAgentProviderOptions extends Omit<BaseAiAgentProviderOptions, 'onStateChange'> {
  /**
   * Application ID for authentication with the AI service.
   */
  appId: string

  /**
   * Authentication token for the AI service.
   */
  token: string

  /**
   * Base URL of the AI service API.
   */
  baseUrl: string

  /**
   * Initial chat messages of the conversation with the AI Agent.
   * @default []
   * @example
   * [
   *   {
   *     type: 'ai',
   *     text: "Hello, I'm an AI assistant that can edit your document. How can I help you?",
   *   },
   * ]
   */
  initialChatMessages: ChatMessage[]

  /**
   * Controls whether checkpoints are automatically saved when user sends a message or accepts a tool call.
   * If false, the setCheckpoint function is not called.
   * @default false
   */
  autoSaveCheckpoints: boolean

  /**
   * Options for reviewing changes that are made to the document by the AI Agent.
   */
  reviewOptions: AiAgentReviewOptions

  /**
   * The OpenAI model to use for the AI Agent.
   * Recommended models are gpt-4.1 and gpt-4o as they work best with the AI Agent.
   * The model needs to support tool calling.
   * @default "gpt-4.1"
   */
  modelName: AiAgentModelName

  onLoadingError: EventHandlers['loadingError']
  onStateChange: EventHandlers['stateChange']
  onBeforeToolCall: EventHandlers['beforeToolCall']
  onAfterToolCall: EventHandlers['afterToolCall']
  /**
   * Callback that is invoked when the AI Agent stops running.
   */
  onStopRunning: EventHandlers['stopRunning']

  /**
   * Function to resolve the AI Agent request. Lets you integrate the AI Agent with your own backend service.
   * @param options The options for the AI Agent request, including the chat messages, tool handlers, and model name.
   * @returns The chat messages and tool call messages from the AI service
   * @default defaultAiAgentResolver
   */
  resolver: (options: AiAgentResolverOptions) => Promise<AiAgentResolverReturn>

  /**
   * System prompt to use with the AI Agent. Overrides the default system prompt
   * when using the AI Agent with Tiptap Cloud.
   */
  systemPrompt: string | null

  /**
   * Custom nodes that the AI Agent should be aware of.
   */
  schemaAwarenessCustomElements: SchemaAwarenessItem[]
}

export type AutoAcceptBehavior = 'always' | 'never' | 'onlyRead'
export type ReviewChangesExtension = 'aiSuggestion' | 'aiChanges' | null

export interface AiAgentReviewOptions {
  /**
   * What Tiptap AI extension to use for reviewing changes.
   *
   * - `"aiSuggestion"`: Uses the AI Suggestion extension to preview changes before they are inserted
   * - `"aiChanges"` Uses the AI Changes extension to review changes before they are inserted
   * - `null`: No extension is used. Changes are inserted directly into the document.
   *
   * @default null (no extension is used)
   */
  extension: ReviewChangesExtension
  /**
   * Controls whether the AI agent should automatically accept tool calls that modify the editor content.
   * - `"always"`: Automatically accepts all tool calls.
   * - `"never"`: Never automatically accepts tool calls, requiring manual review.
   * - `"onlyRead"`: Automatically accepts tool calls that do not modify the editor content.
   *
   * @default "onlyRead"
   */
  autoAccept: AutoAcceptBehavior
}

/**
 * Internal state of the AI Agent provider.
 */
export interface AiAgentProviderState {
  /**
   * The current status of the AI agent. It determines what action to take next.
   *
   * The AI Agent works like a finite state machine that can transition from one
   * state to another.
   *
   * @see AiAgentStatus
   */
  status: AiAgentStatus
  loadingError: unknown
  /**
   * The chat messages in the conversation.
   */
  chatMessages: ChatMessage[]
  chatMessagesPendingReview: {
    accept: ChatMessage[]
    reject: ChatMessage[]
  }
  /**
   * Controls the automatic acceptance behavior of the AI agent.
   * - "always": Automatically accepts all tool calls.
   * - "never": Never automatically accepts tool calls, requiring manual review.
   * - "onlyRead": Automatically accepts tool calls that do not modify the editor content.
   */
  autoAccept: 'always' | 'never' | 'onlyRead'

  /**
   * System prompt to use with the AI Agent. Overrides the default system prompt
   * when using the AI Agent with Tiptap Cloud.
   */
  systemPrompt: string | null
}