# Canvas requests with an external AI agent

URL: https://mindmax.me/docs/guides/canvas-requests-with-an-agent/
Last verified: 2026-11-11

> Mark a card or a point on a MindMax canvas, hand one sentence to a connected AI app, and get new branches back on the same board — with what each host shows you.

## Canvas requests with an external AI agent

A canvas request is a mark you leave **on a card or on one point under it**, asking a connected AI
app to keep thinking from exactly there. The request stays with the card as data, the app reads it
on its next visit, and its answer comes back as new cards hanging off the branch you pointed at.
MindMax does not wake the app up: marking a request copies one sentence for you to paste into your
app. That is the whole handoff — a sentence, not a queued job.

This is the path for work that grows over several rounds. If you want a question opened up in one
pass, [open a hard question on the canvas with your agent](https://mindmax.me/use-cases/open-a-question-on-canvas-with-your-agent/)
is the shorter read; [thinking on the canvas](https://mindmax.me/docs/guides/thinking-on-the-canvas/) covers the board
itself.

## Before you start[​](https://mindmax.me/#before-you-start)

- A canvas in the folder MindMax has open, with at least one card you want to pull on.

- An app [connected with Collaborate access](https://mindmax.me/docs/getting-started/connect-an-ai-agent/) —
adding cards is a write.

- The canvas brought to the front, so "this card" has an unambiguous meaning.

## Mark a request[​](https://mindmax.me/#mark-a-request)

- Hover a point under a card and press **Hand to {app}**, or open the card's **⋯** menu
and choose **Hand to {app}…** for the whole card. These entries appear only when a
writable external app is connected.

- Write what you want — "compare these two options", "what would have to be true for this to
fail?" — or leave the text empty. An empty request means _keep thinking from here_.

- The card gets a small signed strip showing how many requests are waiting, and a toast offers
**Copy that sentence**. The canvas bar has the same **Copy prompt** next to the waiting count.

Handle the requests I marked on the canvas "Q3 pricing options" in MindMax, and add your cards
under the ones I marked.

Paste that into your app and send it. **Copying changes nothing**: the canvas keeps the request in
its waiting state until an app actually reads and answers it. See
[handing work to an agent](https://mindmax.me/docs/guides/handing-work-to-an-agent/) for why the button is a
sentence-writer and not a submit button.

## What the app reads[​](https://mindmax.me/#what-the-app-reads)

| Step | What happens | Tool |
| --- | --- | --- |
| "This one" | MindMax reports the canvas in front, the selected card, the point last clicked and the branch path to it | get_active_context with canvasSelection |
| The waiting requests | A list of canvas_request items, by default only the pending ones, with ids like canvas-ask:@ | get_annotations |
| Only what changed | Pass back the "Read at" timestamp from the last read to get just the delta | read_canvas {since} |
| The whole board | Cards, who wrote each one, the points under them and the relations drawn — including your answers and which branches you dug into | read_canvas |

The app then writes cards with `add_canvas_cards`, attaching them to the card (and point) you marked,
naming the request ids in `answering`. That marks the requests handled and points them at the new
cards. A short answer can instead go through `reply_to_comment` with the `canvas-ask:` id. On the
card, the strip changes to show the reply and a link to the new cards; you can reopen a request if
the answer missed, or delete it.

## What you will see, by host[​](https://mindmax.me/#what-you-will-see-by-host)

`show_canvas` is called once at the end of a round. All three tiers can call it — the difference is
only **how the picture is shown**:

| Host | What you see | What the app tells you |
| --- | --- | --- |
| Hosts with interactive cards (including ChatGPT desktop) | The canvas as a clickable card in the chat; click a card to ask the app to keep exploring it | A line or two on what was added and where to look |
| Most other desktop hosts | A picture of the whole canvas after the text, with the new cards highlighted | A line or two on what was added |
| Terminal hosts (Claude Code, Codex) | No picture in the chat. MindMax brings the canvas to the front in its own window | "It is open there (link), and here is what the new cards say" |

**Not seeing a picture does not mean nothing was drawn.** The cards are in the canvas file either
way. In a terminal host, switch to MindMax and the board is already in front with the new cards in
view. The tier is decided at connection time from what the host says it can display — there is no
setting to change it.

The board after a round: new cards grow from the branch you marked, each signed with the app that wrote it.

## What the app may change[​](https://mindmax.me/#what-the-app-may-change)

It can **add** cards and points, draw support, contradiction or reference relations between cards
with `link_canvas_cards`, and **revise cards it wrote itself** with `revise_canvas_card`. On cards
MindMax generated it may only append points; on cards you wrote, revision is refused. Moving cards,
changing colours, deleting cards and rewriting your cards have no tool at all — those stay yours in
MindMax. Question cards you answered can be graded with `grade_canvas_answers`, which adds a verdict
and a note to your answer.

When a branch is settled, `create_document` with `fromCanvas {path, nodeId?}` writes it up as a new
document and hangs a linked document card back on the canvas, so the board shows which branch became
which note. [Brainstorm a product with your agent](https://mindmax.me/use-cases/brainstorm-a-product-with-your-agent/)
walks that path end to end.

## Common problems[​](https://mindmax.me/#common-problems)

**The request is still waiting.** You copied the sentence but did not send it, or the app used a
read-only connection. Send it in the app, then look at the card's strip again.

**New cards appeared at the top level instead of under my point.** Name the card in the sentence and
keep it selected when you copy, so `canvasSelection` carries the branch.

**The app tried to rewrite my cards.** That is refused by design. Ask it to add a new card instead —
the original stays yours.

**Claude Code says the canvas is open but shows nothing.** It is open in the MindMax window. Switch
to it; the app's reply should include the link and a summary of the new cards.

## Next[​](https://mindmax.me/#next)

- [Long jobs with an agent](https://mindmax.me/docs/guides/long-jobs-with-an-agent/) — when the thinking needs a
whole method rather than one round of cards.

- [Working with an external AI agent](https://mindmax.me/docs/guides/working-with-an-external-ai-agent/) — the
capability map.

Last updated on **Nov 11, 2026**