> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maadify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat with Agents
> Use the chat experience, universal search, and agent selection
Chat is the main place where you test agents and use them day to day. You can ask questions, route work to the right parent agent, search internal data, inspect each workflow step, and review the sources or live actions that support an answer.
Maadify gives you three ways to interact with agents:
* **Select a default agent** in chat settings when you want every message to use a specific parent agent.
* **Use Select Agent** when you want Maadify to route each question to the best parent agent based on your question and each agent description.
* **Configure commands** when you want quick access to specific agents from the command box.
You can also use **Universal Search** from chat settings to ask questions across selected index data stores.
## Access chat
You can interact with agents in two ways:
* Use the embedded chat widget inside the Maadify admin portal.
* Open the full chat experience at [https://app.maadify.com/chat](https://app.maadify.com/chat).
## Chat controls
Maadify chat gives users a familiar messaging experience with built-in controls for settings, commands, file input, streaming responses, and step review.
Users can access:
* **Starters** to quickly open **Select a Configured Agent** or **Configure Command Box** when a chat starts.
* **Chat settings** to choose the default routing mode, select a default agent, enable relationship filters, configure Universal Search filters, and control file-to-text conversion.
* **Slash commands** by typing `/` to choose a configured agent or command.
* **File attachments** to send supported documents, data files, or images with a message.
* **File conversion controls** to decide whether attachments become message context or stay available for workflow processing.
* **Stop controls** to cancel a running agent response.
* **Streaming responses** so long-running answers appear as they are generated.
* **Step details** to inspect agent steps such as Select Agent, parent agent responses, tool calls, and tool executions.
* **Source sidebar** to open source details returned from tools or Universal Search.
These controls are available in both the embedded chat widget and the full chat experience.
## Attach files to chat
You can attach one file up to 25 MB to a chat message. Maadify supports:
* **Images**: JPEG, PNG, GIF, and SVG.
* **Documents**: PDF, DOCX, and PowerPoint.
* **Spreadsheets and data files**: XLSX, XLS, CSV, JSON, and XML.
* **Text files**: TXT and HTML.
File conversion controls how the attachment is passed to the agent:
* **Always** converts supported attachments into text and includes that text in the chat content.
* **Never** keeps the attachment available without adding converted text to the message content. Use this when the workflow or tool needs to process the original attachment.
* **Ask Everytime** lets you choose whether to convert the attachment before sending the message.
When you convert an image, Maadify uses AI to describe the image in markdown. That markdown description becomes context for the agent.
## Choose how chat routes messages
Chat routing controls what happens when you send a message without choosing an agent command.
Send messages to one configured parent agent. Use this when you usually work with the same workflow.
Let Maadify choose the best parent agent from your available agents.
Search internal information from configured index data stores.
You can update routing from chat settings. The **Default Agent** setting supports:
* **Select Agent** to route each question automatically.
* **Universal Search** to search selected index data stores.
* **Select Default Agent** to choose one parent agent for all messages.
When you change settings that affect chat routing, Maadify updates the active WebSocket session. For Universal Search, Maadify rebuilds the search engine with the selected index stores and relationship filters.
## How agent chat is initialized
When you start a chat, Maadify opens a WebSocket session and initializes the group chat model. The initialization payload includes:
* **Session and thread IDs** to track conversation state.
* **Agent and action** for the selected parent agent workflow.
* **Channel and supplier tenants** for the current relationship.
* **History and context variables** to restore prior state.
If the selected agent does not belong to the current channel or supplier, chat initialization is blocked.
## Group chat execution
Agent chat uses the group chat model to orchestrate:
* Parent agents and sub-agents.
* Tool calls and tool execution.
* Context propagation between workflow steps.
* Memory context and structured outputs.
The model keeps **context\_variables** and **element\_ids** so subsequent steps can reference outputs from earlier steps.
## Review workflow steps in real time
When you talk to a parent agent, Maadify shows the workflow as it runs. Each step appears under the agent or tool name so you can inspect what happened.
Workflow steps can include:
* **Agent responses** from the parent agent or sub-agents.
* **Agent tool calls** with the input the agent sent to a tool.
* **Tool executions** with the input and output returned by the tool.
* **Current actions** such as approval requests, generated files, or live browser work when an agent uses a virtual browser.
Use the step details to verify how the agent interpreted your request, which tools it used, and what data influenced the final response.
## Chat control events
During a session, the client can send control events:
* **cancel** to stop a running task.
* **reset\_context** to restart the session with a new thread or history.
* **chat** to send a message payload with optional file input.
These events keep chat responsive while long-running tasks execute.
## Use Select Agent
Use **Select Agent** when you do not want to choose a parent agent manually. Maadify compares your question, recent chat history, optional file input, and the descriptions of available parent agents. It then selects the parent agent and relationship that best match the request.
Your question, recent history, and any file input are sent to the selection service.
If relationship filtering is enabled, the selection uses the sender and receiver tenants.
The response includes a parent agent name, action, and relationship details.
The selected agent is initialized and ready to chat.
The selection request is sent to `/select_agent` and includes:
* **question** and **history**
* **channel\_tenant** and **supplier\_tenant**
* **relationship\_filters** when enabled
* **thread\_id** and **file\_input** when present
The service uses your authenticated tenant context to choose the best parent agent for the request.
Use **Select Agent** when users ask different kinds of questions in the same chat and should not need to know which workflow handles each request.
## Configure agent commands
Commands give users quick access to individual parent agents. Configure commands when users frequently talk to the same set of agents.
You can open the command configuration in two ways:
* Type `/` in chat to see configured agents and command actions.
* Click **Configure Command Box** to choose commonly used agents.
When you add an agent as a command, Maadify stores the command in your chat settings and makes it available in the command box. Each command includes the agent display name, relationship context, and description. Maadify also initializes configured agents so they are ready when users choose them.
To use a command, type `/` and select the configured agent. Your next message goes directly to that agent instead of using default routing.
## Continue conversations
Chat sessions track:
* **thread\_id** for the conversation.
* **session\_id** for execution state.
* **context\_variables** for tool outputs and memory context.
When a new thread is created or context is reset, the chat session updates and the agent continues with a clean state. The chat client can also send cancel or reset events during a running task.
## Universal search chat
Universal Search lets you ask questions about information stored in your index data stores. Use it when you want to search internal knowledge instead of running a specific parent agent workflow.
You can:
* Choose which index data stores to search.
* Filter results by channel and supplier relationships.
* Ask follow-up questions in the same conversation.
* Start a new chat when you want a fresh search context.
* Review sources that support the answer.
Universal search requires access to the **universal\_search** permission.
You can configure Universal Search from chat settings. If **Filter on Indexes** is enabled, choose the index data stores you want to search. If **Filter on Relationships** is enabled, choose the channel and supplier relationships that should scope the results.
When you change these settings, Maadify updates the search experience so future questions use the selected data stores and filters.
Use Universal Search when your goal is to find information. Use a parent agent when your goal is to run a workflow or take action with tools.
### Universal Search results
Universal Search returns an answer and source details when matching information is found. Sources help you understand which records or documents supported the response.
## Review sources and actions
Maadify adds sources when a response uses data retrieved from tools or Universal Search. Sources can include tool output, structured records, CSV output, and the agent or tool that produced the data.
Sources help you verify:
* Which agent produced the source.
* Which tool returned the data.
* What tool input or arguments were used.
* Which records supported the answer.
Some agents also expose current actions instead of static sources. For example, an agent that works in a virtual browser can show the live browser context while it acts.
## Troubleshooting
* Confirm you are signed in and your access token is valid.
* Refresh the page to reinitialize the WebSocket session.
* Check that parent agents are active for the relationship.
* Verify your question includes enough context.
* Check relationship filters if **Filter on Relationships** is enabled.
* Type `/` to open the command box.
* Click **Configure Command Box** and add agents again.
* Refresh the chat if settings were recently updated.
* Verify index data stores are connected and populated.
* Rebuild the search engine after changing filters.
* Check selected index stores if **Filter on Indexes** is enabled.