入门 OpenAI 聊天补全 API

OpenAI 聊天补全 API 允许你使用 OpenAI 的模型构建 AI Agent。

有代码演示

本指南包含代码演示，帮助你快速入门。查看 GitHub 仓库。

Client Setup

First, install the AI Agent extension.

npm install @tiptap-pro/extension-ai-agent

Then, import the extension and configure it using the AiAgentProvider class.

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import AiAgent, { AiAgentProvider } from '@tiptap-pro/extension-ai-agent'

const provider = new AiAgentProvider()

const editor = new Editor({
  extensions: [
    StarterKit,
    AiAgent.configure({
      provider,
    }),
  ],
})

Within the AI Agent provider, define a resolver function that calls the backend.

import AiAgent, { AiAgentProvider } from '@tiptap-pro/extension-ai-agent'

const provider = new AiAgentProvider({
  // The `chatMessages` property contains the conversation chat messages
  resolver: async ({ chatMessages, schemaAwarenessData }) => {
    // Call your backend API endpoint
    const response = await fetch('/api-endpoint', {
      method: 'POST',
      body: JSON.stringify({ chatMessages, schemaAwarenessData }),
    })
    return await response.json()
  },
})

In the next section, we'll see how to implement an API endpoint that returns replies in the correct format.

服务器端设置

首先，安装 AI Agent 和 OpenAI 服务器端库。

npm install @tiptap-pro/extension-ai-agent-server openai

从请求参数中获取聊天消息和模式感知数据。

// 你的 API 端点中的代码，依赖于你的后端框架
const { chatMessages, schemaAwarenessData } = request

然后，在你的 API 端点中，创建一个 AiAgentToolkit 实例。它允许你配置 AI 模型可使用的工具。

import { AiAgentToolkit, openaiChatCompletionsAdapter } from '@tiptap-pro/extension-ai-agent-server'

const toolkit = new AiAgentToolkit({
  adapter: openaiChatCompletionsAdapter,
  schemaAwarenessData,
})

同时定义一个 ChatMessagesFormatter 实例。它让你将聊天消息转换成 OpenAI 聊天补全 API 期望的格式。

import {
  AiAgentToolkit,
  openaiChatCompletionsAdapter,
  ChatMessagesFormatter,
} from '@tiptap-pro/extension-ai-agent-server'

const formatter = new ChatMessagesFormatter({
  initialMessages: chatMessages,
  adapter: openaiChatCompletionsAdapter,
})

创建工具包和格式化器后，向 OpenAI 聊天补全 API 发送请求。

import {
  AiAgentToolkit,
  openaiChatCompletionsAdapter,
  ChatMessagesFormatter,
} from '@tiptap-pro/extension-ai-agent-server'
import OpenAI from 'openai'

const { chatMessages, schemaAwarenessData } = request

const toolkit = new AiAgentToolkit({
  adapter: openaiChatCompletionsAdapter,
  schemaAwarenessData,
})

const formatter = new ChatMessagesFormatter({
  // 从请求体获取聊天消息
  initialMessages: chatMessages,
  adapter: openaiChatCompletionsAdapter,
})

// 初始化 OpenAI 客户端
const openai = new OpenAI()

// 调用 OpenAI 聊天补全 API
const response = await openai.chat.completions.create({
  model: 'gpt-4.1',
  messages: [
    {
      role: 'system',
      content: `
<你的系统提示>
${toolkit.getSystemPrompt()}
`,
    },
    ...formatter.format(),
  ],
  // 提供 AI 模型可调用的工具
  tools: toolkit.format(),
})

在系统提示的末尾，包含 AiAgentToolkit 实例生成的系统提示，如：toolkit.getSystemPrompt()。其中包含了有关如何使用工具的指令。

要编写系统提示，请参阅 system prompt guide。其中包含一个可作为起点使用的系统提示示例。

最后，使用 formatter 将回复转换为 AI Agent 扩展期望的格式。

formatter.addAiResponse(response)

const response = formatter.getResolverResponse()

formatter.getResolverResponse() 返回的值应作为你的 API 端点响应以及 resolver 函数的返回值。

PreviouslyVercel AI SDK

Next upOpenAI Responses