> 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/advanced-genai-tech/canvas.md).

# Canvas

Canvas（キャンバス）の概念と、MaiAgent の Agent がキャンバスエージェントに出力を引き継ぐ仕組み、対応するコンテンツの種類、表示可能な会話プラットフォーム、関連する制約を説明します。

## Canvas とは

一般に Canvas（キャンバス）は、会話の横に「完成した 1 つの出力」を独立して表示するインターフェースです。ドキュメント、図、Web ページ、インタラクティブなコンポーネントを会話のテキストと分け、個別にプレビュー、繰り返しの修正、ダウンロードができます。

MaiAgent では、Canvas は Agent モード内の設定の一つです。Agent が今回の出力はキャンバスに適していると判断すると、プラットフォーム内蔵のキャンバスエージェントにコンテンツの生成を引き継ぎます。会話インターフェースはコンテンツの種類に応じてレンダリングします。

***

## MaiAgent での仕組み <a href="#how-it-works" id="how-it-works"></a>

### 設定と有効化

* **Agent**：Agent の <mark style="color:blue;">回答モード設定</mark> で <mark style="color:blue;">回答モード</mark> を <mark style="color:blue;">Agent モード</mark> に設定し、その下の <mark style="color:blue;">Agent モード</mark> で <mark style="color:blue;">キャンバスモード (Canvas)</mark> を選択します。ツール呼び出しに対応したモデルのみキャンバスモードを選択できます。組織のプランによって、利用可能な Agent モードが制限される場合もあります。
* **MaiGPT**：デフォルトでキャンバスモードを使用し、メンバーは会話内で直接利用できます。

### 1 回の回答の流れ <a href="#flow" id="flow"></a>

```mermaid
sequenceDiagram
    participant U as ユーザー
    participant A as Agent
    participant C as キャンバスエージェント
    participant P as MaiAgent プラットフォーム
    participant F as 会話インターフェース

    U->>A: 質問します
    A->>A: 必要に応じて先にツールを呼び出します（例：ナレッジベース検索）
    A->>C: 引き継ぎます（handoff）
    C->>P: 説明文とマーカーで囲んだキャンバス内容をストリーミング出力します
    P->>P: キャンバス内容を抽出し、会話に保存します
    P-->>F: キャンバス内容をストリーミング配信します
    F->>F: コンテンツの種類に応じてレンダリングします
```

1. **引き継ぎ**：キャンバスモードの Agent には引き継ぎツールが追加され、システムプロンプトにも引き継ぎの説明が含まれます。図の作成、データの可視化、Web ページや UI コンポーネントの作成、書式付きドキュメントの生成では、キャンバスエージェントに引き継ぎます。地図は例外で、Agent が場所検索ツールで座標を取得済みの場合は、プロンプトに従って自身で地図キャンバスを出力します。
2. **生成**：キャンバスエージェントは Agent と同じモデルを使い、プラットフォームに設定されたキャンバスプロンプトに従ってコンテンツを生成します。このターンでナレッジベースから取得した情報も、そのプロンプトに含まれます。ツール呼び出しの反復回数も、Agent の「最大反復回数」の制限を受けます。
3. **マーカー**：各キャンバスには `name`（識別名。同じ名前を使うと同じキャンバスを更新します）、`type`（コンテンツの種類）、`title`（タイトル）、`display`（表示位置）が付いています。
4. **保存**：プラットフォームはキャンバス内容を会話とともに保存するため、会話を再度開いたときにも閲覧できます。

### 対応するコンテンツの種類 <a href="#content-types" id="content-types"></a>

| `type`     | 表示方法                                                                                                    | ダウンロード形式                                  |
| ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `markdown` | Markdown ドキュメントです                                                                                       | `.md`                                     |
| `html`     | HTML、CSS、JS を 1 ファイルに記述した HTML ページを iframe 内で実行します                                                      | `.html`                                   |
| `svg`      | ベクター画像です                                                                                                | `.svg`                                    |
| `mermaid`  | フローチャート、シーケンス図、ガントチャートなどです。コンテンツのストリーミング完了後に描画します                                                       | `.md`（他の会話プラットフォームのダウンロードリンクでは `.mmd` です） |
| `react`    | ブラウザー側でコンパイルしてプレビューする React コンポーネントです。React、lucide-react、recharts、shadcn/ui コンポーネント、Tailwind クラスを使用できます | `.jsx`                                    |
| `map`      | 中心点、場所のマーカー、経路を含む JSON によるインタラクティブな地図です                                                                 | `.json`                                   |

キャンバスパネルでは、プレビュー、ソースコードの表示、元の形式または PDF でのダウンロードができます。

### 表示位置 <a href="#display" id="display"></a>

| `display`      | 用途                                                                                                                     |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `inline`       | 会話メッセージに直接埋め込み、現在の内容の理解を助ける小さな図表や説明図に使用します                                                                             |
| `panel`（デフォルト） | サイドパネルで開き、保存、修正、会話外での使用を想定する出力に使用します。ドキュメント、完全な Web ページ、インタラクティブなコンポーネント、地図などが該当します。長いコンテンツ（およそ 40 行を超える場合）にもパネルを使用します |

キャンバスは Web Chat と MaiGPT Web 版の会話インターフェースでのみレンダリングされます。LINE、Microsoft Teams、Slack などの他の会話プラットフォームでは表示できません。プラットフォームは回答の後にキャンバスのダウンロードリンクを追加し、リンクは 7 日間有効です。

### キャンバスを使用する場面 <a href="#when-canvas-is-used" id="when-canvas-is-used"></a>

キャンバスエージェントへの引き継ぎ条件とプロンプトの規則は次のとおりです。

* **引き継ぐ場合**：ユーザーが図の作成（例：SVG）、データや概念の可視化（例：Mermaid）、Web ページや UI コンポーネントの作成、書式付きドキュメントやレポートの生成、地図上での場所の表示を求めた場合です。
* **キャンバスを使わない傾向がある場合**：解説やチュートリアル、既存の内容への提案、現在の会話に依存する内容、単発の質問です。会話内に直接表示できる場合、プロンプトは会話内での提示を指示します。
* **1 メッセージにつき 1 キャンバス**：ユーザーが求めない限り、各回答では 1 つのキャンバスのみ生成します。

キャンバスを使いたい場合は、質問時に「キャンバスで……を作成してください」などと明示してください。

### 地図キャンバス <a href="#map-canvas" id="map-canvas"></a>

* デプロイ環境に Google Maps API キーが設定されている場合のみ、キャンバスエージェントは場所検索（`place_search`）と公共交通機関の経路検索（`get_transit_directions`）の 2 つのツールを利用できます。これらのツールがない場合、モデルの既存の知識に基づいて有名な場所を表示することしかできません。
* この 2 つのツールは、呼び出すたびに Credits を消費します。MaiGPT メンバーのロールで対応する公式ツールが許可されていない場合、キャンバスエージェントにも提供されません。

### 主な活用例 <a href="#use-cases" id="use-cases"></a>

| 活用例                                     | よく使う種類         |
| --------------------------------------- | -------------- |
| フローチャート、組織図、シーケンス図、ガントチャートです            | `mermaid`      |
| レポート、Email、議事録などのドキュメントです               | `markdown`     |
| ナレッジベースやデータベースから取得したデータによるグラフやダッシュボードです | `react`        |
| 単一ページの Web サイトやインターフェースのプロトタイプです        | `html`、`react` |
| 場所の紹介、旅行計画、交通経路です                       | `map`          |
| 簡単なアイコンや説明図です                           | `svg`          |

データベースのクエリ結果からレポートを作成する方法は、ユーザーマニュアルの [Text to SQL レポート作成（Canvas モード）](https://docs.maiagent.ai/build/database/text-to-sql-maiagent#report-creation-canvas-mode)をご覧ください。

### デモ動画 <a href="#demo-video" id="demo-video"></a>

{% embed url="<https://drive.google.com/file/d/1GW7o3m130M-yESZ4h6VwZvNXDhdJDiFe/view?usp=drive_link>" %}

***

## 制約と注意事項 <a href="#limitations" id="limitations"></a>

* **ロール指示はキャンバスエージェントに渡されません**：キャンバスエージェントのシステムプロンプトは、プラットフォームに設定されたキャンバスプロンプトと、このターンのナレッジベース情報で構成され、Agent のロール指示は含まれません。会話全体は参照できますが、ロール指示にある書式、用語、ブランドに関する要件がキャンバス内容に反映されるとは限りません。必要な場合は質問内で直接指定してください。
* **キャンバスプロンプトはプラットフォーム単位の設定です**：すべての組織が同じキャンバスプロンプトを共有し、組織側で独自に調整することはできません。
* **HTML と React の制約**：Web Chat の HTML キャンバスはサンドボックス化された iframe 内で実行されます。スクリプトの実行のみが許可され、ホスト Web サイトとは異なるオリジンのため、ホスト Web サイトの Cookie やストレージにはアクセスできません。キャンバスプロンプトはモデルに対し、Web 上の画像を使わず、外部スクリプトを `cdnjs.cloudflare.com` からのみ読み込むよう指示します。React キャンバスで import できるのは、上の表に記載されたパッケージのみです。
* **正しくレンダリングされる保証はありません**：プラットフォームは生成後にキャンバス内容の構文を検査しません。モデルが生成したコードや図の構文に誤りがあると、表示できない場合があります。Agent に修正と再生成を依頼できます。
* **修正方法**：Markdown キャンバスは画面上で直接編集できません。修正する場合は、会話で変更箇所を説明してください。キャンバスプロンプトは、同じ `name` で内容全体を再生成するよう指示します。または、ソースファイルをダウンロードして編集できますが、ローカルでの変更はキャンバスに反映されません。
* **他の会話プラットフォームにはダウンロードリンクのみ提供されます**：上の[表示位置](#display)をご覧ください。

***

## 操作方法はユーザーマニュアルをご覧ください <a href="#user-guide-links" id="user-guide-links"></a>

* [MaiGPT の Canvas キャンバス](https://docs.maiagent.ai/work/maigpt/canvas)：キャンバスの閲覧、ダウンロード、AI への修正依頼を説明します
* [Agent のツール設定：Agent の回答モードの切り替え](https://docs.maiagent.ai/build/tools/configure_tools#step-3-switch-qa-mode)
* [Text to SQL レポート作成（Canvas モード）](https://docs.maiagent.ai/build/database/text-to-sql-maiagent#report-creation-canvas-mode)


---

# 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/advanced-genai-tech/canvas.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.