---
title: "AI 代理状态"
description: "了解如何管理 Tiptap 中 AI 代理的状态。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/agent/features/state"
---

# AI 代理状态

了解如何管理 Tiptap 中 AI 代理的状态。

AI 代理提供者维护一个内部状态，用于跟踪对话和其他重要信息。您可以访问此状态以更新应用程序的 UI。

## 访问状态

您可以直接访问状态及其属性：

```tsx
// 访问当前状态
const currentState = provider.state

// 访问状态的某个属性
currentState.status
```

或者订阅状态的变化：

```tsx
provider.on('stateChange', (newState) => setState(newState))
```

## 状态属性

提供者状态包含以下属性：

| 属性             | 类型                                  | 描述                                                                                                                  |
| -------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `status`       | `AiAgentStatus`                     | 当前状态（加载中、错误等）                                                                                                       |
| `loadingError` | `unknown`                           | 加载过程中发生的错误（如果有）                                                                                                     |
| `chatMessages` | `ChatMessage[]`                     | 对话中的所有消息列表                                                                                                          |
| `autoAccept`   | `'always' \| 'never' \| 'onlyRead'` | 当前的[自动接受](https://tiptap.zhcndoc.com/content-ai/capabilities/agent/features/review.md#auto-accept-configuration) 配置 |
| `systemPrompt` | `string \| null`                    | 自定义的[系统提示](https://tiptap.zhcndoc.com/content-ai/capabilities/agent/configure/system-prompt.md)                     |

## 状态说明

AI 代理可能处于以下状态之一：

1. `idle`：代理当前没有处理任何内容
2. `loading`：代理正在处理发送到服务器的请求
3. `loadingError`：处理过程中发生错误
4. `reviewingToolCall`：代理正在等待用户接受或拒绝工具调用

您可以根据这些状态值更新 UI，例如显示加载指示器或错误消息。

## 聊天消息类型

聊天消息存储在 `provider.state.chatMessages` 属性中，包含不同类型的消息：

```ts
/**
 * AI 助手生成的消息
 */
export type AiChatMessage = {
  type: 'ai'

  /**
   * 消息的文本内容
   */
  text: string
}

/**
 * 用户发送的消息
 */
export type UserChatMessage = {
  type: 'user'

  /**
   * 消息的文本内容
   */
  text: string

  /**
   * 可选上下文，用于向 AI 模型提供补充用户消息的额外信息。
   * 例如，如果用户消息提到了文档，上下文可以包含该文档的 ID。
   */
  context?: string | null

  /**
   * 发送消息时选中的编辑器内容
   */
  selection?: string | null
}

/**
 * 表示对话中的检查点消息
 * 用于保存编辑器在特定时刻的状态
 */
export type CheckpointChatMessage = {
  type: 'checkpoint'

  /**
   * 包含编辑器状态的检查点数据
   */
  checkpoint: Checkpoint
}

/**
 * 表示 AI 发起的工具调用请求消息
 */
export type ToolCallChatMessage = {
  type: 'toolCall'

  /**
   * 被调用工具的唯一标识符
   */
  toolName: string

  /**
   * 工具调用的唯一标识符。一些 AI 提供者要求此 ID 与 `ToolCallResultChatMessage` 中的值匹配。
   */
  toolCallId: string

  /**
   * 工具调用的参数。该对象可序列化为 JSON，且符合工具的输入 schema。
   */
  arguments: any
}

/**
 * 表示工具调用成功结果的消息
 */
export type ToolCallResultChatMessage = {
  type: 'toolCallResult'

  /**
   * 标识这是否为错误消息
   */
  isError: boolean

  /**
   * 被调用工具的唯一标识符
   */
  toolName: string

  /**
   * 工具调用的唯一标识符。一些 AI 提供者要求此 ID 与 `ToolCallChatMessage` 中的值匹配。
   */
  toolCallId: string

  /**
   * 工具调用的结果
   */
  result: string
}
```

所有消息都拥有一个 `metadata` 属性，用于存储附加信息。

## 管理消息

对话的初始消息定义在 `initialMessages` 选项中。要修改消息列表，提供者包含以下方法：

```tsx
// 插入用户消息
provider.addUserMessage('写一个短篇故事')

// 在对话中插入不同类型的消息
provider.addChatMessages([
  {
    type: 'ai',
    text: '我能帮您什么？',
  },
])

// 完全替换对话
provider.setChatMessages([])
```

## 重置 AI 代理状态

您可以通过调用 `reset` 方法重置 AI 代理的状态。这将清除对话并将状态重置为初始值。

```tsx
provider.reset()
```