---
title: "AI 代理聊天机器人"
description: "使用 AI 工具包和 Vercel AI SDK 构建一个可以读取和编辑 Tiptap 文档的 AI 代理。"
canonical_url: "https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/ai-agent-chatbot"
---

# AI 代理聊天机器人

使用 AI 工具包和 Vercel AI SDK 构建一个可以读取和编辑 Tiptap 文档的 AI 代理。

构建一个简单的 AI 代理聊天机器人，能读取和编辑 Tiptap 文档。

> **Interactive demo:** [ai agent chatbot](https://ai-toolkit-demos.vercel.app/ai-agent-chatbot)

查看[GitHub 上的源码](https://github.com/ueberdosis/ai-toolkit-demos)。

## 技术栈

- [React](https://react.dev/) + [Next.js](https://nextjs.org/)
- [Vercel 的 AI SDK](https://ai-sdk.dev/) + [OpenAI](https://openai.com/) 模型
- Tiptap AI 工具包

## 安装

创建一个 [Next.js](https://nextjs.org/) 项目：

```bash
npx create-next-app@latest ai-agent-chatbot
```

安装核心的 Tiptap 包以及用于 OpenAI 的 [Vercel AI SDK](https://ai-sdk.dev/)：

```bash
npm install @tiptap/react @tiptap/starter-kit ai @ai-sdk/react @ai-sdk/openai
```

安装 Tiptap AI 工具包以及 Vercel AI SDK 的工具定义。

> **专业包:**
>
> AI 工具包是一个专业版包。在安装之前，请按照[私有注册表指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md)设置对私有 NPM 注册表的访问权限。

```bash
npm install @tiptap-pro/client-ai-toolkit @tiptap-pro/ai-toolkit-ai-sdk
```

## API 端点

创建一个使用 [Vercel AI SDK](https://ai-sdk.dev/) 调用 OpenAI 模型的 API 端点。包含 Tiptap AI Toolkit 的 [工具定义](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/tools/ai-sdk.md)。

如果你的后端使用的不是 TypeScript，而是其他编程语言，请参阅[本指南](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/advanced-guides/non-typescript-backends.md)。

```ts
// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai'
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'
import { createAgentUIStreamResponse, ToolLoopAgent, UIMessage } from 'ai'

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json()

  const agent = new ToolLoopAgent({
    model: openai('gpt-5.4-mini'),
    instructions: '你是一个可以编辑富文本文档的助手。',
    tools: toolDefinitions(),
  })

  return createAgentUIStreamResponse({
    agent,
    uiMessages: messages,
  })
}
```

要访问 OpenAI API，请在 [OpenAI 控制台](https://platform.openai.com/account/api-keys) 创建一个 API 密钥，并将其作为[环境变量](https://nextjs.org/docs/app/guides/environment-variables)添加。Vercel AI SDK 会自动检测该环境变量。

```sh
# .env
OPENAI_API_KEY=your-api-key
```

当 AI 模型接收到请求时，它会决定调用可用工具来读取文档并对其进行编辑。有关更多详细信息，请参阅[可用工具列表](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/tools.md)。

## 客户端设置

当 AI 模型决定调用某个工具时，需要在客户端执行它。这可以通过 [`executeTool 方法`](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/api-reference/execute-tool.md) 实现：

```ts
import { Editor } from '@tiptap/react'
import { getAiToolkit } from '@tiptap-pro/client-ai-toolkit'

// 创建一个 Tiptap Editor 实例
const editor = new Editor()

// 获取 Tiptap AI Toolkit 实例
const toolkit = getAiToolkit(editor)

// AI 决定调用 `tiptapRead` 工具来读取文档
// 使用 `executeTool` 方法执行该工具并获取结果
const result = toolkit.executeTool({
  // 要执行的工具名称
  toolName: 'tiptapRead',
  // AI 生成的输入
  input: {},
})
// 将结果返回给 AI 模型
```

要在你的应用中实现这一点，请创建一个客户端 React 组件，用于渲染 Tiptap 编辑器和一个简单的聊天 UI。该组件利用 Vercel AI SDK 中的 [useChat hook](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) 来调用 API 端点并管理聊天对话。

```tsx
// app/page.tsx
'use client'

import { DefaultChatTransport, lastAssistantMessageIsCompleteWithToolCalls } from 'ai'
import { useChat } from '@ai-sdk/react'
import { EditorContent, useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { useState } from 'react'
import { AiToolkit, getAiToolkit } from '@tiptap-pro/client-ai-toolkit'

export default function Page() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [StarterKit, AiToolkit],
    content: `<h1>AI 代理演示</h1><p>请让 AI 改进这段内容。</p>`,
  })

  // 解决问题：https://github.com/vercel/ai/issues/8148
  const editorRef = useRef(editor)
  editorRef.current = editor

  const { messages, sendMessage, addToolOutput } = useChat({
    transport: new DefaultChatTransport({ api: '/api/chat' }),
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
    async onToolCall({ toolCall }) {
      if (!editor) return

      const { toolName, input, toolCallId } = toolCall

      // 使用 AI 工具包执行工具
      const toolkit = getAiToolkit(editor)
      const result = toolkit.executeTool({
        toolName,
        input,
      })

      addToolOutput({ tool: toolName, toolCallId, output: result.output })
    },
  })

  const [input, setInput] = useState('用一个关于 Tiptap 的短篇故事替换最后一段')

  if (!editor) return null

  return (
    <div>
      <EditorContent editor={editor} />
      {messages?.map((message) => (
        <div key={message.id} style={{ whiteSpace: 'pre-wrap' }}>
          <strong>{message.role}</strong>
          <br />
          {message.parts
            .filter((p) => p.type === 'text')
            .map((p) => p.text)
            .join('\n')}
        </div>
      ))}
      <form
        onSubmit={(e) => {
          e.preventDefault()
          sendMessage({ text: input })
          setInput('')
        }}
      >
        <input value={input} onChange={(e) => setInput(e.target.value)} />
      </form>
    </div>
  )
}
```

## 最终效果

配合额外的 CSS 样式，效果是一个简单但精致的 AI 聊天机器人应用：

> **Interactive demo:** [ai agent chatbot](https://ai-toolkit-demos.vercel.app/ai-agent-chatbot)

查看[GitHub 上的源码](https://github.com/ueberdosis/ai-toolkit-demos)。

## 下一步

- 让你的用户通过 [审查更改指南](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/review-changes.md) 审查 AI 生成的更改
- 使用 [流式传输指南](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/streaming.md) 添加实时工具流式传输，以查看更改如何实时发生
- 你的文档是否包含自定义节点和标记？通过 [模式感知指南](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/api-reference/schema-awareness.md) 了解如何让你的 AI 代理理解它们。