Chat with Agents

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 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.

​

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. 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. 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.

​

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.

​

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