Skip to content

Commit 3154fef

Browse files
Golgix Auto Deploycursoragent
andcommitted
docs: add Scheduled Tasks feature documentation
Adds a new feature page covering the Scheduled Tasks side-panel, which lets users run any Agent or Assistant on a cron schedule, fixed interval, or one-shot future date: - Registers `CalendarClock` in the sidebar icon map (`lib/icons.tsx`) so the page's `icon: CalendarClock` frontmatter resolves correctly, matching the in-app tab icon. - Registers the page in `content/docs/features/meta.json` under the *Agentic AI* section. - Documents Redis as the only required infrastructure (BullMQ-backed) and links to the dedicated Redis configuration page. - Covers target/prompt configuration, the three trigger types (cron, interval, date) with the Quick presets dropdown and inline friendly-cron description, and IANA-timezone semantics including DST and the past-date no-op for one-shot triggers. - Documents per-task capabilities (Web Search, File Search, Code Execution, MCP server picks) and notes that global `librechat.yaml` toggles still apply. - Covers output handling: scheduled runs land in fresh conversations tagged `isScheduled: true`, hidden from the main chat sidebar, and surfaced via the per-task Task Runs modal; documents the Temporary Chat mode for non-persisted runs. - Documents the inline task-management controls (pause/resume, edit-in-place, history, delete) and the post-deletion visibility behavior (past runs stay filtered out of the main sidebar). - Adds a Security and Isolation section covering user-scoped data access and per-user execution context. - Adds a companion local QA checklist (`QA_TESTING_GUIDE.md`) for verifying the Next.js/Fumadocs site builds cleanly with the new page. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 8670c91 commit 3154fef

4 files changed

Lines changed: 141 additions & 0 deletions

File tree

QA_TESTING_GUIDE.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Local QA Testing Guide: LibreChat Docs (librechat.ai)
2+
3+
This guide provides step-by-step instructions to locally test the documentation updates for the **Scheduled Tasks** feature.
4+
5+
## Prerequisites
6+
7+
1. Ensure you have [Bun](https://bun.sh/) installed (version 1.0+).
8+
2. Clone and navigate to your `librechat.ai` fork directory.
9+
3. Install dependencies:
10+
```bash
11+
bun install
12+
```
13+
14+
## Test Cases
15+
16+
### 1. Build Verification
17+
**Goal:** Verify that the Next.js/Fumadocs site builds without any syntax or MDX errors.
18+
19+
- Run the build command:
20+
```bash
21+
bun run build
22+
```
23+
- **Expected Result:** The build should complete successfully without any errors about missing links, broken MDX syntax, or invalid JSON.
24+
25+
### 2. Local Development Server & Navigation
26+
**Goal:** Verify the new documentation page renders correctly and is accessible from the sidebar.
27+
28+
- Start the local development server:
29+
```bash
30+
bun dev
31+
```
32+
- Open your browser to `http://localhost:3333` (or the port specified in the terminal).
33+
- Navigate to the **Features** section in the top/side navigation.
34+
- Look under the **Agentic AI** category in the left sidebar.
35+
- **Expected Result:** You should see **Scheduled Tasks** listed under `Agents API` and before `Artifacts`.
36+
37+
### 3. Content Validation
38+
**Goal:** Ensure the content on the Scheduled Tasks page is formatted correctly and readable.
39+
40+
- Click on **Scheduled Tasks** in the sidebar.
41+
- Verify the following sections are present and correctly formatted:
42+
- **Prerequisites** (includes the Redis `.env` snippet).
43+
- **Creating a Scheduled Task** (Target, Prompt, Trigger Types).
44+
- **Timezone Support** (Explains IANA identifiers and UTC defaults).
45+
- **Per-Task Capabilities** (Tools and MCP Servers).
46+
- **Output Handling & History** (Hidden from main chat, Task Runs Modal, Temporary Chat Mode).
47+
- **Security & Isolation** (User-scoped execution).
48+
- Check that all Markdown elements (headers, bold text, code blocks, lists) render nicely according to the site's theme.
49+
50+
### 4. Link & Formatting Checks
51+
**Goal:** Check that the internal links work and formatting matches the rest of the documentation.
52+
53+
- Verify the internal link to `[Model Context Protocol (MCP)](./mcp)` works and navigates to the MCP documentation page.
54+
- Run the Prettier/Lint checks (if configured) to ensure formatting compliance:
55+
```bash
56+
bun run lint
57+
bun run prettier
58+
```
59+
- **Expected Result:** No linting or formatting errors related to `scheduled_tasks.mdx` or `meta.json`.
60+
61+
---
62+
63+
Once all tests pass, the documentation changes are ready to be marked for review on GitHub!

content/docs/features/meta.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
"skills",
99
"subagents",
1010
"agents_api",
11+
"scheduled_tasks",
1112
"artifacts",
1213
"code_interpreter",
1314
"---Search & Knowledge---",
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Scheduled Tasks
3+
icon: CalendarClock
4+
description: Run any Agent or Assistant on a cron schedule, fixed interval, or one-shot future date — completely decoupled from the active chat session.
5+
---
6+
7+
Scheduled Tasks turn an Agent or Assistant into a background worker. Define a schedule, hand it a prompt, and the task runs in its own conversation context every time it fires — with the same tools, MCP servers, web search, and code execution your interactive chats have access to.
8+
9+
Useful for repeatable work such as:
10+
11+
- Daily summaries (open PRs, tickets, news) delivered every morning
12+
- Periodic data checks via an MCP-exposed system
13+
- One-shot reminders at a specific wall-clock time
14+
- Fire-and-forget automations that post a notification via an MCP webhook tool
15+
16+
## Prerequisites
17+
18+
Scheduled Tasks are backed by [BullMQ](https://docs.bullmq.io/) and require a running Redis instance. The same Redis you already use for caching and resumable streams works — no extra service to operate.
19+
20+
```bash filename=".env"
21+
USE_REDIS=true
22+
REDIS_URI=redis://localhost:6379
23+
```
24+
25+
If Redis is not configured the backend boots normally but the UI's task definitions will never fire. See [Redis Configuration](/docs/configuration/redis) for hosted / cluster setups.
26+
27+
## Creating a Task
28+
29+
Open the **Scheduled Tasks** tab in the unified left sidebar (calendar-clock icon) and click the **+** button.
30+
31+
### Target and Prompt
32+
33+
- **Target Type**`Agent` or `Assistant`.
34+
- **Target ID** — the unique ID of an Agent / Assistant you own.
35+
- **Prompt** — the message sent to the target every time the task runs. Treated identically to a chat input.
36+
37+
### Trigger
38+
39+
Pick one of three trigger types:
40+
41+
- **Cron** — a standard 5-field expression, e.g. `0 9 * * 1-5` for _9 AM every weekday_. The task builder also ships a **Quick presets…** dropdown beneath the cron input (every minute, every 15 minutes, hourly, weekdays at 09:00, etc.); a friendly description is shown below the field when LibreChat recognizes the pattern. Power users can still type any 5-field expression directly — [crontab.guru](https://crontab.guru/) is a good visual helper.
42+
- **Interval** — a fixed delay in **milliseconds**, e.g. `3600000` for hourly.
43+
- **Date** — a one-shot execution at a specific datetime. Date triggers in the past simply produce no queued job.
44+
45+
Cron and Date triggers honor an IANA timezone (e.g. `America/New_York`, `Asia/Kolkata`). New tasks default to your browser's detected zone, and cron schedules respect Daylight Saving Time transitions for the chosen zone. Interval triggers are timezone-agnostic.
46+
47+
### Per-Task Capabilities
48+
49+
The task builder mirrors the in-chat tool picker, scoped per task rather than inherited from the target Agent's default:
50+
51+
- **Tools** — Web Search, File Search, Code Execution toggles.
52+
- **MCP Servers** — checkbox list of servers configured for your account; only the ones you tick are exposed to this task's run.
53+
54+
This makes it easy to ship narrow, least-privilege background jobs (e.g. _"only the GitHub MCP server, nothing else"_). Per-task switches can only enable capabilities that are also enabled globally in `librechat.yaml` — if an admin has disabled Web Search, the task's Web Search toggle is a no-op.
55+
56+
## Output Handling
57+
58+
Every run starts a **fresh conversation** so background activity never pollutes your interactive chat history.
59+
60+
- Scheduled-run conversations are marked `isScheduled: true` and excluded from the default conversation list.
61+
- The **History** (clock) icon on each task card opens the **Task Runs** modal listing every persisted run, newest first. Clicking an entry navigates to that conversation where you can read the output, inspect tool invocations, and continue manually if you want.
62+
- Check **Run as Temporary Chat** in the builder to skip persisting the conversation entirely — useful for fire-and-forget tasks that only need to perform a side effect. Temporary runs do not appear in the Task Runs modal.
63+
64+
## Managing Tasks
65+
66+
Each task card in the panel exposes inline controls for the most common workflows:
67+
68+
- **Pause / Resume** — pause stops a recurring task without losing its configuration or history; resume re-arms the schedule.
69+
- **Edit** — reopens the builder pre-populated with the task's current settings. Saving atomically replaces the underlying schedule.
70+
- **History** — opens the Task Runs modal described above.
71+
- **Delete** — removes the task and its scheduled job. Past run conversations keep `isScheduled: true` and remain filtered out of the main chat sidebar even after deletion; they're still accessible via their direct conversation URL.
72+
73+
## Security and Isolation
74+
75+
Scheduled Tasks are strictly bound to the user who created them. A run executes in the same security context as a manual chat from that user — file ACLs, tool permissions, and MCP server credentials all apply identically. Read / update / delete API calls are scoped to the authenticated user at the data layer, so a request for another user's task ID returns `404`.

lib/icons.tsx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ import {
7575
Import,
7676
Share2,
7777
Clock,
78+
CalendarClock,
7879
Zap,
7980
// Config & structure
8081
Variable,
@@ -156,6 +157,7 @@ const icons: Record<string, ReactElement> = {
156157
Import: <Import />,
157158
Share2: <Share2 />,
158159
Clock: <Clock />,
160+
CalendarClock: <CalendarClock />,
159161
Zap: <Zap />,
160162
Variable: <Variable />,
161163
Code: <Code />,

0 commit comments

Comments
 (0)