# The assistant

Ask a model of your choice from inside a document and watch its answer write itself into the page, called from your device with your own API key.

Every document has an assistant behind the sparkle in the status bar. You ask it for something, and the answer streams into the document as formatted text, written the way an agent writes over MCP: a caret with a name moves along as the words arrive. It works signed in or not, since it needs only the provider you choose and your key for it.

To have an agent work in your documents from outside Entz, connect it over MCP instead: see [Agents in Entz](/docs/mcp/).

## Set it up

1. Open **Settings** and go to **Assistant**.
2. Choose a **Provider**: **Anthropic**, **OpenAI**, **Google**, **xAI**, **Groq**, or **OpenAI-compatible** for a server of your own or a gateway that speaks OpenAI's Chat Completions API (Ollama, LM Studio and vLLM do).
3. Choose a **Model** from the provider's list. For an OpenAI-compatible server, type the model's name, and the server's address in **Base URL**, such as `http://localhost:11434/v1`.
4. Paste your **API key** from the provider. An OpenAI-compatible server may not need one.

[Settings](/docs/settings/) lists the models each provider offers.

## Your key stays on your device

The request goes from your device to the provider, and the answer comes straight back. No Entz server stands in between: Entz never sees what you ask, the text that goes along with it, the answer or your key. The key is kept with your settings on this device (in the browser's storage on the web) and goes only to the provider you chose. Requests count against your account with that provider, under its terms.

:::caution
On a computer other people use, clear the **API key** field when you are done: the key stays in the browser until you do.
:::

:::note
On the web, requests come from the page at entz.app, so a server of your own must accept requests from `https://entz.app` (its CORS setting), and the browser must be able to reach it.
:::

## Ask

1. Select text first if your request is about it.
2. Press the sparkle in the status bar (**Ask the assistant**; a magic wand on the web and Android). A field opens in the status bar, and on a phone it takes the whole bar.
3. Type your request and press `Enter`, the send button, or the Send key on a phone's keyboard.

`Escape` or the × button (**Close the assistant**) closes the field. Closing it does not stop an answer on its way.

## Where the answer goes

The button after the field, whose icon shows the current choice, opens a menu of where the answer goes. The field's placeholder repeats the choice.

| Choice | Where the answer lands |
|---|---|
| **Let the model decide** | Where the model judges best from your request: at the caret, in place of the selection, or in place of the whole document. This is the default. |
| **Insert at the caret** | After the block the caret is in, or in that block when it is an empty line. For continuing the text, answering a question or adding a section. |
| **Replace the selection** | In place of the selected text, for rewriting, translating, fixing or expanding it. Only available while text is selected. |
| **Replace the document** | In place of everything in the document, for translating, reformatting, restructuring or summarising it as a whole. |

With **Let the model decide**, an answer the model does not place goes in place of the selection when there is one, and at the caret otherwise. The menu goes back to **Let the model decide** when you open another document.

## What goes along

With your request, the model receives:

- the document, as Markdown. A document longer than 100,000 characters (about 25,000 tokens) goes as a window of that size around the caret, with a note of how much was left out before and after it;
- your selection, when there is one;
- where the answer goes, when you chose.

Nothing else goes: not your other documents, not the document's other [tabs](/docs/tabs/), not its [comments](/docs/comments/).

The model is asked to reply with the content alone, in the document's language, tone and formatting, using headings, lists, tables and code where they help. It is also asked to send diagrams and charts as Mermaid diagrams and mathematics as formulas, which Entz draws ([Diagrams, math and code](/docs/diagrams/)).

## Watch it write

As soon as you send, a grey placeholder showing your request appears after the caret's block (or in its place, when it is an empty line), with the assistant's caret waiting in it. The answer takes the placeholder's place when its first words arrive, formatted as it lands: a heading, a list or a table becomes one as soon as it is complete. While the end of the answer is on screen, the page scrolls to keep it in view; scroll away and the page stays where you put it.

The caret carries the assistant's name, in its provider's colour:

| Provider | Name on the caret |
|---|---|
| Anthropic | Claude |
| OpenAI | GPT |
| Google | Gemini |
| xAI | Grok |
| Groq, OpenAI-compatible | Assistant |

The assistant shows among the people on the right of the status bar while it writes and for a few seconds after, and pressing it follows its caret ([Presence and following](/docs/presence/)). In a shared document, everyone who has it open sees the answer arrive the same way.

## Stop, undo and errors

- While the answer streams, the field reads **Answering…** and the send button becomes a stop button (**Stop the answer**). Stopping keeps what has arrived.
- Undo takes the answer out like any edit, and brings back text it replaced.
- With no key set (for an OpenAI-compatible server, no address or no model), sending says "Choose a provider and enter its key in Settings".
- When the provider refuses (a wrong key, a model it does not know, no connection), its reason shows in red beside the field, with the status code when there is one, such as `401: …`. It stays until your next request.