Skip to main content
Queues and scheduled tasks are the main building blocks for background and recurring work in MeshAgent.

​
Run a queue-backed agent

Start an agent that listens on a room queue: 
meshagent setup
meshagent rooms create --name myroom --if-not-exists

meshagent process join \
  --room myroom \
  --agent-name queue-agent \
  --channel queue:support-jobs \
  --storage \
  --web-search \
  --rule "You are a queue-based support operations agent. Process queued jobs without asking follow-up questions unless the job explicitly asks for interactive behavior."
This gives you one agent that consumes background work from the support-jobs queue.

​
Send work into the queue

Once the agent is running, enqueue a job: 
meshagent room queue send \
  --room myroom \
  --queue support-jobs \
  --json '{"prompt":"Summarize the latest support backlog and save a report."}'
This is the main queue pattern:
  • the queue holds the work item
  • the agent consumes it
  • the agent runs without needing a live chat message
For MeshAgent queue consumers such as meshagent process queue channels, the payload can also be structured. For example, you can provide typed prompt content and a thread template: 
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."}]}'
Use prompt when you want room prompt files such as room:///prompts/support-summary.md resolved into text before the turn starts. Use content when you want typed file items preserved as file inputs for the agent.

​
Schedule recurring work

Scheduled tasks enqueue work on a cron schedule. Add a task that sends one job into the same queue every day: 
meshagent scheduled-task add \
  --room myroom \
  --queue support-jobs \
  --schedule "30 17 * * *" \
  --payload '{"prompt":"Generate the daily support summary and save it to storage."}'
This creates a project-level scheduled task that targets the support-jobs queue in myroom. Scheduled-task payloads use the same queue message format, so you can also send structured prompt or content payloads and thread templates when the target consumer is a MeshAgent queue channel. List scheduled tasks: 
meshagent scheduled-task list --room myroom
Update a scheduled task: 
meshagent scheduled-task update TASK_ID \
  --schedule "0 18 * * *" \
  --active
Delete a scheduled task: 
meshagent scheduled-task delete TASK_ID

​
How queues and scheduled tasks fit together

  • Queues are the delivery mechanism for asynchronous work
  • Scheduled tasks are the trigger that enqueues work on a schedule
  • Agents or services consume the queued work
That makes queues useful for one-off background jobs and scheduled tasks useful for recurring work such as daily digests, periodic reports, monitoring jobs, or imports.

​
Room scope and project scope

Queue operations are room-level operations. Scheduled tasks are managed at the project level, but they usually target a queue for a specific room. That is why the scheduled-task commands take both a queue and an optional --room.