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

# Canvas

The concept of Canvas, how MaiAgent Agents hand off output to the canvas agent, supported content types, where canvases appear across conversation platforms, and related limitations.

## What Is Canvas?

In general, Canvas is an interface that displays a complete output separately alongside a conversation. Documents, diagrams, web pages, and interactive components are kept separate from conversation text so you can preview, revise, and download them independently.

In MaiAgent, Canvas is a setting within Agent mode. When an Agent determines that its output is suitable for a canvas, it hands off to the platform’s built-in canvas agent to generate the content. The conversation interface then renders it according to its content type.

***

## How It Works in MaiAgent <a href="#how-it-works" id="how-it-works"></a>

### Configure and Enable Canvas

* **Agent**: In the Agent’s <mark style="color:blue;">Response Mode Settings</mark>, set <mark style="color:blue;">Response Mode</mark> to <mark style="color:blue;">Agent Mode</mark>. Then select <mark style="color:blue;">Canvas Mode (Canvas)</mark> under <mark style="color:blue;">Agent Mode</mark> below. Only models that support tool calling can use canvas mode. Your organization’s plan may also limit the available Agent modes.
* **MaiGPT**: Uses canvas mode by default. Members can use it directly in conversations.

### The Flow of a Response <a href="#flow" id="flow"></a>

```mermaid
sequenceDiagram
    participant U as User
    participant A as Agent
    participant C as Canvas Agent
    participant P as MaiAgent Platform
    participant F as Conversation Interface

    U->>A: Ask a question
    A->>A: Call tools first if needed (e.g., knowledge base retrieval)
    A->>C: Handoff
    C->>P: Stream explanatory text plus canvas content wrapped in markers
    P->>P: Extract canvas content and save it in the conversation
    P-->>F: Stream canvas content
    F->>F: Render by content type
```

1. **Handoff**: An Agent in canvas mode has an additional handoff tool, and its system prompt includes handoff instructions. To draw diagrams, visualize data, create web pages or UI components, or generate formatted documents, it hands off to the canvas agent. Maps are an exception: if the Agent has already obtained coordinates using the place search tool, it follows the prompt to output a map canvas itself.
2. **Generation**: The canvas agent uses the same model as the Agent and generates content using the platform’s canvas prompt. Data retrieved from the knowledge base during this turn is also included in its prompt. Its tool calling rounds are subject to the Agent’s “Maximum Iterations” limit as well.
3. **Markers**: Each canvas includes `name` (an identifier; reusing the same name updates the same canvas), `type` (content type), `title` (title), and `display` (display location).
4. **Storage**: The platform saves canvas content with the conversation, so you can still view it when you reopen the conversation.

### Supported Content Types <a href="#content-types" id="content-types"></a>

| `type`     | Presentation                                                                                                                               | Download Format                                                   |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `markdown` | Markdown document                                                                                                                          | `.md`                                                             |
| `html`     | A single-file HTML page (HTML, CSS, and JS in one file), executed in an iframe                                                             | `.html`                                                           |
| `svg`      | Vector graphic                                                                                                                             | `.svg`                                                            |
| `mermaid`  | Flowcharts, sequence diagrams, Gantt charts, and other diagrams; rendered after content streaming finishes                                 | `.md` (download links on other conversation platforms use `.mmd`) |
| `react`    | React components compiled and previewed in the browser; supports React, lucide-react, recharts, shadcn/ui components, and Tailwind classes | `.jsx`                                                            |
| `map`      | Interactive map with JSON containing a center point, place markers, and routes                                                             | `.json`                                                           |

The canvas panel offers a preview, a source code view, and downloads in the original format or as PDF.

### Display Location <a href="#display" id="display"></a>

| `display`         | Purpose                                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inline`          | Embedded directly in conversation messages for small charts or illustrations that help explain the current content                                                                                                             |
| `panel` (default) | Opens in a side panel for outputs users will save, revise, or use outside the conversation, such as documents, complete web pages, interactive components, and maps; also used for longer content (roughly more than 40 lines) |

Canvases render only in the conversation interfaces of Web Chat and the MaiGPT web app. Other conversation platforms, such as LINE, Microsoft Teams, and Slack, cannot display canvases. The platform appends canvas download links after the response; these links remain valid for 7 days.

### When Canvas Is Used <a href="#when-canvas-is-used" id="when-canvas-is-used"></a>

The handoff conditions and prompt guidelines for the canvas agent are:

* **Handoff occurs**: When users ask to draw diagrams (e.g., SVG), visualize data or concepts (e.g., Mermaid), create web pages or UI components, generate formatted documents or reports, or display places on a map.
* **Canvas is generally avoided**: For explanations or tutorials, suggestions about existing content, content that only makes sense within the current conversation, and one-off questions. When content can be presented directly in the conversation, the prompt instructs the model to do so.
* **One canvas per message**: Each response produces only one canvas unless the user requests otherwise.

To request a canvas, state it explicitly in your question, for example, “Use Canvas to create a…”.

### Map Canvas <a href="#map-canvas" id="map-canvas"></a>

* The canvas agent receives the place search (`place_search`) and public transit directions (`get_transit_directions`) tools only when a Google Maps API key is configured in the deployment environment. Without these tools, it can only mark well-known places based on the model’s existing knowledge.
* Each call to these tools consumes Credits. If a MaiGPT member’s role does not allow the corresponding official tools, the canvas agent will not receive them either.

### Main Use Cases <a href="#use-cases" id="use-cases"></a>

| Use Case                                                                     | Common Types    |
| ---------------------------------------------------------------------------- | --------------- |
| Flowcharts, organizational charts, sequence diagrams, Gantt charts           | `mermaid`       |
| Documents such as reports, Email, and meeting minutes                        | `markdown`      |
| Charts and dashboards using data retrieved from a knowledge base or database | `react`         |
| Single-page websites and interface prototypes                                | `html`, `react` |
| Place introductions, itinerary planning, and transportation routes           | `map`           |
| Simple icons and illustrations                                               | `svg`           |

For creating reports from database query results, see [Text to SQL Report Creation (Canvas Mode)](https://docs.maiagent.ai/build/database/text-to-sql-maiagent#report-creation-canvas-mode) in the User Manual.

### Demo Video <a href="#demo-video" id="demo-video"></a>

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

***

## Limitations and Considerations <a href="#limitations" id="limitations"></a>

* **Role instructions are not passed to the canvas agent**: Its system prompt consists of the platform’s canvas prompt and this turn’s knowledge base data, without the Agent’s role instructions. It can see the full conversation, but formatting, terminology, or branding requirements in role instructions may not be reflected in the canvas content. Include them directly in your question when needed.
* **The canvas prompt is configured at the platform level**: All organizations share the same canvas prompt and cannot customize it themselves.
* **HTML and React limitations**: HTML canvases in Web Chat run in a sandboxed iframe (only script execution is allowed, and the iframe has a different origin from the host website). They cannot access the host website’s cookies or storage. The canvas prompt instructs the model not to use images from the web and to load external scripts only from `cdnjs.cloudflare.com`. React canvases can only import the packages listed in the table above.
* **Correct rendering is not guaranteed**: The platform does not check the syntax of generated canvas content. If the model generates invalid code or diagram syntax, the content may fail to display. You can ask the Agent to fix it and regenerate it.
* **Making changes**: Markdown canvases cannot be edited directly on screen. To make changes, describe them in the conversation. The canvas prompt instructs the model to regenerate the complete content using the same `name`. Alternatively, download and edit the source file yourself; local edits are not written back to the canvas.
* **Other conversation platforms receive download links only**: See [Display Location](#display) above.

***

## See the User Manual for Instructions <a href="#user-guide-links" id="user-guide-links"></a>

* [Canvas in MaiGPT](https://docs.maiagent.ai/work/maigpt/canvas): View, download, and ask AI to modify canvases
* [Configure Tools for an Agent: Switch the Agent’s Response Mode](https://docs.maiagent.ai/build/tools/configure_tools#step-3-switch-qa-mode)
* [Text to SQL Report Creation (Canvas Mode)](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/en/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.