AI 代理状态

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

访问状态

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

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

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

或者订阅状态的变化：

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

状态属性

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

属性	类型	描述
`status`	`AiAgentStatus`	当前状态（加载中、错误等）
`loadingError`	`unknown`	加载过程中发生的错误（如果有）
`chatMessages`	`ChatMessage[]`	对话中的所有消息列表
`autoAccept`	`'always' \| 'never' \| 'onlyRead'`	当前的自动接受配置
`systemPrompt`	`string \| null`	自定义的系统提示

状态说明

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

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

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

聊天消息类型

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

/**
 * 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 选项中。要修改消息列表，提供者包含以下方法：

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

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

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

重置 AI 代理状态

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

provider.reset()