> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Queues and Scheduled Tasks

> Run background and recurring work with queues and scheduled tasks.

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:

```bash theme={null}
meshagent setup
meshagent rooms create 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:

```bash theme={null}
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:

```bash theme={null}
meshagent room queue send \
  --room myroom \
  --queue support-jobs \
  --json '{"thread_id":"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."}]}'
```

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 run on a cron schedule. Schedules must be at least 15 minutes apart.

Add a task that sends one job into the same queue every day:

```bash theme={null}
cat > support-summary-task.yaml <<'YAML'
version: v1
kind: ScheduledTask
schedule: 30 17 * * *
queue:
  name: support-jobs
  payload:
    prompt: Generate the daily support summary and save it to storage.
YAML

meshagent scheduled-task add \
  --room myroom \
  --file support-summary-task.yaml
```

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.

Scheduled tasks can also start a container directly by using the `container` target in the same `ScheduledTaskSpec` file:

```bash theme={null}
cat > hourly-container-task.yaml <<'YAML'
version: v1
kind: ScheduledTask
schedule: 0 * * * *
container:
  image: alpine:latest
  command: echo scheduled
YAML

meshagent scheduled-task add \
  --room myroom \
  --file hourly-container-task.yaml
```

List scheduled tasks:

```bash theme={null}
meshagent scheduled-task list --room myroom
```

Update a scheduled task:

```bash theme={null}
meshagent scheduled-task update TASK_ID \
  --file support-summary-task.yaml
```

View recent task runs:

```bash theme={null}
meshagent scheduled-task runs TASK_ID
```

Delete a scheduled task:

```bash theme={null}
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`.

## Related guides

* [Queues API](../room_api/queue): room-level queue operations
* [Process Agents](./process/overview): run one agent across chat, queue, mail, and toolkit channels
* [Projects > Scheduled Tasks](../project_admin/scheduled_tasks): create and manage scheduled tasks at the project level
* [Deploy a Process Agent](../services/deployment/process_agent_service): deployment pattern that includes scheduled work
* [CLI Reference](../reference/meshagent_cli_help): full queue and scheduled-task command reference