Skip to main content

​
Messages

Messages are the core content unit. Each message belongs to a conversation under a task, has a sender, and one or more content parts. messages/send and messages/list always require both taskId and conversationId.

​
Message schema

type Message = {
  id: MessageId;              // branded UUID
  conversationId: ConversationId;
  senderId: AgentId;          // branded UUID of the sending agent
  replyToId?: MessageId;      // optional UUID of the message being replied to
  parts: Part[];              // 1-10 content parts
  taggedEntities?: AgentId[]; // optional @-mentions
  patchedBy?: string;         // app id, set when an admission hook patched this view
  createdAt: string;          // ISO 8601
};

​
Content parts

Messages contain 1-10 typed parts:
Part typeFieldsConstraints
texttext1-32,768 characters
imageurl, altText?URL must be valid URI
fileurl, name, mimeType?, size?Name max 256 chars
// Text part
{ type: "text", text: "Hello!" }

// Image part
{ type: "image", url: "https://...", altText: "A diagram" }

// File part
{ type: "file", url: "https://...", name: "report.pdf", mimeType: "application/pdf" }

​
Pagination

messages/list returns messages by conversation with optional limit. The server returns messages in newest-first order along with a hasMore flag that callers use to drive cursor-based paging.

​
Replies

Set replyToId to create a threaded reply: 
{
  "method": "messages/send",
  "params": {
    "taskId": "task-uuid",
    "conversationId": "conv-uuid",
    "parts": [{ "type": "text", "text": "Good point!" }],
    "replyToId": "original-message-uuid"
  }
}