> 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/tech/ja/serve/conversation-handoff-continuation.md).

# 対話の引き継ぎと継続 API

引き継ぎサマリーから継続会話を作成し、元の会話と継続会話の関連を確認します。

Agent が元の会話で引き継ぎサマリーを生成すると、連携側はサマリーメッセージを使って継続会話を作成できます。新しい会話は元の会話の Agent と会話設定を引き継ぎ、以降のメッセージは新しい会話に送信します。API Key で連携するメンバーが通常の会話を作成してメッセージを送信する方法は、[会話とメッセージの作成](/tech/ja/api-integration/conversations-and-messages.md)を参照してください。Web Chat の匿名訪問者は、[匿名 Web Chat での後続メッセージの送信](#anonymous-web-chat-messaging)を使用してください。

API レスポンスのフィールド名は camelCase です。

画面上で引き継ぎ内容をまとめて新しい会話に移る操作、および Web Chat で事前に必要な設定（会話プラットフォームの「会話の引き継ぎを有効にする」をオンにし、Agent の応答モードを Agent に設定する）については、ユーザーマニュアルの[会話の引き継ぎ](https://docs.maiagent.ai/work/maigpt/chat/conversation-handoff#enable-on-web-chat)を参照してください。

## 継続会話の作成 <a href="#create-continuation" id="create-continuation"></a>

引き継ぎは Web Chat の会話でのみ利用できます。Web Chat の匿名訪問者の元の会話は、`POST /api/conversations/` に `{"webChat": "<webChatId>"}` を送信して作成します。認証ヘッダーは不要です。`webChatId` は管理画面の Web Chat 設定ページで取得できます（[クイックスタート](/tech/ja/serve/web-chat-sdk.md#quickstart)を参照）。レスポンスの `id` が元の会話の UUID です。

まず `GET /api/conversations/{conversation_id}/` で元の会話を取得します。匿名訪問者には認証ヘッダーが不要です。API Key で連携するメンバーの場合、この取得リクエストと、以下の継続会話を作成する `POST` の両方に `Authorization: Api-Key <API Key>` を付けてください。レスポンスの `handoff.enabled` が `false` の場合、プラットフォームで会話の引き継ぎが有効になっていないため、引き継ぎサマリーは生成されません。`true` の場合、Agent が引き継ぎサマリーを生成すると、`handoff.latestSummaryMessageId` にそのサマリーメッセージの UUID が返されます。フィールドが空の場合、元の会話にはまだ引き継ぎサマリーがありません。サマリーが生成されるのは、ユーザーが元の会話で引き継ぎを依頼した場合（例えば「引き継ぎ」「新しい会話で続ける」「handoff」と送信するか、案内バーの「引き継ぎ内容をまとめる」をクリックした場合）、またはコンテキスト使用量が高くなって Agent が引き継ぎを提案し、ユーザーが同意した場合のみです。また、サマリーを生成するのは Agent または Team モードの Agent のみです。生成後に元の会話を再取得すると、サマリーの ID を取得できます。続いて `POST /api/conversations/{conversation_id}/handoff-continuations/` に以下を送信します。

```json
{"summaryMessageId": "<元の会話にある引き継ぎサマリーメッセージの UUID>"}
```

`summaryMessageId` は、この元の会話にある引き継ぎサマリーを指す必要があります。初回の作成では HTTP 201 が返されます。継続会話がまだ存在する場合、同じサマリーを再送すると既存の会話と HTTP 200 が返されます。以前の継続会話が削除されている場合は、再送によって新しい会話を作成でき、HTTP 201 が返されます。どちらのレスポンスにも以下が含まれます。

| フィールド            | 意味                                              |
| ---------------- | ----------------------------------------------- |
| `conversationId` | 継続会話の UUID です                                   |
| `title`          | 継続会話のタイトルです                                     |
| `created`        | `true` は今回新しく作成したことを、`false` は既存の会話を取得したことを示します |

メッセージが元の会話に属していない場合や、引き継ぎサマリーではない場合、リクエストは拒否されます。連携側はレスポンスの `conversationId` を保存し、以降の会話に使用してください。

## 匿名 Web Chat での後続メッセージの送信 <a href="#anonymous-web-chat-messaging" id="anonymous-web-chat-messaging"></a>

Web Chat の匿名訪問者は API Key を持たないため、`POST /api/messages/` を使用できません。継続会話の `conversationId` を取得した後は、Web Chat のメッセージエンドポイントを使用してください。認証ヘッダーは不要です。

```
POST /api/conversations/{conversationId}/web-chat-messages/
```

```json
{"content": "前の質問の続きです"}
```

URL 内の `conversationId` によって会話が決まり、その会話の連絡先としてメッセージが送信されます。成功すると HTTP 201 が返され、レスポンスには送信した訪問者のメッセージ（`type` は `incoming`）が含まれます。Agent の応答は含まれません。

Agent の応答はバックグラウンドで生成されます。訪問者は `GET /api/messages/?conversation={conversationId}` で会話のメッセージを取得できます。認証ヘッダーは不要です。レスポンスの `results` はデフォルトで最新 20 件のメッセージを返し、作成日時の古い順に並びます。Agent の応答の `type` は `outgoing` です。Agent の応答がまだ表示されない場合は、少し待ってから再取得してください。

## 引き継ぎの関連情報の取得 <a href="#read-handoff-links" id="read-handoff-links"></a>

会話データの `handoff` フィールドには関連情報が含まれます。継続会話では `sourceConversationId` と `sourceTitle` を取得できます。元の会話では、継続会話が作成されると `continuedToConversationId` と `continuedToTitle` を取得できます。連携側はこれらのフィールドを使って、「元の会話に戻る」や「継続会話に移動する」リンクを提供できます。

## 権限と再送 <a href="#access-and-retry" id="access-and-retry"></a>

Web Chat の匿名訪問者は、元の会話の UUID を使って、まだ有効な Web Chat の会話のみを操作できます。ログインが必要な Web Chat では、匿名での継続会話の作成は受け付けません。ログイン済みのメンバーは、閲覧権限のある組織の会話や、自分が連絡先となっている会話を操作できます。連携側がタイムアウトにより同じサマリーを再送した場合は、`created` によって、まだ存在する会話を取得したかどうかを判断できます。削除された継続会話は再作成できます。


---

# 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/tech/ja/serve/conversation-handoff-continuation.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.