Chat and Conversations

A published Agent provides a full chat page; the preview on the right side of the editor is for build-time debugging. A conversation is created when the first message is sent and stores variables, message count, and Token usage.

Start a Conversation

From the Apps page

1. Navigate to Apps (/app/apps).
2. Select the Agent tab and find the agent you want to use.
3. Open the agent card menu and choose Chat.
4. The agent chat opens at /chat/{agent_id}. Send your first message to create a conversation.

From an existing agent chat

1. Open the agent's chat page.
2. Use the conversation controls in that page to continue a recent conversation or start a new one.
3. Type your message and send it.

Chat Interface

Layout

┌─────────────────────────────────────────────────┐
│  Agent Name                    [Settings] [...]  │
├─────────────────────────────────────────────────┤
│                                                  │
│  Agent: Hello! How can I help you today?        │
│                                                  │
│  You: What is Clouisle?                         │
│                                                  │
│  Agent: Clouisle is an enterprise-grade...      │
│  [Sources: doc1.pdf, doc2.md]                   │
│                                                  │
├─────────────────────────────────────────────────┤
│  [📎] Type your message...            [Send] │
└─────────────────────────────────────────────────┘

Key Elements

Sending Messages

Text Messages

Basic message:

1. Type your message in the input box
2. Press Enter or click Send
3. Wait for the agent response (streaming)

Multi-line message:

1. Type your message
2. Press Shift + Enter for a new line
3. Press Enter to send

File Uploads

If the agent supports file uploads (attachments enabled):

1. Click the 📎 Attach button
2. Select file(s) from your computer
3. Supported formats depend on the agent's attachment configuration (PDF, DOCX, TXT, MD, CSV, XLSX, PPTX, images, etc.)
4. Wait for the file to upload/parse
5. Add your message or question about the file
6. Click Send

Upload limits:

• All chat uploads are limited to 10 MB per file (server-enforced)
• Max files per message is configurable by the agent (default 5)

For detailed file support and security notes, see Attachments and Media.

Understand a Reply

Streaming Responses

Agents stream responses in real-time:

• Text appears word-by-word as generated
• You can read while the agent is still typing
• Stop generation by clicking the Stop button

Response Components

A reply may consist of the following parts:

• Body: Displayed in streaming increments.
• Reasoning: Shown only when the model provides it and the Agent does not hide it.
• Referenced documents: The chunks, document names, and relevance returned by RAG.
• Tool calls: Parameters, results, logs, and artifacts; details can be hidden by the Agent.
• Media results: Images or videos rendered directly into the assistant's message body.
• Message actions: Copy, version, Token, speed, and more; can be hidden by the Agent.

Thought Timeline and Source Citations

Progress events are displayed in the order they are emitted. Retrieval, context compression, reasoning, tool calls, media results, and text can be interleaved; the UI does not always put retrieval first.

Retrieved sources may include a stable citation_id. When citing a factual claim, use the exact [[cite:SOURCE_ID]] marker and replace SOURCE_ID with the value returned by the source.

Response Quality

High-quality responses include:

• Direct answer to your question
• Relevant context and details
• Source citations (if using a knowledge base)
• Clear structure and formatting

If response quality is poor:

• Rephrase your question more clearly
• Provide more context
• Break complex questions into simpler parts
• Check if the agent has access to a relevant knowledge base

Attachments and Media

Attachments provide user assets (documents, images) to the agent; media generation lets the agent call authorized image or video models. Both must be explicitly enabled in the Agent Orchestration.

Default attachment limits: single file 10 MB (1KB-50MB), 5 per message (1-10). Images only enter the model directly when the chat model supports vision.

For full configuration options, see Attachments and Media.

Variables and Forms

If the agent defines required variables, complete the variable form before sending messages. Variables are referenced in the prompt as {variable_name}; {query} is the current user message.

1. The variable form appears at the top of the chat page
2. Fill in the required fields
3. Type your message and send

Stop, Steer, and Regenerate

• Stop: Click Stop during streaming. The client terminates the SSE stream and tells the worker to abort the run; the message state is recorded as manually stopped.
• Steering / User Guidance: While the Agent is generating or thinking, you can type supplementary instructions or corrections into the composer and send them without stopping the run. The UI renders a floating capsule above the composer indicating queued guidance, shows a "User Guidance" step in the thought-process timeline, and injects the steer into the active LLM context.
• Edit: Editing an earlier user message forks a new branch from that turn and streams a fresh reply under the new branch.
• Regenerate: Regenerating an assistant message appends a new version to that turn. Use the left and right arrows to toggle between versions without losing history.
• Delete: Deleting a message prunes downstream branches; deleting a conversation permanently deletes all of its messages and runs.

Scrolling and Interactive Optimizations

• Instant pin-to-bottom: sending a message immediately pins the viewport to the new bubble before the stream starts, avoiding blank states or first-token jumpiness.
• Collapsible thought process: expand or collapse the model's Chain of Thought at any time. Stream auto-scroll tracks thought steps cleanly, and tool-call cards support inline argument inspection, logs, and one-click artifact downloads.
• Queued follow-ups: typing a follow-up near the end of a run persists the message directly to the database and smoothly transitions into the next generation turn.

Message Branching

Conversations can have multiple branches:

Main conversation:
You: Tell me about AI
Agent: AI is...

Branch 1 (edit message):
You: Tell me about ML
Agent: ML is...

Branch 2 (regenerate):
Agent: AI, or Artificial Intelligence...

Navigate branches using the arrow buttons.

Manage Conversations

The conversation sidebar lets you create, select, rename, and delete your own conversations. Titles are up to 200 characters and are the only editable conversation setting.

Creating

Click the New chat (SquarePen) button at the top of the sidebar to start a new conversation; the conversation itself is created when you send the first message.

Renaming

Open a conversation's ... menu in the sidebar and choose Rename.

Deleting

Open the conversation's ... menu, choose Delete, and confirm. Deletion removes the conversation and its messages and cannot be undone.

Searching

Both conversation searches match a keyword against the conversation title or ID (title / id substring match); they never search message bodies:

Logs Page

The agent Logs page (Agent sidebar > Logs) lists conversations by time and search term; selecting one shows variables, model, Token usage, response time, reasoning, and knowledge sources.

Best Practices

Writing Effective Prompts

✅ Do:

Good: "What are the steps to reset my password in the
admin dashboard?"

Good: "Summarize the key points from the Q3 report
about revenue growth"

Good: "Compare the features of Plan A and Plan B in
a table format"

❌ Don't:

Bad: "password?"
Bad: "tell me everything"
Bad: "help"

Tips:

• Be specific about what you want
• Specify format if needed (table, list, summary)
• Provide relevant context
• Ask one thing at a time for complex topics

Managing Context

Start a new conversation when:

• Switching to an unrelated topic
• The agent seems confused about context
• You want a fresh start

Continue a conversation when:

• Asking follow-up questions
• Building on previous answers
• Maintaining context is important

Using Knowledge Bases Effectively

✅ Do:

• Ask specific questions about documents
• Request sources: "According to the manual..."
• Mention document names if known
• Follow up for clarification

❌ Don't:

• Ask about information not in the knowledge base
• Expect the agent to know real-time information
• Assume all documents are indexed

For detailed context management, see Memory and Context.

Troubleshooting

Agent Not Responding

Problem: No response after sending a message

Solutions:

1. Check your internet connection
2. Refresh the page
3. Check if the agent is published
4. Try a different agent
5. Contact the administrator

Slow Responses

Problem: Agent takes a long time to respond

Solutions:

1. Check your internet speed
2. Simplify your question
3. Try during off-peak hours
4. Contact the administrator about server load

Irrelevant Responses

Problem: Agent gives unrelated answers

Solutions:

1. Rephrase your question more clearly
2. Provide more context
3. Start a new conversation (clear context)
4. Check if the agent has a relevant knowledge base
5. Try a different agent specialized for your topic

Sources Not Showing

Problem: No source citations in RAG mode

Solutions:

1. Verify the agent has a knowledge base connected
2. Check the agent's RAG mode is not "off"
3. Ask more specific questions
4. Verify documents are indexed (status: completed)

File Upload Fails

Problem: Cannot upload files

Solutions:

1. Check file size (must be under 10 MB)
2. Verify the file format is supported
3. Check if the agent allows file uploads
4. Try a different file
5. Contact the administrator

Related: Streaming events, Conversations API, Attachments and Media, Memory and Context.