Chat

Every conversation in OpenAgent is a Chat session backed by a Store. The Store's configuration determines everything: which model responds, whether the knowledge base is searched, which tools are available, and what instructions the model operates under.

Request lifecycle

When a user sends a message, OpenAgent runs this sequence:

1. Load history. The conversation history is retrieved from the database, bounded by the Store's Memory Limit. Turns beyond the limit are dropped, oldest first. The system prompt is always included regardless of the limit.

2. Search the knowledge base. If the Store has an Embedding Provider and indexed Files, the user's message is embedded and compared against the Store's Vectors. The top N chunks by cosine similarity are retrieved (N = Knowledge Count).

3. Assemble context. The prompt is constructed: system prompt first, then the retrieved chunks (labeled as context), then the conversation history, then the user's message.

4. Call the model. The assembled context is sent to the LLM. If the model calls a tool, OpenAgent executes the tool, appends the result to the context, and calls the model again. This loop repeats until the model produces a text response.

If a tool call fails, OpenAgent marks the tool result as an error and gives the model a recovery turn. The model can retry with corrected arguments, choose a different approach, or explain why the task is blocked.

5. Stream and save. Tokens stream to the client in real time. When the response is complete, a Message record is saved containing the text, tool calls, retrieval metadata (if any), token counts, and estimated cost.

Chat records

Each Chat belongs to a Store and a user. It records:

• Display Name — the chat title shown in the sidebar. OpenAgent prefers the generated title from the model and falls back to a short version of the first user message when no title is returned.
• Message Count — total turns in the conversation
• Token Count — cumulative tokens across all messages
• Price — cumulative estimated cost (if pricing is configured on the model provider)
• Is Generating / Is Unread — status flags used by the chat list. OpenAgent marks a chat as generating while a response is running, polls active chats for status updates, and clears the unread state when a completed chat is opened.
• Is Hidden / Is Deleted — soft-delete flags; admins can hide or delete chats without permanent removal

Admins can browse all Chats across all users from Chat in the admin panel. Opening a Chat shows the full conversation history with Message detail.

Message records

Every turn is saved as a Message. The admin UI can show the full technical detail for debugging (retrieval results, tool calls, which provider handled the request, and token/cost accounting).

Feedback and regeneration

Users can leave feedback on AI responses:

Like / Dislike — thumbs up or down on a message. Useful for collecting quality signals from users without any additional tooling.

Regenerate — users can regenerate an AI response. Both the original and regenerated responses are retained.

Follow-up suggestions

If Suggestion Count is set on the Store (to a number greater than 0), OpenAgent generates follow-up question suggestions after each AI response. These appear as clickable prompts in the chat UI. The count controls how many suggestions are generated — typically 2–4 works well.

Setting Suggestion Count to 0 disables the feature entirely.

Attachments

Users can attach files from the chat input. Files can also be pasted directly from the clipboard or dragged into the input area, which adds them to the pending attachments before the message is sent. Pasting and dropping accept the same file types as the attach button — images plus common document formats such as .txt, .md, .yaml, .csv, .pdf, .docx, .xlsx, and .pptx — and duplicate files pulled from the clipboard are de-duplicated automatically.

Streaming

Responses stream token by token. The frontend renders each token as it arrives. Tool calls appear inline as they happen — the user can see what tool was called, with what arguments, and what it returned, before the final response is generated.

Failed tool calls are shown as error tool results in the stream, which makes retries and blocked actions easier to diagnose from the chat transcript.

If a provider doesn't support streaming, OpenAgent falls back to waiting for the full response. Streaming is the default for all providers that support it.

During long-running tool calls, OpenAgent sends SSE keepalive comments so browsers and proxies are less likely to close an otherwise quiet stream.

While a response is running, OpenAgent can stream generation status events into the chat UI. The message shows a compact progress strip for stages such as preparing context, retrieving knowledge, calling tools, or waiting for the model, so users can see that work is still moving even before new answer text appears.

Message generation is tracked independently from a single browser connection. If the tab refreshes or the SSE connection drops, reconnecting to the same message can replay the generated stream while the job is still retained. Closing the stream alone does not cancel the model call; use the chat cancel action to explicitly stop a running answer.

If generation finishes while the browser was interrupted, the chat UI refreshes the latest messages when it detects the chat is no longer generating. Tool call arguments can also stream incrementally, so users can inspect long tool inputs before the tool result is complete.

When a tool creates a downloadable file, OpenAgent can show generated Resource cards directly under the assistant message.

User identities

Wherever a user appears in the UI — chat message authors, comments, issue replies, task lists, Insights contributor breakdowns, and the owner columns of the admin management list pages (Chats, Messages, Files, Sessions, Stores, and more) — OpenAgent shows their real display name and avatar instead of a bare username. Hovering the name or avatar pops a small profile card, and it links through to the full user profile, so it is easy to see who wrote a message or left a comment.

Multi-provider fallback

A Store can have Child Model Providers as fallbacks. If the primary provider fails (network error, rate limit, API key issue), OpenAgent tries each fallback in order. No conversation is interrupted by a single provider outage.

Advanced: what’s in a Message record?

If you’re integrating with the API or debugging deeply, Message records include structured fields for:

• Retrieval metadata (which chunks were retrieved and their similarity scores)
• Tool calls (tool name, arguments, and results)
• Provider attribution (which model/embedding provider was used)
• Token and cost accounting

Related

• Agent Configuration — prompt, memory, rate limiting, content filtering
• Stores — complete Store field reference
• Vectors — understanding vector retrieval and scores