# Working with the AI Assistant

> The AI Assistant sits on every page of nexxus. It knows where you are, works with your data and your rights, shows where its answers come from, and changes nothing until you approve. This page shows how to get the most out of it.

The AI Assistant is built into nexxus. It sits on every page, so you never have to copy data into a chat window: open the customer Nordwind AG, ask "which invoices are still open here?", and it already knows which customer you mean. It reads your company's knowledge and your files, uses the tools your company has connected, and works through whole tasks, sometimes for several minutes, while you do something else.

Every installation can give the AI Assistant its own name: an admin enters it in the field <Ui>Name</Ui> under <MenuPath to="Administration > Operations > Setup" />, step <Ui>AI</Ui> (see [below](#give-the-assistant-your-companys-name)). The app then shows that name in its labels. Unless it is changed, the name is Ava. Where a label quoted on these pages says "AI Assistant", your app shows the name your installation chose, or the one you gave it yourself (see [Your own AI Assistant](#your-own-ai-assistant)).

Two rules shape everything the AI Assistant does. **It can only do what you may do yourself**, because every tool it uses runs with your rights. And **the AI Assistant proposes, you approve**: whenever something would change, you see a card with the exact change and nothing happens until you click.

Take Mia Schulz, office manager at Brandt & Söhne. Mia filters the customer list to customers without a project in the last 90 days and asks the AI Assistant for a follow-up plan. It reads the filtered list, looks up the contact persons, drafts the plan and proposes three follow-up tasks on one card. Mia deselects one of the three customers on the card and clicks <Ui>Execute 2 of 3</Ui>. Both tasks are created, or neither: if the second one failed, the first would be rolled back.

<Hub
  inputsLabel="The AI Assistant works with"
  inputs={[
    { icon: 'map-pin', title: 'The page you are on', text: 'The list with its filters, the record you opened' },
    { icon: 'library', title: 'Your company knowledge', text: 'Knowledge entries and the content of your files' },
    { icon: 'plug-zap', title: 'Connected systems', text: 'Connectors your admin has set up' },
  ]}
  core={{
    title: 'AI Assistant',
    text: 'One assistant, on every page',
    items: ['Your rights', 'Your model', 'Your conversations'],
  }}
  outputsLabel="You get"
  outputs={[
    { icon: 'message-square-text', title: 'Answers with sources', text: 'You see what the answer is based on' },
    { icon: 'shield-check', title: 'Proposals to approve', text: 'Changes happen only after your click' },
    { icon: 'file-check', title: 'Files', text: 'Documents, tables and images the AI Assistant creates' },
  ]}
/>

## Open the AI Assistant

The AI Assistant's button sits at the top right of every page. It carries the assistant's name (tooltip <Ui>Open or close AI Assistant</Ui>). Click it and a column opens on the right, next to the page you are on.

<Screenshot src={shot_ai_assistant_column} url="/partner/customers" alt={"The AI Assistant's column open next to the customer list"} caption={"The column stays open while you move between pages."} />

- **The column stays.** It stays open while you move from page to page, and the conversation goes on. A new page only changes what the AI Assistant knows about where you are.
- **Make it wider or narrower** by dragging its left edge (<Ui>Drag to resize, double-click to reset</Ui>). The arrow keys also work on the edge. nexxus remembers the width for your account, on every device.
- **Open it as a full page** with <Ui>Open as full page</Ui> in the column header. That takes you to <MenuPath to="AI > Work with AI > AI sessions" /> with the same conversation, more room and the list of all your conversations.
- **Other ways in:** the dashboard widget <Ui>Ask the assistant</Ui> sends a question straight to the column. Documents in Files have their own button for the AI Assistant, and a conversation started there belongs to that document. On <MenuPath to="AI > Set up AI > Avatars" />, <Ui>Start conversation</Ui> opens the column with one of your company's avatars, for example Mara. On many record pages, [AI buttons](#ai-buttons-on-record-pages) start a conversation with a prepared request.

The first time you open the AI Assistant, a short tour appears: <Ui>Welcome to nexxus</Ui> (with your installation's name) explains what it can do and how to work with it. <Ui>Let's go</Ui> closes it for good.

<Screenshot src={shot_ai_assistant_welcome} url="/partner/customers" alt={"The welcome tour the first time the AI Assistant opens"} caption={"It appears once per person."} />

### On the dashboard

On the dashboard, the AI Assistant sits as a figure in the tile <Ui>Ask the assistant</Ui>. Click it to open the column. Beside it, the tile lists what is waiting for you, the most pressing first:

- **Questions:** a conversation in which the AI Assistant asks you something (<Ui>Question</Ui>), or a task on the desk whose avatar needs you (<Ui>Question</Ui> or <Ui>Needs you</Ui>).
- **What is new:** an unread answer in one of your conversations (<Ui>New answer</Ui>), an avatar's result on the desk (<Ui>To review</Ui>) and unread notifications (<Ui>Notification</Ui>), newest first.
- **What is open:** your tasks on the desk (<Ui>Task</Ui>, with the due date) and follow-ups that are due (<Ui>Follow-up</Ui>), in the order of the desk.

Ask the AI Assistant "What is waiting for me?" in any chat and it answers with the same entries.

The heading names the most pressing kind: <Ui>AI Assistant is waiting for you</Ui>, <Ui>New for you</Ui> or <Ui>Open for you</Ui>. A click opens the entry where you deal with it. A notification counts as read once you open it, as in the bell; one without a page of its own opens <Ui>Notifications</Ui>, where its buttons are. The figure shows what is going on:

- **It waves** when a question or something new is waiting.
- **It works** while one of its conversations is answering. Hover over it and it says <Ui>AI Assistant is working</Ui>.
- **It sleeps** outside your working hours, unless something is waiting. It knows them if you named them when it got to know you at the desk (see [The AI Assistant at the desk](/use/dashboard/#the-ai-assistant-at-the-desk)). Without them, it never sleeps.

{/* SHOT: ai-assistant-dashboard */}

## The AI Assistant knows where you are

You never have to explain which page you are looking at. The column header says what the AI Assistant sees of it, on the dashboard for example <Ui>Sees: Start page</Ui>. The page goes along with every message, also when you move to another page in the middle of a conversation. Many pages tell it more:

- **A list** passes on what it shows: the kind of records, your active filters and search, and how many rows match. "Of these, which have no contact person?" then refers to exactly the rows you see.
- **A record** you opened passes on which one it is, often with its key data, so the AI Assistant does not have to look it up first.
- **A part of a page** can be in focus, for example one slide of a presentation or one block in an app. It shows up as a chip above the input field and goes along with every message. Click the chip's <Ui>Do not send this reference</Ui> button to leave it out.

<Ui>Hide</Ui> switches this off. The line then says <Ui>Does not see the page</Ui>, and your messages go out without the page until you click <Ui>Show page</Ui>. nexxus remembers the choice for your account, on every device. A part in focus has its own button on the chip. Conversations with an avatar or about a document bring their own context and do not have this line.

When you start a conversation on a page, it is titled after that page.

## Show the AI Assistant part of the screen

Sometimes words are not enough: a number looks wrong, a field is empty, a chart is confusing. With <Ui>Show</Ui> you mark the spot and ask about it.

<Steps>

1. Click <Ui>Show</Ui> in the input area, or press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (on a Mac <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd>) on any page.

2. Your browser asks whether nexxus may capture this tab. Allow it. nexxus takes a single picture of the tab and stops capturing right away.

3. The picture freezes on screen. Mark what you mean: drag a <Ui>Frame</Ui>, draw <Ui>Freehand</Ui> around it, click an <Ui>Element</Ui>, or take the <Ui>Whole page</Ui>.

4. Type your question, or pick one of the suggestions: <Ui>What is this?</Ui>, <Ui>Why is something missing here?</Ui>, <Ui>Explain this to me</Ui>.

</Steps>

{/* SHOT: ai-assistant-show */}

The AI Assistant receives the marked part as an image, plus the page's address and the text under your marking. If the selected model cannot see images, it gets the text and the structure of that part only (<Ui>Selection, as text only</Ui>). The content of input fields and of the AI Assistant's own column never goes along.

## Write, attach, mention

The input area works the same in the column and on <Ui>AI sessions</Ui>.

- <kbd>Enter</kbd> sends, <kbd>Shift</kbd> + <kbd>Enter</kbd> starts a new line.
- **Attach files** with the <Ui>+</Ui> button: <Ui>File from this computer</Ui> or <Ui>One of your files</Ui>. When your tenant works with folders, you pick single files or whole folders there, sub-folders included, up to 100 files. You can also drop files onto the column or paste an image.
- **Type `/`** to pick a skill: a prepared way of working that your company has stored, for example for offers or meeting minutes.
- **Type `@`** to pick a connector, for example a connected CRM. The <Ui>+</Ui> button also has an entry <Ui>Connectors</Ui> with the number of active ones. It opens the <Ui>Connectors of this conversation</Ui>, where you switch them on or off for this conversation. Below the input area, <Ui>Connect accounts</Ui> shows the integrations that still wait for your own account.
- **Speak** instead of typing. A short click on the microphone dictates into the input field, and you send the text yourself. Hold the microphone down to record a voice message (tooltip <Ui>Voice input (hold for a voice message)</Ui>). It goes out the moment you let go and shows in the conversation with "Voice message · 0:14" (with the real length). See [Voice](/setup/voice/#send-a-voice-message).

<Screenshot src={shot_ai_assistant_composer} url="/partner/customers" alt={"The input area with the attach and connector menu"} caption={"Type / for a skill and @ for a connector."} />

Files you attach and files the AI Assistant creates are stored in your Files, in the folder "KI-Sessions" with one sub-folder per conversation. Files the AI Assistant produces (documents, tables, images) go into its sub-folder "Ergebnisse" (results) and show up as chips under the answer.

## Choose a model

The model button in the input area opens the list of models your admin has published. Each has a name your company chose and a short description.

<Screenshot src={shot_ai_model_picker} url="/partner/customers" alt={"The model picker with the usage cost of a model"} caption={"Admins also see active models that are not published yet."} />

- <Ui>Recommended</Ui> marks the model a new conversation starts with, unless you picked another one before. Your choice applies to this conversation and the next ones (<Ui>Which model answers. The choice applies to this conversation and the next ones.</Ui>).
- Hover a model to see its description and its <Ui>Usage cost</Ui>, from <Ui>Low</Ui> to <Ui>Very high</Ui>, calculated from the prices your admin entered. Prefer a cheaper model for simple questions.
- A warning sign means <Ui>Weak model, poor at using tools</Ui>. Such a model answers, but it struggles with tasks that need several steps.
- If you attach an image and the selected model cannot see images, the AI Assistant tells you and offers a model that can.

## AI buttons on record pages

Some requests come up again for every customer and every invoice: a briefing before a meeting, a payment reminder, a summary. An AI button puts a skill for this on the record's page. A click opens the request, already filled in from the record. You read it, change it if needed and send it.

Before a phone call, Mia opens Nordwind AG and clicks <Ui>Briefing</Ui> in the page header. The window already holds the request with the customer's name. She adds "mainly the open invoices" and clicks <Ui>Send</Ui>. The answer comes in the column on the right, in a new conversation with Mara.

### Where the buttons are

AI buttons sit in the header of a partner's, an invoice's and a document's page in Files, and on the record pages of package modules. Up to two buttons show directly. If there are more, the first two stay visible and the rest go into the menu <Ui>More</Ui>. When an avatar leads the conversation, the button carries its sign. Hover over a button to see the skill's description.

You only see a button if you can see its skill: the skill is active, not archived, and you may read it. A personal skill therefore shows its buttons only to the person it belongs to. On a package module's page, the package must also be installed and active, and you need the right to read that kind of record. If you may not see a button's avatar, or the avatar is archived or switched off, the button stays and the AI Assistant itself leads the conversation.

### The request window

A click on an AI button opens a window titled with the button's label:

- **Who answers:** the avatar with its name and role, or the AI Assistant itself.
- **The skill** on a card, with its name, its description and a line naming the record, for example <Ui>About Partner “Nordwind AG”</Ui>.
- **The request** in the input field, pre-filled from the record. You can change, shorten or extend it freely. <kbd>Enter</kbd> sends, <kbd>Shift</kbd> + <kbd>Enter</kbd> starts a new line.
- **Attachments, microphone and model:** the paperclip (<Ui>Attach</Ui>) attaches files. The microphone and the model button work as in the column's input area. If the avatar has its own model, it is already selected.

<Ui>Send</Ui> sends the request, <Ui>Cancel</Ui> closes the window without sending anything.

A button set to <Ui>Send directly</Ui> opens no window: it fills in the request from the record and sends it at once.

{/* SHOT: ai-buttons-popup */}

After sending, the window closes and the AI Assistant's column opens on the right with a new conversation, led by the button's avatar. The conversation is named after the button and the record, for example "Briefing: Nordwind AG", and the AI Assistant knows which record it is about. The conversation that was open in the column before is still on <Ui>AI sessions</Ui>.

### Create AI buttons

AI buttons belong to a skill and are created in the skill editor, on <MenuPath to="AI > Work with AI > Skill Management" />. Whoever may change the skill may create and change its buttons.

<Steps>

1. Open the skill and go to the section <Ui>AI buttons</Ui>.

2. Click <Ui>Add button</Ui>. Next to it you see how many buttons the skill already has. A skill carries at most 10.

3. Under <Ui>Page</Ui>, choose where the button goes. <Ui>General</Ui> lists <Ui>Partner</Ui>, <Ui>Document</Ui> and <Ui>Invoice</Ui>, followed by the record types of the package modules you may read.

4. Enter a <Ui>Label</Ui>, for example "Summarise", with at most 80 characters.

5. Under <Ui>Avatar</Ui>, choose who leads the conversation. Without a choice of your own, the <Ui>House assistant</Ui> takes it, that is the AI Assistant itself.

6. Turn on <Ui>Send directly</Ui> when the request is fixed and nobody adds anything before sending. A click on the button then sends it to the AI Assistant at once, without the window first.

7. Write the <Ui>Request</Ui>, with at most 2000 characters. The buttons after <Ui>Insert placeholder:</Ui> add placeholders that are filled from the record on click: `{{title}}` is its title, `{{record.field}}` one of its fields. For package modules, the fields of the chosen record type are listed there.

8. Put the buttons in order with <Ui>Move up</Ui> and <Ui>Move down</Ui>. The first two show directly on the page, the rest under <Ui>More</Ui>.

9. Click <Ui>Save</Ui>. The buttons are saved with the skill, the bar counts them as changes, and <Ui>Last saved</Ui> then shows the new time.

</Steps>

{/* SHOT: ai-buttons-editor */}

nexxus refuses any other placeholder on save, so a typo like `{{titel}}` does not end up literally in the request. If the record has no value for a field, the placeholder is simply left out when the window opens.

In two cases the editor shows the buttons read-only:

- **The skill comes from a package module.** The package then brings its buttons, at most three per skill, and every package update rewrites them. The editor names the package.
- **You may only read the skill.** Then the same goes for its buttons.

### Skills without a button

A skill does not need a button. In any conversation you pick it with `/` (see [Write, attach, mention](#write-attach-mention)). Ask the AI Assistant about a skill, and it looks the skill up and also names the pages where it sits as a button. It cannot change buttons, that only happens in the skill editor.

## Hand over instead of waiting

The AI Assistant is not a chatbot that answers in a second. For a real task it searches, reads, checks and calls tools, and that can take a few minutes. You do not have to watch:

- Move on to other pages. The column keeps working.
- While the AI Assistant works, the answer shows <Ui>Working</Ui>, the number of tools and helpers it uses, and a line with the current step. If something takes unusually long, a note says so and that the reason for any failure will appear there.
- The AI Assistant can split a task among several **helpers** that work in parallel. They show up in the same line.
- When an answer finishes while you are elsewhere, the menu entry <Ui>AI sessions</Ui> gets a badge. If you allow it, your browser also shows a notification.
- <Ui>Stop</Ui> ends the current answer.

An answer that runs longer than 30 minutes loses its live connection. The AI Assistant keeps working, and the answer appears when you reload the conversation. Split very large tasks into smaller steps.

## Read an answer

An answer is more than text. From top to bottom you may find:

| Part | What it tells you |
|---|---|
| The run line | <Ui>Working</Ui> or <Ui>Done</Ui>, how many tools and helpers were used, how many failed. Click it to see each tool call with its <Ui>Input</Ui> and <Ui>Result</Ui>. |
| Thoughts | What the model considered on the way, set apart from the answer. |
| The answer | Text, tables (sortable), lists, sometimes a form that asks you for details. |
| <Ui>Sources</Ui> | What the answer is based on. See below. |
| Cards | Changes for you to approve, questions about external services, connector suggestions. See [The AI Assistant proposes, you approve](#the-ai-assistant-proposes-you-approve). |
| Chips | Files the AI Assistant created, skills it used, pages it opened for you, things it noted about you. |
| Actions | <Ui>Copy</Ui>, <Ui>Read aloud</Ui>, <Ui>Add to knowledge</Ui>. |

<Screenshot src={shot_ai_answer_sources} url="/dashboard" alt={"An answer with its sources"} caption={"Sources come from what the AI Assistant actually fetched, not from the model's claims."} />

### Sources

nexxus takes the sources from what the AI Assistant actually did in this answer, not from what the model claims. A source appears only if a tool really fetched it.

| Source | Meaning |
|---|---|
| <Ui>Knowledge</Ui> | An entry from your company knowledge. Click it to open the entry. |
| <Ui>Document</Ui> | A file in Files, or a section of it. Click it to open the document. |
| <Ui>Earlier session</Ui> | One of your earlier conversations that the AI Assistant recalled. Click it to open the conversation. |
| <Ui>Web</Ui> | A web page, if web search is on. Click it to open the page. |
| <Ui>Connector</Ui> | A connected system the AI Assistant asked, for example your CRM. |
| <Ui>System data</Ui> | Records from nexxus itself that the answer was computed from. |
| <Ui>General knowledge</Ui> | No source from your system: the answer comes from what the model knows and has not been checked. |

The AI Assistant often searches more than it uses. Sources the answer actually takes up stand in the row. What was only searched hides behind a quiet "5 searched" (with the real number); click it to see <Ui>Only searched, not used in the answer:</Ui>. When an answer has no source at all, treat <Ui>General knowledge</Ui> as a hint to check the answer yourself.

## The AI Assistant proposes, you approve

The AI Assistant never writes to the database on its own. Whenever an answer would change something in nexxus, it prepares the change, the server checks it, and you decide.

<Flow
  steps={[
    { icon: 'message-square-text', title: 'You ask', text: 'Create a follow-up task for each of these customers.' },
    { icon: 'sparkles', title: 'The AI Assistant prepares', text: 'It finds the data and builds the change.', tone: 'lavender' },
    { icon: 'shield-check', title: 'The server checks', text: 'Input, current state of the record and your rights.', tone: 'cyan' },
    { icon: 'circle-check-big', title: 'You click', text: 'Only then is the change carried out, as you.' },
  ]}
  caption="On execution the server runs every check again. A card that was checked earlier is a preview, never a permit."
/>

### A single change

The headline names the change and the kind of record, for example <Ui>Create PartnerContact</Ui>, with the technical key of the action below it (here `partnerContact.create`). Then come the fields the AI Assistant wants to set, by their technical names, and three checks:

- <Ui>Input valid</Ui>: the values fit the fields.
- <Ui>Record in the right state</Ui>: the record allows the change right now, and every record it points to, such as the customer of a new project, exists and is visible to you.
- <Ui>Permission granted</Ui>: you may make this change.

When all three pass, they shrink to three green chips, <Ui>Input</Ui>, <Ui>State</Ui> and <Ui>Permission</Ui>, and the button <Ui>Execute</Ui> appears. Until you click it, as the card says, <Ui>Nothing happens until you click.</Ui>

If a check fails, the card spells out which one and why. A missing required field, for example, reads "Pflichtfelder fehlen für partnerContact.create: email. Ohne sie lässt sich der Datensatz nicht anlegen." (required fields are missing; the server writes this in German). The other checks then say they were not run, and instead of the button the card says <Ui>Cannot be executed while a check fails.</Ui> Usually the AI Assistant corrects this itself: it looks up what is missing or adds the step before, checks again and proposes a new card. The red one then disappears from the answer. If it needs something only you know, such as the missing e-mail address, it asks exactly that. If a card stays red, <Ui>Try to fix it</Ui> sends it the messages, so you do not have to type them.

<Screenshot src={shot_ai_action_card} url="/ai/sessions" alt={"A single change proposed by the AI Assistant, waiting for approval"} caption={"The server checks input, state and your rights before you can execute."} />

Changes in a package module come on the same card. Their key names the module first, for example `curiaos.kanzlei:frist.update`, and an open page of the package shows the change right after your click, without a reload.

### Several changes at once

Some tasks need several steps that depend on each other, for example "create the customer and right away a project for it". The AI Assistant puts them on one card: <Ui>2 steps, one confirmation</Ui> (with the real number) and a button <Ui>Execute all 2</Ui>. A field that takes its value from an earlier step says so, for example "partnerId from step 1". The checks of such a step cannot run before the earlier step exists, so they read "Wird erst nach Schritt 1 prüfbar." (can only be checked after step 1). nexxus runs them when you execute. The steps run in one go: <Ui>If a step fails, the earlier ones are rolled back too.</Ui> You never end up with half of it.

<Screenshot src={shot_ai_action_bundle} url="/ai/sessions" alt={"Two dependent changes on one card"} caption={"All steps run in one go or none does."} />

When a step creates a record for which the package works out an amount in advance, a billable service for example, the amount shows in its row and the <Ui>Total</Ui> below the steps.

Every row starts with a checkbox that deselects the step. The button then reads <Ui>Execute 2 of 3</Ui>, for example, and the total counts only the selected ones (<Ui>Total of the 2 selected</Ui>). Steps that build on a deselected one are deselected with it. Select it again and they come back too. A step with a failed check holds up the whole card until you deselect it, then the rest can be executed. After executing, a deselected row says <Ui>Deselected, not executed</Ui>, and the AI Assistant learns which steps you turned down.

### After you execute

Once a card is executed, it shows what was created or changed. Under <Ui>Executed</Ui> or <Ui>All 2 steps executed</Ui>, every record gets a small card with its kind and name. For the example above, one says <Ui>Partner</Ui> and one <Ui>Project</Ui>. A click opens the record. Kinds without a page of their own show the card without a link. What it says comes from the server's answer, not from the AI Assistant's text, and it is back after you reload the conversation. Tools that write without a card, for example when the AI Assistant creates a folder or an app, put the same cards under the answer.

### Changes to documents

When the AI Assistant edits a document in Files, every change becomes a new version. The answer shows a card from the version history with what was added, changed and removed, a button to <Ui>Compare</Ui> and one to undo back to the previous version.

### Actions in other systems

Connectors can let the AI Assistant act in other systems, for example create a ticket or send a message. Actions that can change something there need your confirmation each time, on a card <Ui>Confirm action</Ui>: "Run ... in ...? The action can change something there." Click <Ui>Confirm</Ui> or <Ui>Decline</Ui>. A confirmation lets exactly that one call through, with exactly those values. A question nobody answers expires after 24 hours.

{/* SHOT: ai-plugin-confirm */}

If a connector needs your own account at the other system, the AI Assistant shows <Ui>Connect to ...</Ui> with the connector's name (<Ui>The assistant needs your account to go on.</Ui>).

### Data that leaves for an external service

Some tools send data to a service outside your installation, for example image generation. Before the first use in a conversation, the AI Assistant pauses and asks: <Ui>Allow external service?</Ui> The text says what goes where. Click <Ui>Agree</Ui> to continue or <Ui>Cancel</Ui> to keep the data in. Your answer counts for the rest of that conversation.

<Screenshot src={shot_ai_consent_dialog} url="/dashboard" alt={"The AI Assistant asks before data goes to an external service"} caption={"The answer counts for the rest of the conversation."} />

## What the AI Assistant may do

The AI Assistant acts with your rights, checked by the server on every single step. The prompt has no say in it.

- **Records:** The AI Assistant sees and changes only what you could see and change on the screens yourself. Every change runs the same checks as the form you would otherwise use.
- **Files:** It finds content only in files you may at least view. nexxus checks this per file, on every search.
- **Knowledge:** It finds entries that are visible to you: your personal ones, those of your business unit and those for the whole company.
- **Connectors:** It can use the connectors your admin has installed, and only those switched on in the conversation.
- **Companies:** It looks up customers, suppliers and your own companies, but only those you would also see in a company picker. When you name a person, a company or a project it does not know, it asks who or what that is. It creates new contact persons and companies only through a card that you confirm.
- **No direct database queries:** It reads records through the same checks as the pages, never past them.
- **Earlier conversations:** It recalls only your own conversations, never anyone else's.

Admins can see every change the AI Assistant is able to make on <MenuPath to="AI > Work with AI > AI actions" />. The list is read from the running application, not maintained by hand, and the AI Assistant gets the same list, filtered by the same rights.

## Ask the AI Assistant by email

Some questions you ask the same way every week, such as the hours booked per project. If your administrator has set up a mailbox for it, send the question by email to that mailbox. The AI Assistant works on it with your rights and sends the answer back by mail, with reports and tables attached. Your administrator tells you the address. How they set up the mailbox is described in [Connect mailboxes](/setup/mailboxes/).

<Flow
  steps={[
    { icon: 'mail', title: 'You write', text: 'From the address of your nexxus account to the mailbox.' },
    { icon: 'shield-check', title: 'nexxus checks', text: 'Genuine sender, exactly one person, hourly limit.', tone: 'cyan' },
    { icon: 'sparkles', title: 'The AI Assistant works', text: 'In a new session, with your rights, read-only.', tone: 'lavender' },
    { icon: 'reply', title: 'The answer arrives', text: 'As a mail to you, files attached.' },
  ]}
  caption="A mail that fails a check gets no answer. Your administrator sees the reason at the mailbox."
/>

### Who gets an answer

Before the AI Assistant reads a mail, nexxus checks the sender:

- **The mail really comes from that address.** nexxus checks the DKIM signature itself, and it must belong to the domain of the sender address. For a mailbox in Microsoft 365, mail from your own organisation also passes when Exchange Online has marked it as internal.
- **The address belongs to exactly one person.** It must be the email address of an account in your tenant whose invitation has been accepted. Service accounts and deleted accounts do not count. If several accounts share the address, the AI Assistant answers none of them.
- **The hourly limit is not reached.** Per person, a mailbox accepts only as many requests within 60 minutes as your administrator set under <Ui>Requests per person and hour</Ui>. The default is 5.

If a mail fails a check, the AI Assistant does not read it and you get no answer, not even an error message. That way nobody who only pretends to be you gets an answer. Automatic mails such as out-of-office notes, newsletters or mails from noreply addresses are skipped without a check. If an AI schedule handles the mail, the AI Assistant does not answer it itself.

### What the AI Assistant does with your mail

- Every mail gets **its own session**, titled „E-Mail:“ followed by your subject. It belongs to you and is listed on <MenuPath to="AI > Work with AI > AI sessions" />. Attachments of your mail are files of the session, as if you had uploaded them in the chat.
- The AI Assistant works **read-only**. If data needs to change, it prepares the change and says in one sentence what it prepared. The change runs only once you confirm it in the session.
- **It cannot ask back.** It makes assumptions and names them in the answer. So say right away which period, which project and which format you mean.
- Quoted or forwarded parts of your mail are material to it, not instructions.
- It has **15 minutes**. Your reply to its mail is a new request with a new session.

### The answer

The answer goes to the address you wrote from, with the subject "Re:" and your subject. Tables and lists are formatted. The mail is in German. Below the answer it lists what belongs to it:

- „Im Anhang:“ (attached) and the files the AI Assistant created. Up to 15 MB in total go with the mail. What no longer fits is listed under „Zu groß für diese Mail, deshalb nur in der Session:“ (too large for this mail, so only in the session).
- „Bitte in der App bestätigen:“ (please confirm in the app) when a change is prepared.
- The link „Session in Nexxus öffnen“ (open the session in nexxus), where you continue the conversation.

If the AI Assistant could not answer because time ran out, too much was running at once or an error occurred, you get this instead: „Ihre Anfrage konnte der Assistent leider nicht beantworten. Bitte versuchen Sie es später noch einmal oder öffnen Sie die Session in Nexxus.“ (the assistant could not answer your request; try again later or open the session).

### For administrators: what became of each mail

Open <MenuPath to="Administration > Content & automation > Mailboxes" /> and the mailbox. Under <Ui>Received mails</Ui>, every mail that arrived while <Ui>Assistant answers mails</Ui> was on carries a tag with its state. Clicking the row shows <Ui>AI assistant</Ui> with state and reason, and below it a line such as „Keine Person mit der Adresse ...“ (no person with this address) or „Schon 5 Anfragen in der letzten Stunde (Grenze 5).“ (already 5 requests in the last hour, limit 5).

| State | Meaning |
|---|---|
| <Ui>Skipped</Ui> | An automatic mail: <Ui>automatic mail (Auto-Submitted)</Ui>, <Ui>bulk mail (Precedence)</Ui>, <Ui>mailing list (List-Id)</Ui>, <Ui>sender is automated (noreply, bounce)</Ui> or <Ui>our own sender address</Ui>. |
| <Ui>Rejected</Ui> | A check failed: <Ui>no single sender</Ui>, <Ui>no DKIM signature</Ui>, <Ui>DKIM signature invalid</Ui>, <Ui>DKIM signature of another domain</Ui>, <Ui>DKIM signature could not be checked</Ui>, <Ui>unknown sender</Ui>, <Ui>address belongs to several people</Ui>, <Ui>person not active</Ui> or <Ui>hourly limit reached</Ui>. No answer goes out. |
| <Ui>Schedule</Ui> | <Ui>handled by a schedule</Ui>. The AI Assistant does not answer. |
| <Ui>Queued</Ui>, <Ui>Running</Ui> | The run is waiting in the queue or running. |
| <Ui>Answered</Ui> | The answer has been sent. With <Ui>a change awaits confirmation in the app</Ui>, the AI Assistant prepared a change. |
| <Ui>Failed</Ui> | <Ui>queue full</Ui>, <Ui>time limit exceeded</Ui>, <Ui>run failed</Ui> or <Ui>run interrupted (restart)</Ui>. The person gets a short mail saying their request could not be answered, unless they can no longer sign in. |

The answers sent are listed on <MenuPath to="Administration > Operations > Maintenance > Email delivery" />, visible to administrators only.

## Model and cost per answer

**Admins** see a line under every finished answer in the AI Assistant's column: duration, number of tool calls, cost and model. Click it for the tokens and the cost in detail (<Ui>Numbers of this answer (admins only)</Ui>). The cost appears in euros when your admin has set an exchange rate, otherwise in dollars. If no price is set for the model, the line says <Ui>no price</Ui>.

**Everyone else** does not see this line. You see the <Ui>Usage cost</Ui> scale in the model picker, which tells you how expensive a model is compared with others.

<Screenshot src={shot_ai_answer_meta} url="/dashboard" alt={"The cost and model line under an answer, expanded"} caption={"Only admins see this line. Without a price for the model it says so instead of an amount."} />

How admins set prices and read the totals is described in [Connect your AI](/setup/connect-ai/#costs).

## Your conversations

Every conversation is saved, with all its answers, files and decisions.

- **In the column**, the title in the header is a button: <Ui>Conversations</Ui> opens your recent conversations with a search field (<Ui>Search conversations</Ui>). The pencil icon starts a <Ui>New conversation</Ui>.
- **On <MenuPath to="AI > Work with AI > AI sessions" />** you see all of them, with a button <Ui>New session</Ui> and a search over titles and recaps, grouped by <Ui>Today</Ui>, <Ui>Yesterday</Ui>, <Ui>Last 7 days</Ui> and <Ui>Older</Ui>, with filters <Ui>All</Ui>, <Ui>Relevant</Ui>, <Ui>Waiting</Ui> (the AI Assistant waits for your answer), <Ui>Schedules</Ui>, <Ui>Shared</Ui> and <Ui>Archive</Ui>. Each conversation has a menu to <Ui>Rename</Ui>, <Ui>Generate title</Ui>, <Ui>Mark as relevant</Ui>, <Ui>Archive</Ui> or <Ui>Delete</Ui>. A side panel <Ui>History</Ui> shows the timeline of the conversation: messages, tools, files and actions.

<Screenshot src={shot_ai_sessions_page} url="/ai/sessions" alt={"AI sessions with the conversation list and the history panel"} caption={"Every conversation is saved with its answers, files and decisions."} />

### One conversation, in chapters

The column does not start empty on every visit. When you open it, it shows your last conversation with the AI Assistant, as long as its last message is less than four hours old and you have not signed out in between. After that, your next message starts a new chapter. The pencil icon starts a new chapter right away.

While a new chapter is still empty, the last three earlier ones are folded below it under <Ui>Earlier chapters</Ui>, each with its title, time and summary (or <Ui>No summary yet.</Ui>). <Ui>Continue there</Ui> makes an earlier chapter the current conversation again. Every chapter is an ordinary conversation and is also listed on <Ui>AI sessions</Ui>.

This applies to the general conversation with the AI Assistant, not to conversations with an avatar, about a document or from a schedule. Which chapter is current is remembered by your browser, so on another device the column starts with a new chapter.

Who can see your conversations: you, and the people you share a conversation with (see below). Admins can open them read-only, and conversations behind a schedule can be read by whoever may read that schedule. Nobody else can write in your conversation, not even an admin. When you look at a conversation you cannot write in, a note says so, for example <Ui>Read only: conversation of ...</Ui> with the owner's name.

:::note[The files stay]
Deleting a conversation keeps its files: in your Files under <Ui>System</Ui> › "KI-Sessions", in the conversation's folder. The dialog lists them before you confirm. From there you can move them into a folder of your own.
:::

### Continue a long conversation in a new session

A model keeps only a limited amount of text in view at a time. When a conversation gets very long, for example with many files, the AI Assistant summarizes older parts, and details get lost. Before that happens, nexxus offers to continue in a new session that starts with a handover.

On <MenuPath to="AI > Work > My sessions" />, a note appears above the conversation once it is 80 % full, for example <Ui>This session is 85 % full. Soon the assistant summarizes older parts, and details get lost.</Ui> If the AI Assistant has summarized already, it reads <Ui>This session has been summarized already. The assistant knows older details only in short.</Ui> The note appears only in your own conversations, not in those of a schedule and not in the column. The cross (<Ui>Hide notice</Ui>) hides it until you open the page again.

<Steps>

1. Click <Ui>Continue in a new session</Ui> in the note. The AI Assistant writes a handover from the conversation: what it is about and where the work stands. This takes a moment.

2. Read the <Ui>Handover</Ui> and change it where needed. Below it you see the <Ui>Files that come along</Ui> and, if you worked with skills, the <Ui>Skills that come along</Ui>.

3. Click <Ui>Start new session</Ui>. <Ui>Cancel</Ui> creates nothing.

</Steps>

The new session keeps the old title with "(Fortsetzung)" (continuation) added and opens right away. Its first message is the handover, and the AI Assistant answers it. It works with the same avatar and model, your choice of connectors and the skills from the dialog. The files are the same as in the old session, not copies. The old session stays as it was and shows <Ui>This session goes on in a new one.</Ui> with the button <Ui>Open the new session</Ui>.

If the AI Assistant cannot write the handover right now, nexxus puts it together from the conversation, and the dialog says so: <Ui>The handover was put together from the conversation without AI. Please check and complete it.</Ui>

### Share a conversation

A conversation is often the record of work that others should see too, such as an offer you checked or the summary of a document. Instead of sending screenshots, you share the conversation. Whoever gets it can read it and continue it as their own copy. Only you keep writing in your conversation.

<Steps>

1. Open the conversation on <MenuPath to="AI > Work with AI > AI sessions" /> and click the <Ui>Share</Ui> icon in the bar above the conversation. It appears only in your own conversations, not in those of a schedule.

2. Under <Ui>People and business units</Ui>, choose whom to share with: <Ui>Person</Ui>, <Ui>Business unit</Ui> (with its sub-units) or <Ui>Whole company</Ui>. Pick the person or unit and click <Ui>Share</Ui>. The share then appears below, with the right <Ui>Read and continue as a copy</Ui>.

</Steps>

Someone who gets a conversation personally sees it in the bell and gets an e-mail. Both can be switched off under <MenuPath to="My profile > Notifications" />, section <Ui>AI chats: shared</Ui>. Shares with a business unit or the whole company send no notification.

**What the recipients see.** The conversation is on <MenuPath to="AI > Work with AI > AI sessions" /> in the group <Ui>Shared with me</Ui> and under the filter <Ui>Shared</Ui>. It opens read-only, with the note <Ui>Shared with you by ...</Ui> showing your name. Recipients see the whole conversation, but of tool steps only the name and the outcome, not the data, and files by name only. Only people who may use the AI Assistant themselves can open that page. Anyone else can reach the conversation through a public link only.

**Continue as my own copy.** With <Ui>Continue as my own copy</Ui> in the note or in the conversation's menu, a recipient starts a conversation of their own with everything said so far. It keeps the original's title with "(Kopie)" (copy) added. Files are not copied. In the copy, the AI Assistant works with the recipient's rights, not with yours.

**Take a share back.** The cross next to a share (<Ui>Remove share</Ui>) removes it after a confirmation. The person no longer sees the conversation. Copies they already made stay.

### Create a public link

A link opens the conversation for people without an account in nexxus too. You create it in the same dialog, under <Ui>Public link</Ui>.

<Steps>

1. <Ui>Valid until</Ui> is set to 30 days from today. Pick another day if the link should end sooner or later. It is valid until the end of that day.

2. A <Ui>Password</Ui> is optional. If you set one, everyone who opens the link has to enter it.

3. Switch on <Ui>Signed-in people only</Ui> if only people signed in to nexxus should open the link.

4. Click <Ui>Create link</Ui>. The link appears below. <Ui>Copy link</Ui> puts it on the clipboard.

</Steps>

Under each link you see until when it is valid, whether it has a password and how often it was opened. <Ui>Revoke link</Ui> blocks it at once, after a confirmation.

Whoever opens the link sees the conversation under <Ui>Shared chat</Ui>, read-only and with the same note about tool steps and files. People who are signed in can take it over with <Ui>Continue as my own copy</Ui>. Without signing in, the button reads <Ui>Sign in to continue</Ui> and brings them back to the conversation after signing in.

:::caution[Anyone with the link can read along]
A link without a password and without <Ui>Signed-in people only</Ui> opens the conversation for anyone who has it. Only pass it on where that is fine, and revoke it when it is no longer needed.
:::

## What the AI Assistant remembers

- **Notes about you.** When you tell the AI Assistant something lasting ("I work Monday to Thursday"), it may note it. The answer shows <Ui>Noted: ...</Ui> with an <Ui>Undo</Ui> button. All notes are on your <Ui>Desk</Ui>, in the notebook <Ui>What AI Assistant knows about you</Ui>. Only you see it. Each note can be removed with <Ui>Forget</Ui>, and <Ui>Export everything</Ui> and <Ui>Forget everything</Ui> work on all of them. When the AI Assistant is no longer sure about a note, it asks, and you answer <Ui>Yes, still true</Ui> or <Ui>Not anymore</Ui>.
- **Company knowledge.** An answer worth keeping can become a knowledge entry: click <Ui>Add to knowledge</Ui> under the answer, give it a <Ui>Title</Ui>, check the <Ui>Content (Markdown)</Ui> and choose the <Ui>Visibility</Ui>: <Ui>Personal</Ui> (only you), <Ui>Business unit</Ui> (your unit and its sub-units) or <Ui>Company</Ui> (everyone). After a long task the AI Assistant offers it by itself (<Ui>Add to knowledge?</Ui>).
- **Avatars.** Your company can set up avatars: AI colleagues with their own field, their own way of working and their own memory of your conversations with them. The AI Assistant itself is the house avatar that everyone talks to by default.

## Your own AI Assistant

You decide yourself what the AI Assistant is called and how it looks for you: under <Ui>My profile</Ui>, tab <Ui>Your Ava</Ui> (with your installation's name). Only you see it this way, and what it knows about you stays the same. Everyone who may use the AI Assistant has this tab.

- <Ui>What should she be called?</Ui> takes a name of your own, up to 20 characters. In conversation, the AI Assistant answers to this name and introduces itself to you with it. For everyone else it keeps your installation's name. Clear the field to go back to that.
- <Ui>Colour</Ui>: <Ui>As for everyone</Ui> (your installation's colour), <Ui>Mint</Ui>, <Ui>Coral</Ui>, <Ui>Sun</Ui>, <Ui>Ocean</Ui>, <Ui>Lavender</Ui>, <Ui>Forest</Ui> or <Ui>Slate</Ui>.
- <Ui>Shape</Ui>: <Ui>Ball</Ui>, <Ui>Drop</Ui>, <Ui>Pebble</Ui>, <Ui>Mochi</Ui>, <Ui>Cushion</Ui>, <Ui>Sprout</Ui>, <Ui>Classic</Ui> (with arms) or <Ui>Spark</Ui> (a sparkle sign without a face).
- <Ui>Style</Ui>: <Ui>Soft</Ui>, <Ui>Comic</Ui>, <Ui>Sticker</Ui> or <Ui>Plain</Ui>.
- <Ui>Eyes</Ui>: <Ui>Round</Ui>, <Ui>Big</Ui>, <Ui>Sparkly</Ui>, <Ui>Sleepy</Ui>, <Ui>Winking</Ui> or <Ui>Dots</Ui>. With the shape <Ui>Spark</Ui> this choice is missing, because it has no face.

Every choice applies at once; there is no save button. Next to it, a preview shows the AI Assistant large and below that how it shows up everywhere: in the <Ui>Header</Ui>, on the <Ui>Dashboard</Ui>, at the <Ui>Desk</Ui> and in the <Ui>Chat</Ui>. <Ui>As for everyone</Ui> below the choices resets name and look to your installation's defaults. Your choice counts for your account, on every device. The AI Assistant knows the page and opens it for you when you ask about it.

{/* SHOT: ai-assistant-look */}

## Give the assistant your company's name

*For admins.* The AI Assistant does not have to keep its default name. Under <MenuPath to="Administration > Operations > Setup" />, step <Ui>AI</Ui>, the card <Ui>Assistant</Ui> sets how it is called and how it looks.

<Steps>

1. Enter a <Ui>Name</Ui>, up to 40 characters. It appears everywhere: on the button at the top right, in the header of the chat and in the input field. Leave it empty to go back to the default name. People who gave the AI Assistant a name of their own under <Ui>My profile</Ui> keep seeing that one.

2. Choose the <Ui>Appearance</Ui>: <Ui>Dark</Ui> sets the column apart from the rest of the app, <Ui>Light</Ui> blends in.

3. Choose a <Ui>Colour</Ui>: <Ui>Aurora</Ui>, <Ui>Ocean</Ui>, <Ui>Forest</Ui>, <Ui>Sunset</Ui> or <Ui>Graphite</Ui>. Colour and appearance show across the app at once, as a preview.

4. Click <Ui>Apply</Ui>. The message confirms the new name.

</Steps>

<Screenshot src={shot_ai_assistant_settings} url="/einrichtung" alt={"The Assistant card in the setup, where admins rename the assistant"} caption={"Colour and appearance preview at once, the name changes after Apply."} />

## When something goes wrong

| Message | What it means and what to do |
|---|---|
| <Ui>No connection to the assistant. Please send again.</Ui> | nexxus could not reach the assistant. Send the message again. If it keeps happening, tell your admin. |
| <Ui>The connection dropped during the answer. The answer may still finish in the background and then appears after a reload.</Ui> | Wait a moment and reload the conversation. |
| <Ui>The assistant returned nothing and gave no reason. Please send again or choose another model.</Ui> | Send again or switch to another model. |
| A note that the AI provider is not answering, with a retry counter | nexxus retries on its own. If all retries fail, try later or choose a model from another provider. |
| "Die Antwort hat länger als 30 Minuten gedauert ..." (the answer took longer than 30 minutes) | The AI Assistant keeps working. Reload the conversation later. Split large tasks into smaller steps. |
| "... could not be uploaded: the file is too large for the server." | The file exceeds the size limit. Upload a smaller file or a part of it. |
| "... cannot see images. The image is only mentioned as a file." | The selected model is text-only. Switch to a model that sees images. |
| A card says <Ui>Cannot be executed while a check fails.</Ui> | One of the three checks failed. Read which one and click <Ui>Try to fix it</Ui>, or tell the AI Assistant what is missing. If it is <Ui>Permission granted</Ui>, you lack the right for this change. |
| <Ui>Without sharing the tab the assistant cannot see anything. "Show" will ask again next time.</Ui> | You declined the screen capture. Click <Ui>Show</Ui> again and allow it. |
| A colleague cannot find a model you use | You are an admin and use an active model that is not published. Ask the person who manages the AI settings. |
| <Ui>This link has expired.</Ui> | The day under <Ui>Valid until</Ui> has passed. Ask the person who shared the conversation for a new link. |
| <Ui>This link does not exist, or no longer.</Ui> | The link was revoked or not copied completely. Ask for a new one. |
| <Ui>The password is not right.</Ui> | Enter the password again. It is case-sensitive. |
| <Ui>Too many attempts. Please try again in a few minutes.</Ui> | Your address sent 10 wrong passwords within 10 minutes. Wait, then try again. |
| <Ui>This link is for signed-in people only.</Ui> | Click <Ui>Sign in</Ui>. After signing in, the conversation opens. |
| An AI button is missing on a page | Its skill is switched off or archived, it is another person's personal skill, or you lack the right to read that kind of record. Ask whoever maintains the skill. |
| `Platzhalter '{{titel}}' gibt es nicht, ...` (placeholder does not exist) when saving the AI buttons | The request contains a placeholder with a typo. Delete it and add it again with <Ui>Insert placeholder:</Ui>. |
| Your mail to the AI Assistant gets no answer | nexxus rejected the mail, for example because it did not come from the address of your nexxus account or the hourly limit was reached. Your administrator sees the reason at the mailbox under <Ui>Received mails</Ui>. See [Ask the AI Assistant by email](#ask-the-ai-assistant-by-email). |

## Next steps

<CardGrid>
  <LinkCard title="Voice" description="Dictate instead of typing, and have answers read aloud." href="/setup/voice/" />
  <LinkCard title="Search by meaning" description="How the AI Assistant finds knowledge and document content." href="/setup/embeddings/" />
  <LinkCard title="Connect mailboxes" description="Set up a mailbox your people can write to the AI Assistant at." href="/setup/mailboxes/" />
  <LinkCard title="Connectors" description="Connect the systems your company already uses." href="/plugins/overview/" />
</CardGrid>