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:

Status

The AI Agent can be in one of these statuses:

1. idle: The agent is not currently processing anything
2. loading: The agent is processing a request to the server
3. loadingError: An error occurred during processing
4. 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:

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

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

// Tool call message (the AI decides to call 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.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()