Threads and items
In ChatKit, a thread represents a single conversation. It is the unit that ties together everything that happens in that conversation: messages, widgets, actions, system signals, and metadata. A thread is stored as an ordered history of thread items, which ChatKit loads, paginates, and renders as needed.
What is a thread?
A thread is an ordered timeline that contains:
- Conversation history (user and assistant messages)
- Structured content such as widgets and workflows
- Internal signals that guide processing or model behavior
- Metadata like titles or status flags
Threads are persisted by your store implementation and can be updated, continued, or made read-only according to your application’s needs.
What are thread items?
Thread items are the individual records that make up a thread. Each item represents one meaningful unit in the conversation history, such as:
- A user message
- An assistant response
- A widget rendered by the assistant
- A non-visible signal used only for model input
ChatKit maintains the order of items, streams new ones as they are produced, and paginates them when history is loaded.
How threads are created and updated
A typical thread lifecycle looks like this:
- Thread creation: When a user submits a message and no thread exists yet, ChatKitServer creates one and persists it by calling your store’s
save_thread. - Appending items: As the server streams a response, ChatKit persists thread items automatically as each item completes. Streaming events directly drive what gets stored.
- Updating metadata. Apply a
ThreadPatchto the saved thread. In a responder, yieldawait self.update_thread(turn.thread.id, {"title": "New title"}, turn.context, turn_id=turn.id)to save the change and update the browser. Usestore.patch_threadwhen the change needs no stream event. - Loading history: When history is enabled client-side, ChatKit retrieves past threads and their items. Users can continue an existing thread by default.
- Closing or locking. Set the thread status to
closedorlockedto update the client's input UI. Enforce any write restrictions in your server. Delete a thread when it should be removed from history.
How thread items are used
Thread items serve two primary purposes in ChatKit:
Model input
Your server's respond can load thread items and choose the history to include in model input. The same stored history is available when a user resumes a conversation.
See Respond to a user message for a full walkthrough.
UI rendering
On the client, ChatKit.js renders items incrementally as they stream in for the active thread. When a past thread is loaded, the same persisted items are re-rendered to reconstruct the conversation UI.
Core item types
User messages
UserMessageItems represent end-user input. They may include:
- Plain text entered by the user
- Optional
quoted_textfor reply-style UIs - Attachment metadata
User text is not Markdown-rendered, but it may contain @-mentions if your integration enables them.
Assistant messages
AssistantMessageItem holds assistant text and inline annotations. Widgets, client tool calls, and structured inputs are separate thread items.
Assistant text supports rich Markdown and is rendered progressively as it streams.
Markdown support
Assistant messages support:
- GitHub-flavored Markdown (headings, lists, code blocks, links, blockquotes)
- Stable list rendering during streaming (Safari-safe, no reflow)
- Optional single-newline line breaks
- Syntax-highlighted, copyable code blocks
- LaTeX math (inline and block)
- Tables with automatic sizing and horizontal scrolling
- Inline annotations that create interactive affordances in the UI
Hidden context items
Hidden context items stay on the server. Your responder can include them in model input so the model can react to activity in the interface.
Typical use cases include recording widget actions, selection state, or system signals.
-
HiddenContextItem. Application-defined context. The default converter handles strings. Overridehidden_context_to_inputto pass structured content. -
SDKHiddenContextItem: Hidden context inserted by the ChatKit Python SDK for its own internal operations. Most applications do not need to modify this unless overriding conversion behavior.
Thread item actions
Thread item actions are quick action buttons associated with an assistant turn. They let users act on the output—such as retrying a response, copying content, or submitting feedback.
Actions are configured client-side using the threadItemActions option.
Converting items to model input
ThreadItemConverter translates stored thread items into model-ready input items. The default converter understands common ChatKit item types such as messages, widgets, workflows, and tasks.
You can override the converter when you need custom behavior. For example:
- Formatting attachments for the model
- Translating tags or mentions into structured input
- Summarizing rich widgets into text the model can consume
Custom conversion is typically paired with prompting so the model receives a coherent representation of the conversation.