> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Jobs
> Scheduled tasks that run automatically
## What are Jobs?
**Jobs** are scheduled tasks that run automatically at specified times or intervals, without requiring user interaction. They enable your agent to perform automated operations like sending reports, cleaning up data, or monitoring systems.
A scheduled assistant - tasks that run on their own schedule, like daily reports or weekly cleanup
Two ways to create jobs - pre-defined with LuaJob or dynamically with Jobs API.
## Why Jobs?
Run tasks automatically without user requests
Send reminders, reports, and updates at the right time
Clean up old data, monitor health, maintain systems
Send daily summaries, weekly reports, monthly newsletters
## Two Types of Jobs
**Static jobs defined at agent setup**
```typescript theme={null}
import { LuaJob, User } from 'lua-cli';
const dailyReport = new LuaJob({
name: 'daily-sales-report',
schedule: {
type: 'cron',
expression: '0 9 * * *' // Every day at 9 AM
},
metadata: {
userId: 'user_abc123' // Store user ID in metadata
},
execute: async (job) => {
// ⚠️ Pre-defined jobs have NO conversational context
// Get user by ID from metadata
const user = await User.get(job.metadata.userId);
await user.send([{
type: 'text',
text: 'Your daily report is ready!'
}]);
}
});
```
**Best for:**
* Daily/weekly reports
* Cleanup tasks
* System monitoring
* Recurring notifications
**No Context:** LuaJob executes outside conversations. Use `User.get(userId)` with ID from metadata.
**Jobs created on-demand from tools (has user context!)**
```typescript theme={null}
import { Jobs } from 'lua-cli';
// Inside a tool's execute function
const job = await Jobs.create({
name: 'user-reminder',
metadata: { message: 'Meeting in 10 minutes' },
schedule: {
type: 'once',
executeAt: new Date(Date.now() + 600000)
},
execute: async (jobInstance) => {
// ✅ Dynamic jobs automatically have user context
const user = await jobInstance.user(); // No userId needed!
await user.send([{
type: 'text',
text: jobInstance.metadata.message
}]);
}
});
```
**Best for:**
* User-requested reminders
* Follow-up messages
* One-time notifications
* Context-specific tasks
**Has Context:** Dynamic jobs created in tools automatically know which user triggered them. Use `jobInstance.user()` - no userId needed!
## Schedule Types
### Cron (Specific Times)
```typescript theme={null}
schedule: {
type: 'cron',
expression: '0 9 * * *' // Every day at 9 AM
timezone?: 'America/New_York' // Optional timezone
}
```
**Common patterns:**
* `'0 9 * * *'` - Every day at 9 AM
* `'0 9 * * 1'` - Every Monday at 9 AM
* `'0 0 1 * *'` - First of every month at midnight
* `'*/15 * * * *'` - Every 15 minutes
### Interval (Regular Periods)
```typescript theme={null}
schedule: {
type: 'interval',
seconds: 3600 // Every hour
}
```
**Common intervals:**
* `300` - Every 5 minutes
* `3600` - Every hour
* `86400` - Every day
### Once (One-time)
```typescript theme={null}
schedule: {
type: 'once',
executeAt: new Date('2025-12-25T09:00:00Z')
}
```
**Use for:**
* Specific future date/time
* User-requested reminders
* Follow-up messages
## Example Use Cases
Send sales summaries, analytics, or metrics every day
Delete old data, archive records, maintain database
Remind users about appointments, tasks, or deadlines
Check system health, API status, or thresholds
Send follow-up messages after support tickets
Proactive updates about orders, shipments, or events
## Adding Jobs to Your Agent
Pre-defined jobs are added to your LuaAgent:
```typescript theme={null}
import { LuaAgent } from 'lua-cli';
import dailyReport from './jobs/daily-report';
import weeklyCleanup from './jobs/weekly-cleanup';
export const agent = new LuaAgent({
name: "my-agent",
persona: "...",
skills: [...],
// Add scheduled jobs
jobs: [
dailyReport,
weeklyCleanup
]
});
```
Dynamic jobs are created from within tools using the Jobs API.
## Testing Jobs
```bash theme={null}
lua test
# Select: Job → daily-report
# Job executes immediately for testing
```
## Next Steps
Pre-defined jobs documentation
Dynamic job creation documentation
Learn about LuaAgent configuration
Understand HTTP endpoints