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

# Canvas

Canvas（畫布）的概念，以及 MaiAgent 的 Agent 如何把產出交給畫布代理、支援哪些內容類型、在哪些對話平台顯示，與相關限制。

## 什麼是 Canvas

一般而言，Canvas（畫布）是在對話旁獨立顯示「一份完整產出」的介面：文件、圖表、網頁或互動元件不混在對話文字裡，可以單獨預覽、反覆修改與下載。

在 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**：預設使用畫布模式，成員直接在對話中使用。

### 一次回覆的流程 <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 多了一個交接工具，系統提示詞也會附上交接說明：要畫圖、把資料視覺化、做網頁或 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 頁面（HTML、CSS、JS 寫在同一檔），在 iframe 中執行                                     | `.html`                    |
| `svg`      | 向量圖                                                                               | `.svg`                     |
| `mermaid`  | 流程圖、時序圖、甘特圖等圖表；內容串流完成後才繪製                                                         | `.md`（其他對話平台的下載連結為 `.mmd`） |
| `react`    | 在瀏覽器端編譯後預覽的 React 元件，可使用 React、lucide-react、recharts、shadcn/ui 元件與 Tailwind class | `.jsx`                     |
| `map`      | 互動地圖，內容是含中心點、地點標記與路線的 JSON                                                        | `.json`                    |

畫布面板提供預覽、原始碼檢視，以及下載原始格式或 PDF。

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

| `display`   | 用途                                                                  |
| ----------- | ------------------------------------------------------------------- |
| `inline`    | 直接嵌在對話訊息中，用於幫助理解當下內容的小型圖表或說明圖                                       |
| `panel`（預設） | 在側邊面板開啟，用於使用者會保存、修改或在對話外使用的產出，例如文件、完整網頁、互動元件、地圖；內容較長（約 40 行以上）時也用面板 |

畫布只在 Web Chat 與 MaiGPT 網頁版的對話介面渲染。LINE、Microsoft Teams、Slack 等其他對話平台無法顯示畫布，平台會在回覆後附上畫布的下載連結，連結 7 天內有效。

### 什麼時候會用畫布 <a href="#when-canvas-is-used" id="when-canvas-is-used"></a>

畫布代理的交接條件與提示詞規範如下：

* **會交接**：使用者要求畫圖（例如 SVG）、把資料或概念視覺化（例如 Mermaid）、做網頁或 UI 元件、產生格式化文件或報告、在地圖上顯示地點。
* **偏向不用畫布**：解說或教學性質的內容、針對既有內容的建議、依賴當下對話才有意義的內容、一次性的問題。能直接在對話中呈現時，提示詞要求以對話呈現。
* **一則訊息一份畫布**：除非使用者要求，每則回覆只產生一份畫布。

希望使用畫布時，可以在提問時直接說明，例如「用畫布做一份……」。

### 地圖畫布 <a href="#map-canvas" id="map-canvas"></a>

* 部署環境設定了 Google Maps API 金鑰時，畫布代理才有地點搜尋（`place_search`）與大眾運輸路線（`get_transit_directions`）兩個工具；沒有這兩個工具時，只能依模型既有知識標出知名地點。
* 這兩個工具每次呼叫扣 Credits。MaiGPT 成員的角色沒有開放對應的官方工具時，畫布代理也不會拿到。

### 主要應用情境 <a href="#use-cases" id="use-cases"></a>

| 情境                    | 常用類型           |
| --------------------- | -------------- |
| 流程圖、組織圖、時序圖、甘特圖       | `mermaid`      |
| 報告、Email、會議紀錄等文件      | `markdown`     |
| 以知識庫或資料庫查到的數據製作圖表、儀表板 | `react`        |
| 單頁網頁、介面原型             | `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 中執行（只允許執行 script，與宿主網站不同源），無法讀取宿主網站的 Cookie 與儲存空間。畫布提示詞要求模型不使用網路圖片、外部 script 只從 `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/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.