---
title: "AI agent lifecycle"
description: "Learn about the lifecycle of an AI agent run in Tiptap."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/agent/features/lifecycle"
---

# AI agent lifecycle

Learn about the lifecycle of an AI agent run in Tiptap.

The AI agent lifecycle starts when `provider.run()` is called, and ends when the AI agent has completed the task, needs user review, or encounters an error.

## Lifecycle steps

1. **Initialization**: The lifecycle begins when you call `provider.run()` after adding a user message.
2. **Processing**: The AI agent calls the AI model. The AI responds with a message and a tool call.
3. **Tool execution**: The AI agent calls the tool to read or modify the document.
4. **Loop**: The AI agent calls the AI again and executes the next tool, until a termination condition is met.
5. **Completion**: The lifecycle ends when the AI agent has completed the task, needs user review, or encounters an error.

## Controlling the lifecycle

You can control the AI agent lifecycle using these methods:

```tsx
// Start the lifecycle
provider.run()

// Stop the current lifecycle
provider.stop()
```

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

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

## Handling completion

Listen to the `stopRunning` event to be notified when the lifecycle is completed and the AI agent stops running.

```tsx
// Subscribe to the stopRunning event
provider.on('stopRunning', (context) => {
  console.log('AI agent lifecycle completed')
  showCompletionNotification('The AI agent has completed the task')
})
```

## Statuses

During its lifecycle, the AI agent transitions through different [statuses](https://tiptap.dev/docs/content-ai/capabilities/agent/features/state.md#status):

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 is one that has the `isFinal` property set to `true` in the tool call handler object.
   - The LLM does not respond with a tool call.
   - `provider.stop()` is called
   - Another lifecycle is started with `provider.run()`, before the current lifecycle has finished.

## Running AI Agents concurrently

In its current version, the AI Agent extension does not support running multiple AI Agents within the same editor. If a lifecycle is already in progress when `provider.run()` is called, the current lifecycle is interrupted before the new lifecycle starts.

To run multiple AI Agents at the same time, instantiate multiple editors and AI agent providers.