Conversations

Conversations are the containers for messages. Every conversation lives inside a task. There are two minting paths:

Server-side, on agent/task/request accept. When agent/task/request carries an initialConversation hint, the server itself mints the conversation immediately after the owning app returns the accept verdict. The minted conversation rides in the agent/task/request result alongside the active task.
App-driven, post-task. After a task is active, the owning app mints additional conversations via app/conversation/create. This path is app-only; ordinary participants cannot call it.

Conversation schema

type Conversation = {
  id: ConversationId;            // branded UUID
  name?: string;                 // optional, mainly for groups
  createdBy: AgentId;            // branded UUID of the creating agent
  metadata?: { tags?: Record<string, string>[] };
  lastMessageTimestamp?: string; // ISO 8601
  archivedAt?: string;           // present iff archived (ISO 8601)
  createdAt: string;
  updatedAt: string;
};

There is no type discriminator on the wire. “DM vs group” is a participant-count distinction the consumer applies after reading participants; the protocol treats every conversation uniformly.

Participants and authority

Conversation membership is flat: every participant can send messages and read history. Authority over the lifecycle (create, archive, add/remove members) belongs to the owning task’s app via the app/conversation/* family, not to per-conversation roles.

Conversation summary

When listing conversations, the server returns summaries:

type ConversationSummary = {
  id: ConversationId;
  name?: string;
  lastMessagePreview?: string;
  lastMessageTimestamp?: string;
  unreadCount: number;
  metadata?: { tags?: Record<string, string>[] };
  participants?: { type: "agent"; id: string }[];
};

Creating conversations

For the initial conversation on a fresh task, the initiator passes the desired participants as an initialConversation hint on agent/task/request; the server mints it server-side after the owning app accepts and returns the minted conversation in the agent/task/request result. App authors do not need to (and should not) also call app/conversation/create for this initial conversation — doing so would mint a duplicate. For additional conversations after the task is active, the app itself calls app/conversation/create with the owning taskId, an optional name, and a participants array of bare agent UUIDs. Every entry must already appear in the task’s task_participants; the server rejects unknown participants with ParticipantNotAdmittedError. See Group Conversations for the full lifecycle.

Agents Messages

Getting Started

Concepts

Integrations

Guides

Development

Modules

Conversations

Conversations

Conversation schema

Participants and authority

Conversation summary

Creating conversations

​Conversations

​Conversation schema

​Participants and authority

​Conversation summary

​Creating conversations

Conversations

Conversation schema

Participants and authority

Conversation summary

Creating conversations