Skip to content

Canvas ​

A canvas is a document the agent opens next to the chat instead of pasting it into the answer. The agent writes and revises it, the person edits it by hand, goes back to an earlier version and downloads it.

Enterprise module

Canvas is the enterprise canvas module. A workspace whose package leaves it out shows Canvas is not in your package in the agent's Canvas section and agents are not offered canvases. See Licence packages.

Turn it on ​

Open Build → Agents, pick the agent and go to Build → Capabilities → Canvas. Switch on Let the agent open canvases. The setting is saved with the agent's configuration (config.canvas) and is live once you publish. Canvases are shown next to the chat in portals.

What the agent can open:

KindNotes
Document (Markdown)Exported as Markdown or PDF. The person edits it in a rich-text editor or as Markdown source.
Code fileShown in its language.
HTML pageRuns in an isolated frame without network access (a static preview).
SVG image

What a person can do ​

  • Open a canvas from the answer that made it (Open), close it (Close canvas) and go Back to the conversation.
  • Edit it and Save. A save becomes a new version; Nothing changed, so no new version was saved when the text is the same. While the agent is working on the canvas, saving waits until it finishes.
  • Browse Versions, look at an older one and Restore this version: a restore is a new version, nothing is lost. If the canvas changed while the person was editing, they choose Save mine as a new version or Take the newest version.
  • Download it and Copy link.

A canvas is personal to the person, the portal and the conversation it was made in; there is no shared editing. The neutral link APP_URL/canvas/<id> routes the person to the portal that made the canvas (a person who only uses portals gets the portal chooser when the canvas was made outside one). Anybody else cannot open it and gets the same "no longer available" as for a canvas that does not exist.

Limits ​

The limits are set for the whole platform, not per agent:

LimitDefaultVariable
One canvas version256 KB (at most 4 MB)AGENT_CANVAS_MAX_CONTENT_BYTES
Canvases per conversation20AGENT_CANVAS_MAX_PER_CONVERSATION
Versions kept per canvas (besides version 1)100AGENT_CANVAS_MAX_VERSIONS
All canvases of one person50 MBAGENT_CANVAS_MAX_BYTES_PER_OWNER
Find/replace pairs in one canvas_edit call20 (1 to 100)AGENT_CANVAS_MAX_EDITS_PER_CALL

AGENT_CANVAS_ENABLED=false switches canvases off for everyone: agents are not offered the tools, and stored canvases stay readable. AGENT_CANVAS_STATE_INLINE_BYTES and AGENT_CANVAS_READ_CHUNK_BYTES tune how much of the open canvas the agent sees; all variables are in Configuration. Canvas is a package module, not a service id: it is not switched off with CONSOLE_DISABLED_SERVICES.

Over the API ​

An answer's output_files lists the canvases it wrote with type: "canvas", a download_url and a view_url (the canvas's own link for a person). The client API reads them as the session's owner:

CallWhat it returns
GET /client/v1/agents/sessions/{id}/canvasesThe caller's own canvases of the session, newest activity first. limit (1 to 500, default 500); when has_more is true pass next_cursor as after.
GET /client/v1/agents/sessions/{id}/canvases/{canvasId}/contentOne canvas as a file: its current version, or an earlier one with ?version=<n>. Always a download (attachment); an HTML or SVG canvas is never rendered from this origin.

Another person's canvas, an unknown version, and every canvas while canvases are off are 404. See Agent Sessions API.

Studio · Pulse · Console · Agent SDK and more — the Cognipeer documentation hub