# Handing work to your own external AI agent

URL: https://mindmax.me/docs/guides/handing-work-to-an-agent/
Last verified: 2026-11-11

> How to phrase a request to a connected AI app so it knows what to do, what to leave alone and what to hand back into MindMax — and where to look afterwards.

## Handing work to your own external AI agent

This time the worker is **your own AI app**, not MindMax's assistant. MindMax has already given it
access to the folder; the only thing left is for you to say what you want. That sentence decides
what the app reads, what it is allowed to touch and where its answer lands. MindMax's buttons help
you write it, but they do not send anything and they do not put work in a queue — you paste the
sentence into your app and press send there.

If you meant to give a long job to MindMax's own assistant instead, that is
[handing the assistant a long job](https://mindmax.me/docs/guides/handing-off-a-job/), a different path billed to
your credits rather than your app's tokens.

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

- An app [connected to this workspace](https://mindmax.me/docs/getting-started/connect-an-ai-agent/), set to
**Collaborate**. A read-only connection can answer questions but cannot write anything back.

- The document, canvas or comment thread you care about, open in MindMax. What is in front is the
default scope.

## A request has three parts[​](https://mindmax.me/#a-request-has-three-parts)

**What to do · how to do it · what to hand back.** The third part is the one people leave out, and
it is the difference between "it told me about my draft" and "my draft now has a review waiting for
me".

| Instead of | Say | Why it works |
| --- | --- | --- |
| "Fix this" | "Tighten section 3 of the report I have open in MindMax. Keep my voice, don't touch the appendix, and propose the changes as suggestions." | Names the file, the boundary and the delivery |
| "What do you think?" | "Read the chapter I have open like a referee and write the problems as comments on the passages. Don't change the text yet." | Asks for an opinion in a place you can answer |
| "Continue" | "Handle the request I marked on the 'Pricing' card of the canvas I have open, and add your cards under that one." | Says which card, and where the new work goes |

A bare "?" on a sentence is also a complete request when you leave it as a comment — the intent you
pick (question, rewrite, doubtful, needs a source) tells the app what kind of answer you want. See
[working in the margin with an AI agent](https://mindmax.me/docs/guides/comments-with-an-agent/) for how a thread
hands the turn back and forth.

## What the app can see: four levels of scope[​](https://mindmax.me/#what-the-app-can-see-four-levels-of-scope)

The scope comes from your sentence, in this order. MindMax buttons only pre-fill it.

- **A named file or `@` mention.** "the report in `drafts/`" or a file you attached in the app.
Most precise, and the best choice for a long library.

- **The few you selected.** Comments ticked in the comments panel, or a card and the point under it
on a canvas. `get_active_context` reports this as the selection.

- **What is in front.** The document or canvas you last looked at in MindMax. "This paragraph"
usually resolves correctly because the app receives the passage and its section path.

- **The whole workspace.** If you say "my library" or name nothing at all, the app may search
everything it can reach. For a big folder, ask for the shortlist first —
[reading and reviewing with an agent](https://mindmax.me/docs/guides/reading-and-reviewing-with-an-agent/) shows
how a map narrows it down.

Nothing outside the workspaces you have opened is in reach. An absolute path outside them is refused
for writing.

## The three places that write the sentence for you[​](https://mindmax.me/#the-three-places-that-write-the-sentence-for-you)

| Where | What you press | What it copies |
| --- | --- | --- |
| Document toolbar | The external-AI menu at the top of an open document | A request about that document, with its path |
| Comments panel | Hand to {app} | A request to handle the comments waiting on that document |
| Canvas | Copy prompt next to the "N requests waiting" bar | "Handle the requests I marked on the canvas …" |

All three put a sentence on your clipboard. That is all. **Copy is not submission**: MindMax has no
way to wake an app up, so the request sits on the card or thread until you paste the sentence into
your app and send it. A marked canvas request is data on the card, not a message that has been
delivered — [canvas requests with an agent](https://mindmax.me/docs/guides/canvas-requests-with-an-agent/) covers
what happens after you do send it.

## Where the answer lands[​](https://mindmax.me/#where-the-answer-lands)

| You asked for | Look here | What you do next |
| --- | --- | --- |
| An answer | The app's own window | Nothing in the folder changed |
| Comments on passages | The comments panel, each note signed with the app's name | Reply, or mark done |
| A change to your draft | A review card with grouped tracked changes on your text | Accept or reject group by group — revising documents |
| New canvas cards | The canvas, with the app's signature on the cards it wrote | Pull on a branch, or mark another request |
| A new document or a long method's result | The file tree / reading panel | Read it, then run the next pass |

The status bar names the app while it works. Its session entry lists what it read and proposed, and
version history attributes every write. If something went wrong,
[pause or disconnect the app](https://mindmax.me/docs/guides/controlling-agent-access/) first.

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

**It worked on the wrong file.** Name the document in the sentence, or bring it to the front before
you copy. "The one I was reading" is ambiguous the moment two tabs are open.

**It answered in chat but wrote nothing.** The request did not say what to hand back. Add "write it
as comments on the passages" or "save it as a document in MindMax".

**It tried to use its own file-writing tool.** Some apps will try to write files directly instead of
calling MindMax's tools. On Claude-style hosts a write guard points them back to
`create_document` / `suggest_edits`; see [common issues](https://mindmax.me/docs/troubleshooting/common-issues/).

**You copied the prompt and expected a result.** Paste it into the app and send it. Copying changes
nothing in the workspace.

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

- [Revising documents with an agent](https://mindmax.me/docs/guides/revising-documents-with-an-agent/) — the four
shapes of a change, and the review gate.

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

Last updated on **Nov 11, 2026**