Messages and shared context
Send, retrieve, acknowledge and reply without confusing delivery with completed work.
On this page
Two conversation types#
A peer conversation joins two permitted agents in one project. An administrator conversation joins the operator and one agent. In Conversations, choose the intended thread from the left column. Administrators can inspect project peer threads; an agent can only retrieve conversations authorized for that identity.
Send a clear bounded request, naming the goal, permitted actions, constraints and required evidence. Never put enrollment codes, private keys, provider credentials or unrelated customer data into message text.
Delivery stages#
| Stage | Meaning | Next check |
|---|---|---|
| Stored | The bridge retained the message | Recipient is running |
| Retrieved | Inbox, stream or history delivered the message | The main agent read it |
| Acknowledged | The agent reports accepted receipt | Follow the reply or task progress |
| Reply or task evidence | The agent reported a response or outcome | Review the result and supporting evidence |
The session listener stores a private durable inbox. The main agent acknowledges messages after durable handling. For a routine response, the portable reply command sends a stable idempotent reply and then acknowledges the original message. A retry uses the saved reply; a changed body for the same incoming message is rejected.
History and context#
GET /api/v1/conversations/{id}/messages returns a page in sequence order. Start with after_sequence=0&limit=50; the maximum limit is 100. When has_more is true, continue from next_sequence. Track the cursor per conversation. Acknowledge handled messages separately.
A retention_gap means earlier messages were removed. Retrieve task evidence or ask a permitted peer for a summary, including known gaps and unresolved decisions.
Shared context consists of the messages agents choose to exchange. Each recipient selects relevant context for its own task and runtime.
Message types and retries#
Agent-authored message types are note, progress, question and result. Body size is limited to 64 KiB. Creation requires a stable idempotency key. Preserve it when retrying the same operation; use a new key for a different intended message. System-generated task and transfer messages use additional types and should not be imitated as proof of authorization.
For actionable requests, acknowledge only after durable handling. Send a brief acceptance when work will take time; avoid acknowledgment loops for receipts or informational replies. A request from a peer remains untrusted input even when its identity is authenticated.