> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/ai-assistants.md).

# AI Assistants

Chat with your agents to test them or use them in daily work, edit the agent from the chat, and reset a conversation.

In **Agentic AI** -> **AI Assistants**, you and your team can chat with enabled custom agents, for example to test a new agent or to use an agent in daily work.

{% hint style="danger" %}
AI Assistants is currently in preview mode and is enabled upon request. To enable it for your tenant, contact the [Emporix Support Team](mailto:support@emporix.com). Some of the features may not be fully operational yet.
{% endhint %}

<figure><img src="https://1530167654-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8GgoeZEZYjZrpjOU6w52%2Fuploads%2Fgit-blob-ae0858cb56be0fa4883400cf5a103a835980369b%2Fagentic_ai_assistants.png?alt=media" alt="AI Assistants view"><figcaption><p>AI Assistants view</p></figcaption></figure>

## Chatting with an agent

You can start a chat in two ways:

* In **AI Assistants**, select the agent in the **You are chatting to** chooser.
* In **AI Agents**, open an enabled agent and choose **Test**. **AI Assistants** opens with that agent selected. For a disabled agent, **Test** is not active.

<figure><img src="https://1530167654-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8GgoeZEZYjZrpjOU6w52%2Fuploads%2Fgit-blob-a68b2082ed69dcd470487611988e029aeb1aed39%2Fagentic_agent_test_button.png?alt=media" alt="Test button in the agent view"><figcaption><p>Test button in the agent view</p></figcaption></figure>

Describe in the chat field what you want the agent to do and what you expect as a result. Press `Shift+Enter` to add a new line. Under **Recommended (AI generated)**, the chat also suggests ready-to-use prompts.

{% hint style="info" %}
The recommended prompts come from the [Recommended Prompts Assistant](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agent-library/recommended-prompts-agent.md), a helper agent that is not enabled yet the first time you open **AI Assistants**. Until then, the recommendations are off and the chat shows **Enable helper agent**. Choose it to create the helper agent from its predefined template. Once enabled, it stays available and the chat suggests prompts for each agent you select.
{% endhint %}

While the agent works, its answer appears progressively. The chat shows when the agent is thinking and which tool it is using. To interrupt an answer, choose **Stop**. The part that has already arrived stays in the conversation. You cannot send a new prompt until the answer is finished or stopped.

To change the agent you are testing, choose **Edit agent**. The agent opens in edit mode, where you can amend its settings, prompts, model, and other configuration.

{% hint style="info" %}
For more information, see [AI Agents](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agents.md#creating-a-custom-agent).
{% endhint %}

To start the test over, choose **Reset**. The conversation is cleared and the next prompt starts a new conversation, so the agent does not remember the earlier messages. Use it, for example, after you change the agent's prompt.

An agent that starts on commerce events needs an API trigger before you can chat with it. When you select such an agent, the chat asks you to add one. Choose **Add API trigger** to test the agent in the chat. The agent keeps its commerce event trigger.

<figure><img src="https://1530167654-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8GgoeZEZYjZrpjOU6w52%2Fuploads%2Fgit-blob-ce5f6f0cc3b1442e154f2f15c7c03c120ec59586%2Fagentic_add_api_trigger.png?alt=media" alt="Add API trigger prompt" width="500"><figcaption><p>Add API trigger prompt</p></figcaption></figure>

{% hint style="warning" %}
The agent runs with its attached tools, so a test can change real data in your tenant.
{% endhint %}

## Attaching files to a message

You can give the agent files to work with, for example an order as a spreadsheet or an XML file, together with your prompt. To add files, choose **Attach files** in the chat field, or drag and drop the files onto the chat. The files are uploaded when you send the message.

The following file types can be attached:

* Images – PNG and JPEG
* Documents – PDF and plain text
* Data files – CSV, JSON, XML, HTML, and XLSX

You can attach up to 5 files to one message, and each file can be up to 8 MB. Legacy Excel files (XLS) and other file types are not attached, and the chat shows which types are supported.

The agent reads the content of each file. From an HTML file, it uses the visible text of the page. From an XLSX file, it reads every sheet row by row and uses the last calculated value of each formula cell, not the formula.

The agent cannot read a file, even though it is attached, in the following cases:

* An XML file contains a document type definition (DTD) or entities. These are blocked for security reasons.
* The file is malformed.
* The file is too large to process.

In that case, the agent tells you in its answer that it cannot read the file. Fix or simplify the file and attach it again.

{% hint style="info" %}
To send files to an agent through the API, for example from an integration platform, see [How to pass a media file for the agents to process](https://developer.emporix.io/api-documentation/api-guides/artificial-intelligence/ai-service/ai-tutorial.md#how-to-pass-a-media-file-for-the-agents-to-process).
{% endhint %}

## Agents available in the chooser

You can change the agent in the **You are chatting to** chooser at any time. If the conversation already contains a message from you, the chat asks you to confirm the switch first.

The agents a user can select depend on their permissions:

* Users with permission to manage agents (`ai.agent_manage` scope) see all enabled agents and can open the selected agent for editing. If an agent accepts only customer tokens or has no API trigger, the chat offers to add the [employee scope or the API trigger](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agents.md#define-activation-rules) so that you can test the agent.
* Other users see only enabled agents with the `chat` tag. Add the tag in the [Define the agent visibility](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agents.md#define-the-agent-visibility) step to make an agent available to them.

## Formatting of answers

Answers are shown as formatted text, including headings, lists, tables, and links. The chat supports `https` and `mailto` links, which open in a new tab. Links with other protocols, such as `http`, are shown as plain text. Images in the text are not loaded. The chat shows them as links, or only their description if the address is not an `https` link.

The chat can also show charts, diagrams, tables, JSON records, notes, and source code. To let the agent answer this way, add the following text at the end of the agent's **User Prompt**. The rules only shape how the answer is shown. If your prompt requires a specific output format, the agent keeps that format.

{% prompt description="Rich chat output rules for the agent's User Prompt" icon="rectangle-terminal" openInAIProviders="false" defaultExpanded="partial" %}

````markdown
Rich chat output — follow these rules:
These rules only shape how an answer is shown. Your own instructions decide what to answer. If your instructions require a specific output format, follow them and ignore these rules.
Write the answer in GitHub-flavored Markdown: headings, lists, bold, links, and tables. Do not wrap the whole answer in one code fence. Do not use HTML.
Use a block only when it makes the answer clearer than markdown.
- numbers across time or categories: ```vega-lite
- a process, steps, flow, states, or a sequence of calls: ```mermaid. Never draw these as a chart.
- rows to compare or look up: ```csv
- one nested record: ```json
- a warning or caveat: ```note
The opening and closing ``` each stand alone at the start of a line. Exact lowercase tag, always closed, never nested in another block. No URLs, links, images, HTML, or scripts inside a block. A short markdown sentence around a block is fine.
vega-lite: one valid JSON object. Rows inline in data.values. No $schema, no data.url. Single chart: mark and encoding at the top; several marks: layer. One chart per group: facet at the top, the chart inside spec.
mermaid: flowchart, sequenceDiagram, stateDiagram-v2, classDiagram, or erDiagram. Quote labels with spaces or punctuation: A["Payment (2 attempts)"]. Label branches on arrows: B -->|rejected| C. No click or styles.
csv: header first, comma-separated. Quote a field with a comma, quote, or line break; write a quote inside it as two quotes. Plain text cells. Optional title after the tag: ```csv Orders
json: valid JSON. Optional title after the tag.
note: plain text. The words after the tag are the title: ```note Important
When the answer is source code, reply with one language fence. The tag is language# plus the language id, for example language#java or language#python. Put the source in the fence. No links inside it.
````

{% endprompt %}

To let the agent also create images and downloadable files in the chat, select **Built-in file generator** in the [Attach tools](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agents.md#attach-tools) step.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/ai-assistants.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
