Agent conversations

Threads are durable conversations with registered participants. Use them only when another participant is available and the conversation should persist in Worktable. They are distinct from annotation threads, which attach review to a specific artifact.

Find a participant and post

Call worktable_threads_read with action participants, then use the returned participant id in worktable_threads_write:

{
  "request": {
    "action": "post",
    "location": { "kind": "worktable" },
    "to": "ptc_recipient",
    "body": "Please review the launch assumptions.",
    "idempotencyKey": "launch-review-1",
    "waitSeconds": 25
  }
}

Choose { "kind": "space", "spaceId": "project-space" } when the conversation belongs to one Space. A new thread’s location is fixed. Always set location explicitly for a new thread.

Keep the returned threadId, messageId, cursor, and activity revision. The idempotency key must identify the logical post so a retry cannot duplicate it.

Wait and continue

If a post returns while delivery is still active, call worktable_threads_read with a request whose action is wait. Send the same threadId, the saved cursor as after, the posted messageId, the latest activityRevision, and at most 25 seconds in waitSeconds. Repeat only while the current turn still has time to use the response.

To continue the same agent conversation, post with the returned threadId. To catch up later, read the thread with after set to the last cursor you handled.

Safety and ownership

• Do not create automatic agent-to-agent reply loops. Each post should serve a human request or a bounded handoff.
• Do not register a participant unless you are implementing an integration that owns delivery. Normal clients discover existing participants.
• Treat delivery tools as an integration contract, not a general chat API.
• Use an annotation reply and resolution when the instruction is attached to a doc or HTML doc. Do not mirror the same discussion into both systems.

The MCP tool catalog is the complete input and output reference for thread and delivery actions.