> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt/chat/conversation-handoff.md).

# Conversation Handoff

When a conversation gets too long, ask the assistant to prepare a handoff summary, then continue in a new conversation without explaining the background again

The longer you chat in the same conversation, the more the assistant needs to remember. When the content approaches its limit, the assistant starts to lose track of what you discussed at the beginning.

With “Conversation Handoff,” you can ask the assistant to organize your current progress into a **handoff summary**, then start a new conversation with one click to continue your work. The assistant in the new conversation reads this summary first, so you do not need to explain the background again. The original conversation is also preserved for you to revisit at any time.

{% hint style="info" %}
Conversation handoff is available only after MaiAgent enables the system's global conversation handoff feature. This global switch is not available in the admin console, and customer administrators cannot configure it themselves. Contact MaiAgent to enable it. Once enabled globally, conversation handoff is available in **MaiGPT** and **Web Chat**. For Web Chat, an administrator must also turn on “Enable Conversation Handoff” for the conversation platform (see [Enable in Web Chat](#enable-on-web-chat)). Other conversation platforms, such as LINE, Facebook Messenger, and Microsoft Teams, are not supported.
{% endhint %}

***

## Use Case <a href="#use-case" id="use-case"></a>

A marketing specialist is planning an autumn product launch in MaiGPT. She has spent the afternoon discussing the venue, guest count, budget allocation, and introduction scripts for two featured products with the assistant. She notices that “Context Usage” below the input box has reached 82%, and a prompt bar above the input box suggests preparing a handoff.

She clicks “Prepare Handoff.” The assistant creates a handoff summary listing the event goals, the confirmed venue and budget, the introduction scripts in progress, and the remaining tasks. After reviewing the summary, she clicks “Continue in New Conversation.” The screen switches to a new conversation, and the assistant first says, “We've picked up where you left off. The current tasks are…” She then asks the assistant to write the invitation without pasting the earlier discussion again.

***

## Where You Can Use It <a href="#where-available" id="where-available"></a>

| Entry Point  | Users                                  | Description                                                                                                                                                                                                                                                                            |
| ------------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MaiGPT**   | Organization members                   | The MaiGPT conversation page works the same way in every layout. Once the global conversation handoff feature is enabled, you can use it without configuring a separate platform switch                                                                                                |
| **Web Chat** | Website visitors, organization members | The Web Chat conversation window embedded on a website is also available to visitors who are not logged in. After the global conversation handoff feature is enabled, an administrator must also turn on “Enable Conversation Handoff” for that conversation platform (off by default) |

{% hint style="warning" %}
**The Web Chat assistant must use Agent mode**

The assistant prepares the handoff summary. If the assistant connected to Web Chat does not use “Agent mode” (or Agent Teams), it cannot generate a handoff summary. MaiGPT is not affected.
{% endhint %}

### Enable in Web Chat <a href="#enable-on-web-chat" id="enable-on-web-chat"></a>

Conversation handoff and context usage in Web Chat have **two independent switches**, configured separately for each conversation platform and off by default. Visitors to a customer's embedded Web Chat see neither handoff prompts nor context usage until an administrator enables them. “Show Context Usage” takes effect as soon as it is enabled. “Enable Conversation Handoff” takes effect only after MaiAgent enables the global conversation handoff feature.

The customer service manager at an online retailer notices that website visitors often ask about several orders in a single conversation. As the conversation gets longer, the assistant loses track of order numbers mentioned at the start. She wants visitors to first see how much conversation space they have used, so she opens <mark style="color:blue;">Feature Settings</mark> for the official website's Web Chat conversation platform, enables only <mark style="color:blue;">Show Context Usage</mark>, and saves. When visitors reopen the conversation window and receive the assistant's first reply, “Context Usage” and a percentage appear below the input box.

#### 1. Open the Conversation Platform's Feature Settings <a href="#open-function-settings" id="open-function-settings"></a>

In the admin console, go to <mark style="color:blue;">Customer Service Conversations</mark> → <mark style="color:blue;">Conversation Platforms</mark>. Edit the Web Chat platform you want to enable, then click <mark style="color:blue;">Feature Settings</mark> in the left menu.

#### 2. Enable the Switches You Need and Save <a href="#turn-on-switches" id="turn-on-switches"></a>

The “Basic Features” section has two switches. You can enable either one or both:

| Switch                                                       | Effect in Web Chat When Enabled                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Enable Conversation Handoff</mark> | When the global conversation handoff feature is enabled, a handoff prompt bar appears starting at 80% context usage, the assistant can generate a handoff summary card, and visitors can continue in a new conversation. If the global feature is disabled, turning on this switch produces no visible change |
| <mark style="color:blue;">Show Context Usage</mark>          | Displays the context usage percentage below the input box                                                                                                                                                                                                                                                     |

After configuring the switches, click <mark style="color:blue;">Save</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0c70e66268aa842a00483f1b0317c79433f6d409%2Fplatform-function-settings-handoff-context-usage.png?alt=media" alt="The Basic Features section of the conversation platform&#x27;s Feature Settings, with Enable Conversation Handoff and Show Context Usage switches in the last row"><figcaption><p>“Enable Conversation Handoff” and “Show Context Usage” under “Feature Settings” → “Basic Features”</p></figcaption></figure>

{% hint style="info" %}

* **The two switches are independent**: If you enable only “Show Context Usage,” only the percentage appears, without a handoff prompt bar. If you enable only “Enable Conversation Handoff,” usage is not displayed below the input box, but the handoff prompt bar still appears at the 80%, 90%, and 100% usage thresholds (the global conversation handoff feature must be enabled).
* **Conversation handoff also requires the global switch**: MaiAgent controls the global conversation handoff switch. It is not available in the admin console, so customer administrators must contact MaiAgent to enable it. When the global switch is off, handoff is unavailable on all platforms, including MaiGPT, and enabling “Enable Conversation Handoff” produces no visible change. “Show Context Usage” is unaffected by the global switch.
* The settings page for internal platforms does not display these two switches. For their locations on the settings page, see [Feature Settings](/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md).
  {% endhint %}

***

## View Context Usage <a href="#context-usage" id="context-usage"></a>

A “<mark style="color:blue;">Context Usage</mark>” row below the conversation input box contains a short progress bar and a percentage. It shows how much of the assistant's available memory space this conversation has used.

* **MaiGPT**: Always displayed; no configuration is needed.
* **Web Chat**: Displayed only after an administrator enables <mark style="color:blue;">Show Context Usage</mark> for that conversation platform (see [Enable in Web Chat](#enable-on-web-chat)). This switch is independent of “Enable Conversation Handoff.”

Display rules:

* In a new conversation, the row appears only after the assistant's first reply.
* It updates after each completed assistant reply.
* The maximum displayed value is 100%.

The closer usage gets to 100%, the more advisable it is to continue in a new conversation. Once it reaches 100%, the assistant starts losing access to the earliest conversation content.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a28fe8dd2dc5291b307b4665268f15f1df1d879f%2Fconversation-handoff-context-usage.png?alt=media" alt="Context usage progress bar and percentage below the MaiGPT input box"><figcaption><p>“Context Usage” below the input box updates after each assistant reply</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-62279bf41255a0b107f261a899541c9fc38d8e2b%2Fplatform-webchat-context-usage-bar.png?alt=media" alt="Context usage progress bar and 0% below the Web Chat input box"><figcaption><p>After “Show Context Usage” is enabled in Web Chat, “Context Usage” and a percentage appear below the input box</p></figcaption></figure>

***

## Three Ways to Start a Handoff <a href="#how-to-start" id="how-to-start"></a>

### 1. Ask the Assistant Directly <a href="#ask-directly" id="ask-directly"></a>

At any time, you can enter and send a message like this:

> Hand off this conversation to a new conversation

The assistant prepares a handoff summary (see “[Handoff Summary](#handoff-summary)” below). You do not need to wait for usage to increase before handing off.

### 2. Use the Prompt Bar <a href="#prompt-bar" id="prompt-bar"></a>

When context usage reaches **80%**, a prompt appears above the input box:

> This conversation is approaching its context limit. We recommend preparing a summary and handing off to a new conversation to continue

The prompt bar has two buttons on the right:

* <mark style="color:blue;">Prepare Handoff</mark>: Automatically sends “Hand off this conversation to a new conversation” for you, and the assistant prepares the handoff summary.
* <mark style="color:blue;">Close</mark>: Hides the prompt bar so you can continue in the original conversation.

After you close it, the prompt bar appears again when usage crosses the next threshold (**90%**, **100%**). At 100%, the prompt changes to:

> This conversation has reached its context limit. To preserve the completeness of the conversation content, we recommend preparing a summary and handing off to a new conversation to continue

{% hint style="info" %}
Closing the prompt bar applies only to the currently open page. After refreshing the page, the prompt bar appears again if usage is still above the threshold.
{% endhint %}

### 3. Respond to the Assistant's Proactive Question <a href="#assistant-asks" id="assistant-asks"></a>

When context usage reaches 80%, the assistant adds a question at the end of that reply, such as:

> This conversation is getting quite long. Would you like me to summarize the key points and hand off to a new conversation to continue?

* If you agree with a response such as “Yes” or “Sure,” the assistant prepares a handoff summary.
* If you say “No” or ignore the question, the assistant continues as usual without repeating the question every time.
* The assistant reminds you once more at each of the 90% and 100% thresholds.

The assistant's question and the prompt bar appear at the same time. You can use either method to start the handoff.

***

## Handoff Summary <a href="#handoff-summary" id="handoff-summary"></a>

The assistant's summary remains in the original conversation as a “<mark style="color:blue;">Handoff Summary</mark>” card with five sections:

| Section            | Content                                                          |
| ------------------ | ---------------------------------------------------------------- |
| **Goals**          | What this conversation aims to accomplish                        |
| **Decided**        | Confirmed decisions and conclusions                              |
| **In Progress**    | Items still being worked on and their current status             |
| **To Do**          | What needs to be done next                                       |
| **Key References** | Important numbers, names, and names of previously uploaded files |

The summary uses the language of your conversation. Sections with no content are hidden.

At the bottom of the card is a “<mark style="color:blue;">Continue in New Conversation</mark>” button, with a note beside it indicating which new conversation will be created.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e2cd9c3c00f4894f679b9fdeddab12d32735c0c8%2Fconversation-handoff-summary-card.png?alt=media" alt="Handoff summary card in a MaiGPT conversation, with Goals, Decided, In Progress, To Do, and Key References sections and a Continue in New Conversation button"><figcaption><p>After you enter a handoff request, the assistant leaves a handoff summary card in the original conversation</p></figcaption></figure>

{% hint style="warning" %}
**The system does not switch conversations automatically**

After the handoff summary is generated, you remain in the original conversation. Review the summary and confirm it is correct before clicking “Continue in New Conversation.” If important information is missing, ask the assistant to add it in the original conversation, or request another handoff.
{% endhint %}

You can hand off the same conversation more than once. Each handoff creates a new summary, and only the **latest summary** displays the button.

***

## Continue in a New Conversation <a href="#continue-in-new-conversation" id="continue-in-new-conversation"></a>

{% stepper %}
{% step %}

### Click “Continue in New Conversation” <a href="#click-continue" id="click-continue"></a>

Click <mark style="color:blue;">Continue in New Conversation</mark> at the bottom of the handoff summary card. While the conversation is being created, the button displays “Creating New Conversation…”.
{% endstep %}

{% step %}

### Enter the New Conversation <a href="#enter-new-conversation" id="enter-new-conversation"></a>

The screen switches to a new conversation whose title is the original title followed by “(Continued)”. The system sends the first message on your behalf, with the text “Continuing from the handoff for 〈original conversation title〉”. The message is labeled “Sent by System”.
{% endstep %}

{% step %}

### The Assistant Confirms the Continuation Status <a href="#assistant-confirms" id="assistant-confirms"></a>

After reading the handoff summary, the assistant first confirms the continuation status in one sentence, such as “We've picked up where you left off. The current tasks are…”. You can then chat as usual.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-bd08fd6bcf6ad1364e3e57186ffb1c719b0fc762%2Fconversation-handoff-new-conversation.png?alt=media" alt="The first message in the new conversation is a continuation message labeled Sent by System, and the assistant confirms the continuation and lists tasks"><figcaption><p>The system sends a continuation message in the new conversation, and the assistant reads the summary and confirms the continuation status</p></figcaption></figure>
{% endstep %}
{% endstepper %}

After the handoff, the conversation list shows the relationship between the two conversations. The original is labeled “Handed Off To,” and the new one is labeled “Continued from Original Conversation.” The button in the original conversation changes to “<mark style="color:blue;">Go to New Conversation</mark>”. Clicking it again returns to the same new conversation without creating another one.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-066b9a3bef1bbf431932dc0edd2a7e2734fd90ff%2Fconversation-handoff-list-badges.png?alt=media" alt="The conversation list labels the new conversation as Continued from Original Conversation and the original as Handed Off To"><figcaption><p>The conversation list shows the handoff relationship between the two conversations</p></figcaption></figure>

If creating the new conversation fails, the screen displays “Failed to create a new conversation. Please try again,” and the button becomes available to click again.

***

## What You Can Do After Continuing in a New Conversation <a href="#after-handoff" id="after-handoff"></a>

* **Continue your work directly**: The assistant already knows the goals, decisions, and tasks in the handoff summary, so you can give it the next instruction immediately.
* **Use the same assistant**: The new conversation uses the same assistant as the original, with the same model, knowledge base, and tool settings.
* **Revisit the original conversation**: The complete original conversation remains in the conversation list for you to open and review whenever needed.
* **Hand off again**: When the new conversation gets long, you can hand off to another new conversation. Usage is calculated afresh in each new conversation.

The assistant in the new conversation can see only the handoff summary, not the other messages in the original conversation. The following content is not carried over:

* Files and images uploaded in the original conversation (the summary lists only their filenames)
* Files generated in the original conversation and Canvas content
* Conversation details outside the summary

If the new conversation needs this content, upload the files again or paste the relevant passages into the new conversation.

{% hint style="info" %}
If the original conversation or handoff summary was deleted before continuing, the assistant says, “I couldn't find the handoff summary from the original conversation. Please tell me directly what you'd like to continue.” Simply explain what you want to continue.
{% endhint %}

***

## Notes for Web Chat Visitors <a href="#web-chat-visitors" id="web-chat-visitors"></a>

Web Chat visitors who are not logged in can also hand off conversations using the steps above. Keep in mind:

* The new and original conversations are saved only in the visitor's current browser. They are not available in another browser or on another device.
* After the visitor's conversation history expires, the original conversation can no longer be opened, but an already created new conversation remains usable.

***

## Unsupported Scenarios <a href="#not-supported" id="not-supported"></a>

| Scenario                                                                                       | Description                                                                                       |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Other conversation platforms such as LINE, Facebook Messenger, Microsoft Teams, and Slack      | Usage and prompt bars are not displayed, and the assistant does not proactively ask about handoff |
| Automatically switching to a new conversation                                                  | Not supported. You must click “Continue in New Conversation” yourself                             |
| Handing off to a different assistant                                                           | Not supported. The new conversation always uses the original assistant                            |
| Carrying the original conversation's attachments and generated files into the new conversation | Not supported. Upload them again in the new conversation                                          |
| Compressing content and continuing within the same conversation                                | Not supported. A handoff always opens a new conversation                                          |

***

## Frequently Asked Questions <a href="#faq" id="faq"></a>

**Can I hand off while usage is still low?**

Yes. Enter “Hand off this conversation to a new conversation” directly. You do not need to wait for the prompt bar.

**Can I still hand off if I accidentally closed the prompt bar?**

Yes. Ask the assistant to hand off directly in the input box.

**How is context usage calculated?**

The percentage represents how much of the assistant's available memory space the conversation currently occupies, estimated from the conversation content and the assistant's model. Different models can remember different amounts, so conversations of the same length may have different usage percentages.

**Can I keep chatting in the original conversation after a handoff?**

Yes. The original conversation is not locked, but its usage is already high, so we recommend continuing in the new conversation.

**Related Features**

* [AI Chat](/maiagent-user-guide/en/work/maigpt/chat.md)
* [Feature Settings](/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md): The “Enable Conversation Handoff” and “Show Context Usage” switches for Web Chat
* [Conversation Handoff and Continuation API](https://docs.maiagent.ai/tech/serve/conversation-handoff-continuation) (Technical Manual): How to create a continuation conversation from a handoff summary when building your own frontend or integrating through the API


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt/chat/conversation-handoff.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.