AI Agent state

The AI Agent provider maintains an internal state that tracks the conversation and other important information. You can access this state to update the UI of your application.

Accessing the state

You can access the state and its properties directly:

// Access the current state
const currentState = provider.state

// Access a property of the state
currentState.status

Or subscribe to changes in the state:

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

State properties

The provider state includes these properties:

Property	Type	Description
`status`	`AiAgentStatus`	Current status (loading, error, etc.)
`loadingError`	`unknown`	Error that occurred during loading, if any
`chatMessages`	`ChatMessage[]`	List of all messages in the conversation
`autoAccept`	`'always' \| 'never' \| 'onlyRead'`	Current auto-accept setting
`systemPrompt`	`string \| null`	Custom system prompt

Status

The AI Agent can be in one of these statuses:

idle: The agent is not currently processing anything
loading: The agent is processing a request to the server
loadingError: An error occurred during processing
reviewingToolCall: The agent is waiting for the user to accept/reject a tool call

You can use these status values to update your UI accordingly, such as showing loading indicators or error messages.

Chat message types

Chat messages are stored in the provider.state.chatMessages property. It contains different types of messages:

/**
 * Message generated by the AI assistant
 */
export type AiChatMessage = {
  type: 'ai'

  /**
   * The text content of the message
   */
  text: string
}

/**
 * Message sent by the user
 */
export type UserChatMessage = {
  type: 'user'

  /**
   * The text content of the message
   */
  text: string

  /**
   * Optional context to provide additional information to the AI model that
   * complements the user's message. For example, if the user message mentions a
   * document, the context could include the document's ID.
   */
  context?: string | null

  /**
   * Selected editor content at the time of sending the message
   */
  selection?: string | null
}

/**
 * Message representing a checkpoint in the conversation
 * Used to save the state of the editor at a specific point
 */
export type CheckpointChatMessage = {
  type: 'checkpoint'

  /**
   * The checkpoint data containing editor state
   */
  checkpoint: Checkpoint
}

/**
 * Message representing a tool call request from the AI
 */
export type ToolCallChatMessage = {
  type: 'toolCall'

  /**
   * The unique identifier of the tool that was called
   */
  toolName: string

  /**
   * The unique identifier of the tool call. Some AI providers
   * require this to match the value in `ToolCallResultChatMessage`.
   */
  toolCallId: string

  /**
   * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
   */
  arguments: any
}

/**
 * Message representing a successful tool call result
 */
export type ToolCallResultChatMessage = {
  type: 'toolCallResult'

  /**
   * Identifies this as a tool call result message
   */
  isError: boolean

  /**
   * The unique identifier of the tool that was called
   */
  toolName: string

  /**
   * The unique identifier of the tool call. Some AI providers
   * require this to match the value in the `ToolCallChatMessage`.
   */
  toolCallId: string

  /**
   * Result of the tool call
   */
  result: string
}

All the messages have a metadata property where you can store additional information.

Managing messages

The initial messages in the conversation are defined in the initialMessages option. To modify the list of messages, the provider contains these methods:

// Inserts a user message
provider.addUserMessage('Write a short story')

// Inserts different types of messages in the conversation
provider.addChatMessages([
  {
    type: 'ai',
    text: 'How can I help you?',
  },
])

// Replaces the conversation entirely
provider.setChatMessages([])

Resetting the AI Agent's state

You can reset the AI Agent's state by calling the reset method. This will clear the conversation and reset the state to its initial values.

provider.reset()