AI Agent Lifecycle

An AI Agent run is a complete cycle of interaction between the user, the AI Agent, and the document. Understanding the run lifecycle helps you build better integrations and user experiences.

Run lifecycle

1. Initialization: The run begins when you call provider.run() after adding a user message
2. Processing: The AI Agent processes the request, calling the LLM. The LLM model responds with a message and/or a tool call.
3. Tool execution: The AI Agent executes the tool to read or modify the document
4. Loop: The AI Agent continues calling the LLM and executing tools, until a termination condition is met.
5. Completion: The run ends when the AI Agent has completed the task, needs user review, or encounters an error

Run states

During a run, the AI Agent transitions through different states:

1. idle → loading: When run() is called
2. loading → reviewingToolCall: When a tool call requires user review
3. loading → loadingError: When an error occurs
4. loading → idle: When one of these conditions is met:
   • A final tool call is executed. A final tool call stops the automatic loop of running a tool call after the other. A final tool call is one that has the isFinal property set to true in the tool call handler object.
   • The LLM responds with a message and no tool is called.
   • The AI agent stops with provider.stop()
   • Another run is started with provider.run(), before the current run has finished.

Running AI Agents concurrently

To run multiple AI Agents at the same time, instantiate multiple editors and AI Agent providers. In its current version, the AI Agent extension does not support running multiple AI Agents within the same editor. If a run is already in progress when provider.run() is called, the current run is interrupted before the new run starts.

Controlling runs

You can control the AI Agent run using these methods:

// Start a run
provider.run()

// Stop a run in progress
provider.stop()

Auto-running vs. manual control

By default, the AI Agent doesn't automatically run after adding a user message. You need to explicitly call run():

// Add a message and run the AI Agent
provider.addUserMessage('Format this document with proper headings')
provider.run()

Handling run completion

// Subscribe to the runFinished event
provider.on('runFinished', (context) => {
  console.log('AI Agent run completed')
  showCompletionNotification('The AI Agent has completed the task')
})