Queue

​

Overview

​

CLI commands

meshagent room queue --help
meshagent room queue list --room myroom
meshagent room queue size --room myroom --queue my-queue
meshagent room queue send --room myroom --queue my-queue --json '{"payload":"Hello World!"}'
meshagent room queue receive --room myroom --queue my-queue
meshagent room queue send-mail --room myroom --queue my-queue --from support@example.com --subject "Support request" --body "Please review this."

​

Why use the Queues API?

• Decouple producers and consumers when work should happen later.
• Build lightweight background workflows without adding another queueing system.
• Coordinate multi-agent jobs where one participant produces work and another consumes it.

​

How it works

​

Permissions and grants

• list controls queue discovery
• send can be narrowed to specific queue names
• receive can be narrowed separately to specific queue names

​

API reference

​

list()

meshagent room queue list \
  --room myroom

queues = await room.queues.list()

const queues = await room.queues.list();

const queues = await room.queues.list();

final queues = await room.queues.list();

var queues = await room.Queues.List();

• Returns: An array of queue objects, each with a name and size.

​

open(name)

await room.queues.open(name="my-queue")

await room.queues.open("my-queue");

await room.queues.open("my-queue");

await room.queues.open("my-queue");

await room.Queues.Open("my-queue");

• Parameters:
  • name: Queue name.

​

send(name, message, create=True)

meshagent room queue send \
  --room myroom \
  --queue my-queue \
  --json '{"foo":"bar"}'

await room.queues.send(name="my-queue", message={"foo": "bar"}, create=True)

await room.queues.send("my-queue", { foo: "bar" }, { create: true });

await room.queues.send("my-queue", { foo: "bar" }, { create: true });

await room.queues.send("my-queue", {"foo": "bar"}, create: true);

var message = new Dictionary<string, object?> { ["payload"] = "Hello World!" };
await room.Queues.Send("my-queue", message, create: true);

• Parameters:
  • name: Queue name.
  • message: JSON-serializable payload.
  • create: When true, create the queue if it does not already exist.

​

Queue size from the CLI

meshagent room queue size \
  --room myroom \
  --queue my-queue

​

Send email-shaped work from the CLI

meshagent room queue send-mail \
  --room myroom \
  --queue my-queue \
  --from support@example.com \
  --subject "Support request" \
  --body "Please review this."

• prompt: string or typed content items for the next turn
• content: typed content items that should be passed through directly
• path: explicit thread path for the work item
• model, instructions, tools, sender_name: optional turn settings

​

Structured agent payloads

• Think of prompt as “text the agent should read”.
• Think of content as “input items the agent should receive”.
• Use prompt when you want a room:///... text file read from room storage and inlined into the turn as text before the turn starts.
• Use content when you want a room:///... file passed through as a file item in the turn input instead of being converted into text.
• content does not create or update room artifacts by itself. It only defines the turn input that the queue consumer receives.
• prompt can be plain text, typed content, or typed content that includes room:///... files. You only need a room file when you want to pull existing room content into the prompt.
• path can use UTC time tokens such as {YYYY}, {MM}, {DD}, {HH}, {mm}, and {SECOND}.

1. Plain text prompt

meshagent room queue send \
  --room myroom \
  --queue support-jobs \
  --json '{"prompt":"Summarize the current support backlog and highlight urgent issues."}'

2. Prompt that reads a room file and turns it into text

meshagent room queue send \
  --room myroom \
  --queue support-jobs \
  --json '{"path":"dataset://threads/support/{YYYY}/{MM}/{DD}/{HH}/{mm}/summary","prompt":[{"type":"file","url":"room:///prompts/support-summary.md"},{"type":"text","text":"Summarize the current support backlog and highlight urgent issues."}]}'

3. Content that preserves the room file as a file input

meshagent room queue send \
  --room myroom \
  --queue support-jobs \
  --json '{"content":[{"type":"file","url":"room:///docs/report.md"}]}'

​

receive(name, create=True, wait=True)

meshagent room queue receive \
  --room myroom \
  --queue my-queue

message = await room.queues.receive(name="my-queue", create=True, wait=True)

const message = await room.queues.receive("my-queue", { create: true, wait: true });

const message = await room.queues.receive("my-queue", { create: true, wait: true });

final message = await room.queues.receive("my-queue", create: true, wait: true);

var received = await room.Queues.Receive("my-queue", create: true, wait: true);

• Parameters:
  • name: Queue name.
  • create: When true, create the queue if it does not already exist.
  • wait: When true, wait until a message is available.
• Returns: A JSON payload, or null if the queue is empty and wait=False.

​

drain(name)

await room.queues.drain(name="my-queue")

await room.queues.drain("my-queue");

await room.queues.drain("my-queue");

await room.queues.drain("my-queue");

await room.Queues.Drain("my-queue");

• Parameters:
  • name: Queue name.

​

close(name)

await room.queues.close(name="my-queue")

await room.queues.close("my-queue");

await room.queues.close("my-queue");

await room.queues.close("my-queue");

await room.Queues.Close("my-queue");

• Parameters:
  • name: Queue name.

​

Queue

• name: Queue name.
• size: Queue length at the time of retrieval.

​

Related guides

• Room API Overview
• Messaging API
• Service YAML