AI assistants – setting up chat assistants for users and administrators¶
An AI assistant connects nexxcite to a language model. Users chat with it in a form, on a dashboard or in the global search; it can look up records, show them and – for administrators – read and change the configuration. This chapter describes how to create an assistant, what each setting does, which tools it can be given and where its limits are.
It is intended for administrators who set up AI assistants. Which language models can be connected is described in AI providers.
1. AI assistants at a glance¶
| Purpose | A chat with a language model that can use the data and – for administrators – the configuration of nexxcite |
| Typical use | Answering questions about records, summarising a case, finding records; helping administrators to understand and extend the configuration |
| Where | Admin Studio → AI → AI Assistants |
| Related | AI providers, Sketches and publishing, Roles and permissions |
Summary¶
- An assistant names the provider (through credentials), the model, its instructions and the tools it may use.
- Its "Purpose" decides who it serves: "Agent support" for users who work with records, "Administration" for administrators. Only administration assistants can read or change definitions.
- An assistant never does more than the user it works for: every tool is checked against the permissions of that user, and records are read with that user's read restrictions.
- Changes to the configuration go into the user's sketch. They take effect only when a person publishes the sketch.
- An assistant cannot change, create or delete records.
How a chat works¶
- The user sends a message.
- nexxcite sends the instructions, the conversation so far and the descriptions of the tools the assistant may use to the language model.
- The model answers – or asks for a tool, for example "search the records of entity Ticket". nexxcite runs the tool with the permissions of the user and sends the result back to the model.
- Step 3 repeats until the model has its answer, at most "Max Tool Iterations" times.
- The answer appears in the chat while it is being written.
2. Creating an assistant¶
- Set up credentials for the provider in Admin Studio → Access → Credentials – see AI providers.
- Create the assistant in Admin Studio → AI → AI Assistants. An assistant can also be created in the context of an entity (Admin Studio → Entities); this only groups it there.
- Choose "Credentials", enter "Model / Deployment" and the "Purpose".
- Write the instructions as an expression in "Initial Instructions Expression".
- Restrict what it may use: "Enabled Tool Groups", "Searchable Entities", "Stored Query Tags".
- Save, and place the assistant where users need it (section 7).
nexxcite does not test the connection to the provider when you save. Errors appear in the chat with the first message.
3. Settings¶
| Setting | Meaning | Default / Required |
|---|---|---|
| "Credentials" | The connection to the provider: "OpenAI Credentials" or "Anthropic Credentials". The kind decides which interface is used. | Required |
| "Initial Instructions Expression" | An expression that returns the instructions sent with every request: role, tone, rules, what the assistant should and should not do. It is evaluated without a record. | empty – the assistant then only knows its tools |
| "Model / Deployment" | The deployment name for Azure OpenAI, otherwise the model id of the provider, for example gpt-4o or claude-sonnet-4-5. It has to exist at the provider. |
Required |
| "Max Output Tokens" | Upper limit for the length of one answer, in tokens. | empty: 4096 for Anthropic, the provider's own default for OpenAI-style providers |
| "Deactivate AI Assistant" | Takes the assistant offline. Users get the offline message instead of an answer. | off |
| "Offline Message Expression" | The message users get while the assistant is deactivated. | empty: "AI Assistant is currently offline." |
| "Purpose" | "Agent support (works with records)" or "Administration (works with definitions)" (section 4). | "Agent support" |
| "Enabled Tool Groups" | The tool groups the assistant may use (section 4). The tooltip shows which groups it currently gets. | empty = every group the purpose allows |
| "Max Tool Iterations" | How many rounds of tool calls one answer may take. | empty or 0: 10; at most 50 |
| "Show Tool Calls In Chat" | Lists under an answer which tools the assistant used, with duration and arguments. | off |
| "Show Token Usage In Chat" | Shows the tokens an answer used, summed over all requests of that answer. Needs a provider that reports usage. | off |
| "Disable Prompt Caching" | Switches off the caching of tools and instructions at the provider (see AI providers). | off (caching on) |
| "Searchable Entities" | The entities the assistant may search and read. | empty = all entities |
| "Stored Query Tags" | The assistant may only run stored queries that carry one of these tags. | empty = no stored queries; searches the assistant builds itself stay possible |
| "File Upload" | Users may upload files into the chat (section 6). | off |
| "Max File Size (MB)" | Upper limit per uploaded file. | empty: 20 MB |
| "Allowed File Types" | Allowed extensions, separated by comma, for example pdf, png, docx. |
empty = every type the chat can read |
| "File Storage" | Where uploaded files are stored: "Azure Blob Storage" or "S3 Storage". | empty = the storage for images from the global settings |
| "File Storage Credentials" | The credentials of that storage. Only together with "File Storage". | empty |
| "External MCP Servers" | Further servers whose tools the assistant may use: "Name", "URL", "Access Token (optional)" (section 5). | none |
Writing the instructions¶
The instructions are the most important setting. A good instruction states:
- the role – "You support the service desk of ACME with questions about tickets."
- the scope – "Only answer questions about tickets and customers. Decline everything else."
- the way of working – "Search before you answer. Name the ticket number of every ticket you mention."
- the tone and language – "Answer briefly, in the language of the question."
The expression is evaluated without a record and cannot read the fields of a record. To give the assistant the record a form shows, attach it in the chat block (section 6).
4. Purpose and tool groups¶
Purpose¶
| Purpose | Serves | Tool groups it may be given |
|---|---|---|
| "Agent support (works with records)" | Users who work with records | "User interface", "Records", "Queries" |
| "Administration (works with definitions)" | Administrators who build the configuration | all groups |
The purpose is an upper limit. An agent support assistant can never be given the definition groups, whatever else is configured. Switching an assistant from "Administration" back to "Agent support" takes these groups away at once.
Tool groups¶
| Group (as shown in the editor) | What the assistant can do | Purpose |
|---|---|---|
| "User interface (show and open records)" | Show records as cards in the chat, open a record, show a message to the user | both |
| "Records (read records and schemas)" | List the entities, read the structure of an entity, read a record with its fields and related records, read the records attached to the chat | both |
| "Queries (search, aggregate, stored queries)" | Search records with conditions, count and sum (also grouped), list and run stored queries | both |
| "Documentation" | Read the description of every kind of definition, the built-in guides on how nexxcite is configured and this product documentation | Administration |
| "Definitions (read the configuration)" | Find and read definitions, see where a definition is used, see all logic of an entity, check a definition for errors, test an expression, look up icons | Administration |
| "Definition authoring (change the configuration)" | Create definitions and change them – into the sketch (section 8) | Administration |
| "Background processing (read execution history, schedules and server health)" | Read the health of the servers, the execution history with protocols and logs, and the schedules | Administration |
| "Communication (read sent and received e-mails)" | Search the e-mails actions sent and mailbox listeners received, and read one with its content and what it belongs to (see Communication) | Administration |
The groups are a coarse switch. On top of them, for every tool:
- The permissions of the user apply. A tool the user is not permitted to use is not offered to the model at all. Reading definitions of a kind requires the permission to open its management view (for example "Open Action Manager"); writing requires the corresponding "Add …" or "Edit …" permission; the background processing tools require "View Background Processes"; the communication tools require "View Communication".
- Read restrictions apply. Records are read with the entity policies of the user's roles. The assistant does not see records the user may not see.
- "Searchable Entities" and "Stored Query Tags" restrict the data tools further.
- The place of the chat decides about the user interface tools: they are only available where a user interface is attached (section 7).
Example: an administration assistant with all groups is used by a user with the role "Clerk", which has no Admin Studio permissions. The assistant gets the record and query tools – but none of the definition or background processing tools, because the user may not use them.
What no assistant can do¶
- Create, change or delete records. There is no tool for it.
- Read or change users, roles, credentials, API access, authentication providers or sketches.
- Delete definitions as a whole, or publish a sketch.
- Remove fields of an entity, change their type or repoint a relationship (section 8).
- Start, repeat or requeue background jobs. It can suggest it; a person does it under Monitoring → Background Processes.
5. External MCP servers¶
An assistant can use the tools of other systems that offer them through the Model Context Protocol (MCP). Per server:
| Setting | Meaning |
|---|---|
| "Name" | Name of the server. It is put in front of its tool names so that the model can tell several servers apart – give every server a different name. Empty uses mcp. |
| "URL" | The address of the server (HTTP or HTTPS, streamable HTTP transport), for example https://example.com/mcp. |
| "Access Token (optional)" | Sent as Authorization: Bearer <token>. |
nexxcite connects to the servers at the start of every answer. A server that cannot be reached is skipped; the assistant then works without its tools, and the problem is written to the application log.
For administrators
- Tools of an external server are not checked against nexxcite permissions. Every user of the assistant can use them with the access the token grants. Give the token only the rights every user of the assistant may have.
- The model decides what it sends to the server – this can include data from records it has read. Connect only servers you trust with that data.
- The access token is stored in the assistant definition and shown in plain text in its editor. See AI providers.
6. Attachments and chat history¶
Records attached to the chat¶
Users can attach records to a conversation ("Attach a record to the conversation") – found through a search over the searchable entities. The assistant is told which records are attached and reads them with its record tools. A chat block in a form or on a dashboard can also attach records on its own, for example the record of the form.
Files¶
With "File Upload" switched on, users can attach files ("Attach a file to the conversation"):
| Kind | Extensions | How the model gets it |
|---|---|---|
| Pictures | png, jpg, gif, webp | as a picture |
| as a document – for OpenAI-style providers other than Azure OpenAI and OpenAI itself, only the file name is passed | ||
| Text | txt, csv, json, xml, md, html | as text |
| Word | docx | the text is extracted |
| Excel | xlsx | the text of each sheet is extracted |
Other types are refused. Long texts are passed in part; the assistant reads the rest on demand. A chat block can switch the upload off for itself, but not on when the assistant does not allow it.
Uploaded files are stored in the file storage ("File Storage"). They are not deleted when the conversation ends; a file the user removes from the conversation is deleted.
Conversations¶
- A conversation belongs to one user. Users never see each other's conversations.
- A chat block can keep separate conversations, for example one per record.
- A conversation is kept in the memory of the server for 60 minutes after the last activity. After that, or when the server restarts, it is gone. "Forget this conversation and start over" ends it at once.
- "Copy chat" copies the conversation, including all tool calls and their arguments, to the clipboard.
nexxcite does not store conversations permanently. To keep a history, a chat block in a form or on a dashboard can run an action for every message, which writes it into an entity of your own. The action receives the message, the direction, the time and – as JSON – the tool calls, the token usage and the attachments. See Forms and Dashboards.
7. Where assistants appear¶
| Place | How | Notes |
|---|---|---|
| Form | The form block for an AI assistant | Expressions of the block are evaluated against the record of the form; the record can be attached automatically. See Forms. |
| Dashboard | The dashboard widget for an AI assistant | See Dashboards. |
| Global search | Every assistant is offered as a source of the global search | Restrict per role in the tab "Global Search" → "AI Search Assistants"; without an entry in any role of a user, all assistants are offered. See Roles and permissions. |
| Actions | The commands "AI Assist" and "AI Predict Value" | "AI Assist" uses tools only with "Enable Tools" switched on – then it can open a record or show a message where a user interface is attached, and use the other tools everywhere. Without "Enable Tools", and with "AI Predict Value", the model answers in one request without tools. See Actions. |
There is no separate chat window in the Admin Studio. An administration assistant is used through the same places – typically the global search or a dashboard for administrators.
For administrators
- Restrict administration assistants in the global search to the roles of administrators. Other users would not get the definition tools anyway, but they would see an assistant that cannot help them.
- A deactivated assistant is still listed in the global search; it answers with its offline message.
8. Changes to the configuration – the sketch rule¶
An administration assistant with "Definition authoring" can create and change definitions. For every change:
- It goes into the open sketch of the user – never directly into the live configuration. If the user has no open sketch, one is opened. A user without the permission "Create sketch" cannot have changes made for them.
- It requires the same permission as the editor – "Add …" for new, "Edit …" for existing definitions.
- It is marked as made by the AI. The chat shows it under the answer: "Written to your sketch", with the definitions that were created or changed and the note "Nothing is live until you publish the sketch." "Undo" takes the step back.
- Changes to the database structure – entities, fields, relationships – are marked with "Changes the database structure - review this before publishing." The assistant may create entities, fields and relationships and extend them, but not remove a field, change its type or repoint a relationship; that stays with a person in the entity editor.
Nothing takes effect for users until a person publishes the sketch. Check the changes of the sketch before publishing, as you would with the work of a colleague. See Sketches and publishing.
| Kind of definition | Readable | Writable |
|---|---|---|
| Entities, relationships | yes | yes – adding and extending only |
| Expressions, queries, business rules, actions, global values | yes | yes |
| Forms, grids, lists, filters, dashboards, app bars, themes | yes | yes |
| Scheduled actions, mailbox listeners, counters, business hours | yes | yes |
| AI assistants | yes | yes |
| Icon fonts | yes | no |
| Users, roles, credentials, API access, authentication providers, sketches | no | no |
Note: a scheduled action or a mailbox listener created by the assistant starts working only after the server that runs them has restarted. See Scheduled actions and Mailbox listeners.
9. Product documentation¶
With the group "Documentation", an administration assistant can search and read this product documentation – exactly the version that is installed, included in the application. It needs no connection to the documentation website. It also has the descriptions of every kind of definition and built-in guides on how nexxcite is meant to be configured.
10. Transparency for users¶
| What the user sees | When |
|---|---|
| The answer while it is being written | always |
| "AI searched ' |
when the assistant searched records |
| Record cards that open the record on click | when the assistant shows records |
| The tools used, with duration and arguments ("Show what the assistant did to answer") | with "Show Tool Calls In Chat" |
| Tokens used by the answer | with "Show Token Usage In Chat" |
| "Written to your sketch" with "Undo" | when the assistant changed definitions |
nexxcite does not mark answers as generated by AI beyond the chat itself. If your organisation requires a notice that users are talking to an AI, put it into the placeholder or the opening message of the chat block, or into the instructions.
Every tool call is written to the application log with the user, the assistant, the tool, the
duration and the size of the result. The arguments – which can contain record data – only appear at
the log level Debug.
11. Permissions¶
| Permission | Allows | Granted by |
|---|---|---|
| "Open AI Assistant Manager" | Seeing the collection in the Admin Studio | System Developer |
| "Add AI Assistant", "Edit AI Assistant", "Delete AI Assistant" | Creating, changing, deleting assistants | System Developer |
Using an assistant needs no permission of its own – whoever sees a chat block, or the assistant in the global search, can chat with it. What the assistant then does is bounded by that user's permissions (section 4).
12. Limitations¶
- An answer can take at most "Max Tool Iterations" rounds (default 10, at most 50). If the limit is reached, the answer ends – possibly without a final reply. Raise the value for administration assistants, which read documentation and check the configuration before they answer.
- Searches of the assistant return at most 50 records per request.
- Conversations are not stored permanently and do not survive a restart of the server. With several servers, a conversation is kept on the server it took place on; after a switch to another server, the user starts a new one.
- Uploaded chat files are not cleaned up automatically.
- The quality of answers depends on the model. A model can be wrong, misunderstand the data or invent facts. Check answers that matter – and every change to the configuration before you publish it.
- Tools of external MCP servers are not bound to nexxcite permissions.
- The instructions are evaluated without a record.
13. Frequently asked questions¶
The assistant says it has no access to something. Why? Check, in this order: the tooltip of "Enabled Tool Groups" (which groups the assistant really gets), "Purpose", "Searchable Entities", "Stored Query Tags" and the permissions of the user. With "Show Tool Calls In Chat" you see which tools it tried.
Can the assistant see records the user may not see? No. Records are read with the user's permissions and read restrictions.
Can the assistant change data? It cannot change records. An administration assistant can change definitions, but only into the user's sketch; nothing takes effect before a person publishes it.
Can we use the same assistant for clerks and administrators? Yes – an administration assistant only gets the tools each user is permitted to use. Separate assistants with their own instructions usually give better answers, though.
Are our data used to train the model? That depends on the provider and your contract with them, not on nexxcite. See AI providers.