What You’ll Learn
This guide shows you how to automate agent workflows using Scheduled Tasks powered by Celery RedBeat. Your agents can run automatically on specific schedules, saving time and ensuring consistent execution.Prerequisites:
- Admin role in Junis (for creating schedules)
- At least one configured agent (Orchestrator recommended)
- Understanding of basic cron syntax (optional, for CRON schedules)
What are Scheduled Tasks?
Scheduled Tasks enable you to run agent workflows automatically at specific times or intervals without manual triggering.Real-World Example
Without Scheduled Tasks:- ⏰ Time savings: No manual execution needed
- 📊 Consistency: Same task runs at exact same time
- 📝 History tracking: All execution results saved in sessions
- 🔄 Flexibility: Adjust schedules without code changes
How Scheduling Works
Architecture Overview
Junis uses Celery (distributed task queue) + RedBeat (dynamic scheduler) + Redis (storage) for robust scheduling.Key Components
Celery
Distributed Task QueueManages background task execution across multiple workers.
RedBeat
Dynamic SchedulerStores schedules in Redis, allows runtime modification without restart.
PostgreSQL
Schedule StorageStores schedule definitions, execution history, metadata.
Redis
Metadata CacheStores RedBeat scheduler state, provides fast access.
Execution Flow
1
Schedule Creation
Admin creates schedule via UI or API. Schedule saved to PostgreSQL + registered with RedBeat.
2
RedBeat Monitoring
RedBeat continuously checks Redis for schedules due to run. Uses distributed lock to prevent duplicate execution.
3
Task Execution
When scheduled time arrives, RedBeat triggers Celery worker to execute task.
4
Agent Processing
Celery worker calls Orchestrator agent with saved prompt. Agent processes using configured workflow.
5
Result Storage
Agent response saved to chat session. Execution status recorded in
scheduled_task_runs table.Schedule Types
Junis supports 5 schedule types for different use cases:- ONCE
- DAILY
- WEEKLY
- MONTHLY
- CRON
One-Time ExecutionRun task immediately or at a specific future time.Use Cases:Behavior:
- Reminder at specific date/time
- One-off report generation
- Testing scheduled workflows
- If
execute_atnot provided: Runs immediately - If
execute_atprovided: Runs at specified time - Automatically disabled after execution
Setting Up Scheduled Tasks
Step-by-Step Guide
1
Navigate to Schedules Page
- Log in to Junis as Admin
- Go to Team Management → Task Planning
- Click “New Schedule” or ”+ Add Schedule” button
2
Configure Basic Information
Schedule Name:
- Descriptive name (e.g., “Daily Sales Report”)
- Must be unique within your organization
- Used for identification in schedule list
- The instruction/question sent to Orchestrator
- Same as typing in chat interface
- Can include specific parameters, agent names, etc.
3
Choose Schedule Type
Select one of the 5 schedule types:
- ONCE
- DAILY
- WEEKLY
- MONTHLY
- CRON
Immediate or Future:
- Leave blank: Runs immediately
- Set date/time: Runs at specific future time
4
Configure Session Settings
Two Options:
- New Session (Recommended)
- Existing Session
Create fresh session for each executionPros:
- ✅ Clean slate each time
- ✅ Easy to find specific execution results
- ✅ No context pollution from previous runs
- Daily/weekly/monthly reports
- Independent analysis tasks
- One-off scheduled actions
- Auto-generated:
Scheduled: {schedule_name} - {timestamp} - Example:
Scheduled: Daily Sales Report - 2025-01-15 08:00
5
Save and Activate
- Review all settings
- Toggle “Enabled” switch to ON
- Click “Create Schedule” button
- Schedule saved to database
- RedBeat registers schedule in Redis
- Next run time calculated and displayed
- Schedule appears in schedule list
Monitoring Scheduled Tasks
Schedule List View
Location: Admin → Schedules Columns Displayed:| Column | Description | Example |
|---|---|---|
| Name | Schedule name | ”Daily Sales Report” |
| Type | Schedule type | DAILY, WEEKLY, CRON |
| Status | Enabled/Disabled | 🟢 Enabled / 🔴 Disabled |
| Next Run | Next execution time | ”2025-01-16 08:00:00” |
| Last Run | Last execution time | ”2025-01-15 08:00:00” |
| Run Count | Total executions | 142 |
| Actions | Quick actions | Edit, Delete, Run Now, View History |
- 🟢 Enabled: Schedule active, will run at next scheduled time
- 🔴 Disabled: Schedule paused, will not run automatically
- ⏳ Running: Currently executing
- ✅ Completed: ONCE schedule that has finished
Execution History
Viewing History:- Find schedule in list
- Click “View History” or history icon
- See list of all executions
| Column | Description |
|---|---|
| Status | PENDING, RUNNING, SUCCESS, FAILED |
| Started At | Execution start timestamp |
| Completed At | Execution end timestamp |
| Duration | Time taken to complete |
| Session Link | Direct link to chat session with results |
| Error Message | Error details (if failed) |
- ⏳ PENDING: Task queued, waiting for worker
- ▶️ RUNNING: Currently executing
- ✅ COMPLETED: Completed successfully
- ❌ FAILED: Execution failed (see error message)
Viewing Execution Results
Method 1: From Execution History:- Click session link in execution record
- Opens chat session with that execution’s conversation
- View agent’s response and any generated outputs
- Go to Chat → Sessions
- Filter by schedule name or date
- Sessions named
Scheduled: {schedule_name} - {timestamp}
- User message:
[Scheduled] {prompt} - Agent response: Full conversation output
- Tool calls: Any tools used during execution
- Timestamps: Exact execution time
Managing Scheduled Tasks
Editing Schedules
1
Open Edit Dialog
In schedule list, click Edit icon (pencil) next to schedule name.
2
Modify Settings
Can Change:
- Schedule name
- Prompt
- Schedule type and configuration
- Session settings
- Organization (schedules are org-specific)
- Creator (for audit purposes)
3
Save Changes
Click “Save” → Schedule updated in database and RedBeat re-registers with new settings.
- Next run time recalculated based on new schedule
- Existing execution history preserved
- Currently running execution not affected (runs with old settings)
Enabling/Disabling Schedules
Toggle Switch:- In schedule list, use toggle switch in Status column
- Or click schedule name → Toggle “Enabled” switch in details
- Temporary pause (e.g., during maintenance)
- Seasonal schedules (only needed certain times of year)
- Testing/debugging (disable production schedule while testing)
- ❌ Will not run automatically
- ✅ All settings and history preserved
- ✅ Can re-enable anytime without reconfiguration
Running Schedules Manually
“Run Now” Button:- Executes schedule immediately, ignoring schedule time
- Does not affect next scheduled run time
- Useful for testing or one-off manual execution
- Click “Run Now” button next to schedule
- Confirmation dialog appears
- Click “Confirm”
- Task executes immediately
- New execution record created in history
- Testing new schedule before activation
- Running report outside normal schedule
- Recovering from missed execution
Deleting Schedules
Steps:- Click Delete icon (trash can) next to schedule
- Confirmation dialog: “Are you sure you want to delete this schedule?”
- Type schedule name to confirm (security measure)
- Click “Delete Permanently”
- ✅ Schedule definition from database
- ✅ RedBeat entry from Redis
- ✅ All execution history records
- ❌ Chat sessions (preserved for reference)
- If you might need the schedule later, disable instead of delete
- Keeps all history and settings intact
Use Cases & Examples
1. Daily Sales Report
Scenario: Generate sales summary every morning at 8 AM for previous day’s data. Configuration:- 8:00 AM: Orchestrator receives prompt
- Orchestrator calls SalesAnalysisAgent
- Agent queries sales database for yesterday’s data
- Agent generates formatted report
- Report saved to new session
- Team opens chat session to view report
- No manual data gathering every morning
- Consistent report format
- Historical archive of daily reports in chat sessions
2. Weekly Team Sync Summary
Scenario: Every Friday at 5 PM, summarize week’s activities and prepare for Monday meeting. Configuration:- Friday 5:00 PM: Orchestrator processes prompt
- Orchestrator calls ProjectManagementAgent
- Agent queries GitHub, Jira, Slack for activity data
- Agent generates meeting agenda
- Result appended to continuous “Weekly Sync” session
- Team reviews agenda in chat before Monday meeting
- Automatic weekly meeting preparation
- Continuous thread shows historical summaries
- Agent learns patterns over time (same session)
3. Real-Time Monitoring (Every 15 Minutes)
Scenario: Monitor website uptime and alert on issues every 15 minutes during business hours. Configuration:- Every 15 minutes (9 AM-5 PM, Mon-Fri): Check website
- Orchestrator calls MonitoringAgent
- Agent makes HTTP requests to check endpoints
- If issues detected:
- Agent sends alert via Slack MCP
- Agent creates Jira ticket via GitHub MCP
- Status logged to continuous monitoring session
- Proactive issue detection
- Real-time alerts to team
- Complete monitoring history in one session
4. Monthly Financial Close
Scenario: On 1st of each month, generate financial summary for previous month. Configuration:- 1st of month, 6:00 AM: Orchestrator processes prompt
- Orchestrator calls FinancialAnalysisAgent
- Agent queries accounting database for previous month
- Agent calculates metrics and trends
- Agent generates PDF report via claude_pdf_processor
- Report saved to new session
- CFO reviews report in chat or downloads PDF
- Automated monthly close process
- Consistent financial reporting
- Early morning execution ensures reports ready for business day
5. Dynamic Content Curation
Scenario: Twice daily (8 AM, 6 PM), curate trending industry news and share with team. Configuration:- 8 AM & 6 PM: Orchestrator processes prompt
- Orchestrator calls ContentCuratorAgent
- Agent uses Firecrawl MCP to scrape industry news sites
- Agent uses google_search_web to find trending topics
- Agent summarizes top 5 stories
- Agent posts summary to Slack via Slack MCP
- Summary also saved to continuous news curation session
- Team stays informed without manual research
- Twice daily updates (morning and evening)
- Historical archive of curated news
Troubleshooting
Schedule not executing at expected time
Schedule not executing at expected time
Symptom: Schedule is enabled but doesn’t run at scheduled timePossible Causes:
- Celery Worker offline: Worker not running to pick up tasks
- RedBeat not running: Scheduler not monitoring schedules
- Redis connection issue: RedBeat can’t access schedule metadata
- Timezone mismatch: Schedule configured in different timezone
- Go to Admin Dashboard → System Health
- Check “Celery Worker Status” (should show “Active”)
- Check “Schedule Processor Status” (should show “Running”)
- Check “Redis Connection” (should show “Connected”)
- Admin → Schedules
- Find the schedule in the list
- Check “Status” column shows “Enabled”
- Check “Last Run At” has recent timestamp
- All schedules use UTC timezone by default
- If schedule should run at 8 AM local time (e.g., KST = UTC+9):
- Set hour to
-1from local (7 for 8 AM KST, which is 23 UTC previous day) - Or use cron with timezone awareness (future feature)
- Set hour to
Execution fails with error
Execution fails with error
Symptom: Execution status shows FAILED in historyPossible Causes:
Test Manually:
- Prompt error: Invalid or malformed prompt
- Agent not found: Referenced agent doesn’t exist
- Permission issue: Agent lacks required permissions/tools
- External service down: Tool API unavailable (Salesforce, DataLab, etc.)
- Timeout: Execution took too long
- Go to Schedule → View History
- Click failed execution record
- Read error message in details
| Error Message | Cause | Solution |
|---|---|---|
| ”Agent ‘XYZ’ not found” | Agent deleted or renamed | Update schedule with correct agent name |
| ”Tool ‘ABC’ not available” | Agent doesn’t have required tool | Add tool to agent configuration |
| ”Timeout after 300s” | Execution took too long | Simplify prompt or increase timeout |
| ”API rate limit exceeded” | Too many API calls | Reduce schedule frequency or batch requests |
| ”Permission denied” | Agent lacks permissions | Check agent tools and API keys |
- Copy prompt from schedule
- Open chat with Orchestrator
- Paste prompt manually
- Observe execution and error details
- Fix issues before re-enabling schedule
Duplicate executions
Duplicate executions
Symptom: Schedule runs multiple times at same scheduled timePossible Causes:
- Multiple Celery Workers: Different workers pick up same task
- RedBeat lock issue: Distributed lock not working
- Schedule duplicated: Multiple schedules with same name
- Admin → Schedules
- Look for schedules with the same name but different IDs
- Select duplicates and delete all but one
- Click “Save Changes”
- Admin Dashboard → System Health
- Check “Schedule Locking” status (should show “Enabled”)
- If disabled, contact support to re-enable
- Admin Dashboard → Workers
- Verify only 1 Celery Worker is registered (recommended for schedule processing)
- If multiple workers, reduce to single worker via Admin settings
Next run time not updating
Next run time not updating
Symptom:
next_run_at stays same after executionPossible Causes:- ONCE schedule: Single execution completed, schedule disabled
- Database update failure: DB transaction failed after execution
- Schedule calculation error: Next run time calculation bug
- ONCE schedules: Expected behavior (automatically disabled)
- Other types: Should update to next scheduled time
- Admin → Schedules
- Find the schedule with stale
next_run_at - Click Edit
- Toggle “Enabled” to OFF, then click Save
- Toggle “Enabled” to ON again, then click Save
- System automatically recalculates
next_run_atbased on schedule type
- Schedule name
- Current
next_run_atvalue - Expected next run time
- Support team will update schedule metadata
Cannot see execution results
Cannot see execution results
Symptom: Execution shows SUCCESS but can’t find results in chatPossible Causes:
- Session ID mismatch: Results saved to unexpected session
- Organization filter: Viewing different organization’s chat
- Session not created: New session creation failed
- Admin → Schedules → View History
- Find successful execution
- Click session link → Opens exact session with results
- Admin → Schedules → View History
- Find the execution record
- Check “Session ID” field (should be non-empty)
- If empty, execution created no session (check execution error in details)
- If filled, click the session link to view chat history
- Ensure you’re viewing correct organization in UI
- Use organization switcher (top right) to change if needed
- Schedule executions only visible to same organization
Best Practices
Schedule Design
✅ DO:
- Use descriptive schedule names (“Daily Sales Report” not “Report1”)
- Write clear, specific prompts (avoid ambiguity)
- Test prompts manually in chat before scheduling
- Start with ONCE type to test, then convert to recurring
- Use new sessions for independent tasks (reports, analysis)
- Use existing sessions for continuous threads (monitoring, iterative analysis)
- Set reasonable execution frequency (avoid excessive API usage)
- Document complex schedules in schedule description
Prompt Writing Tips
Effective Scheduled Prompts:-
Be Specific:
-
Include Context:
-
Specify Output Format:
-
Use Relative Time:
-
Chain Actions:
Monitoring & Maintenance
Regular Checks (Weekly):- Review execution history for failures
- Check success rate (aim for >95%)
- Monitor execution duration (watch for increasing times)
- Review session list for outdated sessions
- Audit schedules for relevance (disable unused)
- ⬆️ Increase frequency: If insights/reports needed sooner
- ⬇️ Decrease frequency: If data doesn’t change often enough
- 🔄 Change timing: If current time causes conflicts or peak load
- ⏸️ Disable temporarily: During maintenance, holidays, or testing
Security Considerations
Access Control:- Only admins can create/edit/delete schedules
- Schedule executions run with creator’s permissions
- Agents inherit organization’s tool and MCP access
- Execution results visible to all organization members (via chat)
- All schedule creations/modifications logged
- Execution history preserved (start time, end time, status)
- Session links provide full conversation history
- Review audit logs regularly for unusual activity
Advanced Configuration
Conditional Scheduling (Workaround)
Goal: Run schedule only if certain condition met (e.g., only if new data available). Approach: Use agent instruction to check condition first. Example Prompt:- Agent checks data source
- If data exists: Proceeds with analysis
- If no data: Returns early with “No new data” message
- Execution still recorded (SUCCESS status) but no actual work done
Multi-Organization Schedules
Challenge: Run same schedule across multiple organizations. Current Limitation: Schedules are organization-scoped, not global. Workaround:- Create schedule in Organization A
- Export schedule configuration (copy JSON)
- Switch to Organization B
- Create new schedule with same configuration
- Repeat for other organizations
Scheduled Workflows with Sub-Agents
Use Case: Schedule complex workflow involving multiple agents. Example:- Routing to appropriate sub-agents (Sequential workflow)
- Passing context between agents
- Error handling for each step
- Final result aggregation
- Single schedule triggers entire workflow
- Orchestrator manages complexity
- Results appear in one chat session
Performance & Scalability
Schedule Limits
Recommended Limits (per organization):| Schedule Type | Recommended Max | Notes |
|---|---|---|
| CRON (frequent) | 10 | Every minute/15 minutes |
| DAILY | 50 | Once per day |
| WEEKLY | 20 | Once per week |
| MONTHLY | 10 | Once per month |
| ONCE | Unlimited | Auto-disabled after execution |
- Celery Worker has finite capacity
- Concurrent executions may slow down system
- Redis storage grows with more schedules
- Database queries increase with execution history
Optimization Tips
Performance Best Practices:
- Stagger schedules (avoid all at 8:00 AM, spread across minutes)
- Use longer intervals for non-critical schedules
- Clean up old execution history periodically
- Disable unused schedules instead of deleting (can re-enable)
- Monitor Celery Worker resource usage
- Use CRON wisely (avoid excessive frequency)
Monitoring Celery Health
Check Worker Status via Admin UI:- Admin Dashboard → System Health
- View “Active Workers” section showing worker count and status
- View “Registered Tasks” count
- View “Worker Memory Usage” graphs
- Admin Dashboard → Metrics
- Check “Cache Memory Usage” (Redis)
- Check “Queue Size” showing pending schedules
- Check “Execution Success Rate” showing schedule health
- Date range
- Schedule name (optional)
- Type of report needed (execution history, timeline, resource usage)
What’s Next?
Tools Overview
Learn about tools that agents can use
RAG Setup
Upload documents for agent knowledge
Payment System
Set up USDC payments for premium agents
Organization Features
Manage teams and multi-organization setups
Additional Resources
- Celery Documentation: docs.celeryproject.org
- RedBeat Scheduler: redbeat.readthedocs.io
- Cron Expression Generator: crontab.guru
- Junis API Reference: api.junis.ai/docs
Support: For scheduling issues, contact Junis support at [email protected].
