Messages Schema
Individual messages owned by the Convex Agent component
Ownership
Messages are owned and persisted by the Convex Agent component in its own database namespace — not the root app schema.
To list messages for a thread, call listUIMessages(ctx, components.agent, { threadId, paginationOpts }).
Fields
These fields reflect the Agent component's message model:
| Field | Type | Description |
|---|---|---|
_id | string | Convex document ID |
threadId | string | Parent thread |
role | "user" | "assistant" | "system" | "tool" | Message sender |
text | string | Plain text content of the message |
agentName | string | Name of the agent that produced this message |
status | "success" | "failed" | Whether the message was generated successfully |
model | string | LLM model used (e.g. gpt-4o-mini) |
usage | object | Token counts for the generation |
Notes
- Do not define a
messagestable in the root app schema — the Agent component manages its own storage. - Access message data via queries that delegate to
components.agentand check the caller's access first (e.g.goldie/threads:listMessages).