AI Agent State Management

The AI Agent provider maintains an internal state that tracks the conversation, status, 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 you can subscribe to changes in the state:

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

State properties

The provider state includes these key properties:

interface AiAgentProviderState {
  // Current status: "idle", "loading", "loadingError", or "reviewingToolCall"
  status: AiAgentStatus

  // Error that occurred during loading, if any
  loadingError: unknown

  // Array of all chat messages in the conversation
  chatMessages: ChatMessage[]

  // Messages waiting for user review
  chatMessagesPendingReview: {
    accept: ChatMessage[]
    reject: ChatMessage[]
  }

  // Current auto-accept setting
  autoAccept: 'always' | 'never' | 'onlyRead'
}

Status transitions

The AI Agent works as a state machine with these possible 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

The chat messages in the AI Agent conversation are stored in the provider.state.chatMessages property. It can contain different types of messages:

// User message
{ type: "user", text: "Summarize this document" }

// AI response message
{ type: "ai", text: "Here's a summary of the document..." }

// Tool call message (when AI calls a tool)
{
  type: "toolCall",
  name: "read_first_chunk",
  arguments: {},
  llmMessage: {...}
}

// Tool call result message
{
  type: "toolCallResult",
  name: "read_first_chunk",
  llmMessage: {...}
}

// Checkpoint message (saves editor state)
{
  type: "checkpoint",
  checkpoint: {
    chatMessages: [...],
    editorContent: "<p>Document content...</p>"
  }
}

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.addMessages([
  {
    type: 'ai',
    text: 'How can I help you?',
  },
])

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

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 internal state to its initial values.

provider.reset()