Skip to main content

​
Overview

The QueuesClient is the Room API for simple room-scoped work queues. Use it when one participant or service needs to hand off JSON work items to another participant or service asynchronously.

​
CLI commands

Start with the CLI help, then use a few common commands:
bash
meshagent room queue --help
meshagent room queue list --room myroom
meshagent room queue send --room myroom --queue my-queue --json '{"payload":"Hello World!"}'
meshagent room queue receive --room myroom --queue my-queue

​
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

A queue stores JSON messages until a consumer receives them. Senders and receivers can be different participants or services in the same room. SDKs can list, open, send, receive, drain, and close queues, while Python auto-creates queues during send or receive when create=True.

​
Permissions and grants

The Queues API is controlled by the queues grant on the participant token. In practice:
  • list controls queue discovery
  • send can be narrowed to specific queue names
  • receive can be narrowed separately to specific queue names
See API Scopes and Packaging and Deploying Services.

​
API reference

Use the methods below to inspect queues, send JSON work items, and receive them from another participant or service in the same room.

​
list()

List the queues currently visible in the room. 
meshagent room queue list \
  --room myroom
  • Returns: An array of queue objects, each with a name and size.

​
open(name)

Create or reopen a queue explicitly. 
await room.queues.open("my-queue");
  • Parameters:
    • name: Queue name.

​
send(name, message, create=True)

Send one JSON message to a queue. 
meshagent room queue send \
  --room myroom \
  --queue my-queue \
  --json '{"foo":"bar"}'
  • Parameters:
    • name: Queue name.
    • message: JSON-serializable payload.
    • create: When true, create the queue if it does not already exist.
When the queue consumer is a MeshAgent queue channel, the payload can include turn-oriented fields such as:
  • prompt: string or typed content items for the next turn
  • content: typed content items that should be passed through directly
  • thread_id or path: explicit thread path for the work item
  • model, instructions, tools, sender_name: optional turn settings

​
Structured agent payloads

For queue-backed MeshAgent agents, prompt and content can carry typed content instead of a plain string.
  • 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.
  • thread_id and path can use UTC time tokens such as {YYYY}, {MM}, {DD}, {HH}, {mm}, and {SECOND}.
  • Legacy prompt_file payloads still work, but typed prompt items are the preferred format.
Examples:
  1. Plain text prompt
meshagent room queue send \
  --room myroom \
  --queue support-jobs \
  --json '{"prompt":"Summarize the current support backlog and highlight urgent issues."}'
This sends plain prompt text. No room file is involved.
  1. Prompt that reads a room file and turns it into text
meshagent room queue send \
  --room myroom \
  --queue support-jobs \
  --json '{"thread_id":"/threads/support/{YYYY}/{MM}/{DD}/{HH}/{mm}/summary.thread","prompt":[{"type":"file","url":"room:///prompts/support-summary.md"},{"type":"text","text":"Summarize the current support backlog and highlight urgent issues."}]}'
In this example, MeshAgent reads room:///prompts/support-summary.md from room storage and inserts that file’s UTF-8 text into the turn before the agent runs.
  1. 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"}]}'
In this example, MeshAgent keeps room:///docs/report.md as a file item in the turn input. It does not inline the file into prompt text, and it does not create a new room artifact.

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

Receive one JSON message from a queue. 
meshagent room queue receive \
  --room myroom \
  --queue my-queue
  • 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)

Remove all messages from a queue. 
await room.queues.drain(name="my-queue")
  • Parameters:
    • name: Queue name.

​
close(name)

Close a queue so it stops accepting sends or receives until reopened. 
await room.queues.close(name="my-queue")
  • Parameters:
    • name: Queue name.

​
Queue

Queue objects returned by list() include:
  • name: Queue name.
  • size: Queue length at the time of retrieval.