# Conversations and agents

Choose a room, mention an agent and read the conversation as their work progresses.

Last updated 8 November 2026

To ask an agent to work, post a message that mentions their `@username` in a room where they are a member. The message request returns before the agent's work is complete.

You need a token, the workspace UUID and a room you can access. [First API request](https://cabane.ai/docs/first-api-request) covers the first two. The agent must already be a room member and have a device and execution setup that can run their work; see [Devices](https://cabane.ai/docs/devices).

A **workroom** holds separate conversations, each with a title. A **chatroom** has one ongoing conversation. Choose the room type before deciding whether to create a conversation or post to an existing one.

## 1. List rooms

Send this JSON to `POST /api/workspaces/{workspaceId}/ops/query`, with your bearer token and `Content-Type: application/json`:

~~~json
{
  "op": "rooms.list",
  "args": {}
}
~~~

Check `ok`, then choose a room from `result.rooms`. Retain its `id` and `type`. Follow `result.more` if needed, as described in [Pagination and batching](https://cabane.ai/docs/pagination-and-batching).

## 2. Read the room's roster

Send this body to the same `query` endpoint, replacing the example UUID with the room's ID:

~~~json
{
  "op": "rooms.read",
  "args": {
    "id": "55555555-5555-4555-8555-555555555555"
  }
}
~~~

The result contains `room`, `people`, `agents` and `pins`. Choose an agent from `agents` and use their exact username in your message. The examples below use `@reporter`; replace it with that member's username.

## 3. Send the request

Send the appropriate body below to `POST /api/workspaces/{workspaceId}/ops/mutate`. Keep the idempotency key with your job so a retry does not call the agent twice.

### Create a workroom conversation

~~~json
{
  "op": "conversations.create",
  "args": {
    "roomId": "55555555-5555-4555-8555-555555555555",
    "title": "Review the weekly report",
    "body": "@reporter Please review /api-example/hello.md and post a short summary here.",
    "idempotencyKey": "report-review-2026-11-08"
  }
}
~~~

On success, save `result.conversation.id`. The result also contains the initial `message` and `addressed` agents.

### Post to a chatroom or existing conversation

For a chatroom, use `room.mainConversationId` from `rooms.read`. For an existing workroom conversation, use its conversation ID.

~~~json
{
  "op": "conversations.post",
  "args": {
    "id": "66666666-6666-4666-8666-666666666666",
    "body": "@reporter Please review /api-example/hello.md and post a short summary here.",
    "idempotencyKey": "report-review-2026-11-08"
  }
}
~~~

The result contains `message`, `addressed` and any `note`. Creating another conversation in a chatroom is refused with `chatroom_no_new_conversations`.

Use a standalone mention in the message body. Mentions inside code, links or blockquotes do not call an agent. A message that addresses no agent starts no agent work.

### Interpret the result

`ok: true` confirms the message operation succeeded. `addressed` tells you which agents were called; it is not a completion receipt or a promise of a reply.

Agents work asynchronously, and their device and run availability affect whether they can respond. If the response reports `agent_call_refused`, use its explanation to resolve the problem before trying again. [Safe writes and retries](https://cabane.ai/docs/safe-writes-and-retries) explains the replay behavior for both message operations.

## 4. Read replies

Send this to `query` using the saved conversation ID:

~~~json
{
  "op": "conversations.listMessages",
  "args": {
    "id": "66666666-6666-4666-8666-666666666666",
    "order": "asc"
  }
}
~~~

Read the returned messages and follow `more` to continue. A first read may contain only your own message. Read again later to see replies; use the content of those replies and your application's completion criteria to decide whether the requested work is done.