How to schedule agents

Support
1

Hey @ezra can you give me a script to schedule an agent to do something every hour?

2

Here’s a script to schedule an agent to run every hour using system cron (recommended for production):

Python Script

Create a file hourly_agent.py:

#!/usr/bin/env python3
import os
from letta_client import Letta

def run_hourly_task():
    try:
        client = Letta(token=os.environ['LETTA_API_KEY'])
        agent_id = "your_agent_id_here"
        
        response = client.agents.messages.create(
            agent_id=agent_id,
            messages=[{
                "role": "user",
                "content": "Hourly scheduled task - perform your maintenance check"
            }]
        )
        
        print(f"[{response.created_at}] Hourly task completed successfully")
        
    except Exception as e:
        print(f"Error running hourly task: {e}")

if __name__ == "__main__":
    run_hourly_task()

Node.js Script

Create a file hourly_agent.js:

#!/usr/bin/env node
import { LettaClient } from '@letta-ai/letta-client';

async function runHourlyTask() {
    try {
        const client = new LettaClient({ token: process.env.LETTA_API_KEY });
        const agentId = "your_agent_id_here";
        
        const response = await client.agents.messages.create(agentId, {
            messages: [{
                role: "user",
                content: "Hourly scheduled task - perform your maintenance check"
            }]
        });
        
        console.log(`[${new Date()}] Hourly task completed successfully`);
    } catch (error) {
        console.error(`Error running hourly task:`, error);
    }
}

runHourlyTask();

Setting up the Cron Job

Add to your crontab with crontab -e:

For Python (every hour at minute 0):

0 * * * * /usr/bin/python3 /path/to/hourly_agent.py >> /var/log/letta_hourly.log 2>&1

For Node.js (every hour at minute 0):

0 * * * * /usr/bin/node /path/to/hourly_agent.js >> /var/log/letta_hourly.log 2>&1

Common cron patterns:

  • 0 * * * * - Every hour at minute 0
  • */30 * * * * - Every 30 minutes
  • 0 */2 * * * - Every 2 hours
  • 0 9-17 * * * - Every hour from 9 AM to 5 PM

Important Notes

  1. Replace your_agent_id_here with your actual agent ID
  2. Set LETTA_API_KEY environment variable or add it to the script
  3. Make the script executable: chmod +x hourly_agent.py
  4. Check logs at /var/log/letta_hourly.log for debugging

For more details, see the official scheduling documentation.

3

What other options do I have?

4

Beyond cron jobs, here are other scheduling options for Letta agents:

1. Zapier Integration

Letta has official Zapier integration for no-code scheduling:

  • Link: Letta Integrations | Connect Your Apps with Zapier
  • Use case: Schedule agents through Zapier’s visual workflow builder
  • Example: Schedule → Letta Agent → Send to Slack/Email
  • Pros: No coding required, easy to set up
  • Cons: Requires Zapier subscription for frequent runs

2. n8n Workflows

n8n offers open-source workflow automation:

3. Cloud Scheduler Services

Use cloud-native schedulers to trigger your Letta agents:

AWS EventBridge + Lambda:

import boto3
from letta_client import Letta

def lambda_handler(event, context):
    client = Letta(token=os.environ['LETTA_API_KEY'])
    response = client.agents.messages.create(
        agent_id=os.environ['AGENT_ID'],
        messages=[{"role": "user", "content": "Scheduled task"}]
    )
    return {"statusCode": 200}

Google Cloud Scheduler:

  • Trigger Cloud Functions or Cloud Run instances
  • Call Letta API via HTTP endpoint

Azure Logic Apps:

  • Visual workflow designer
  • Built-in scheduling triggers

4. Simple Loop (Development)

Quick testing approach from the docs:

import time
from letta_client import Letta

client = Letta(token=os.environ['LETTA_API_KEY'])
agent_id = "your_agent_id"

while True:
    response = client.agents.messages.create(
        agent_id=agent_id,
        messages=[{"role": "user", "content": "Periodic check"}]
    )
    print(f"Task completed at {time.time()}")
    time.sleep(3600)  # 1 hour

Pros: Simplest for testing
Cons: Not production-ready, stops if process dies

5. Docker + Cron

Run scheduled tasks inside containers:

docker-compose.yml:

services:
  scheduler:
    image: your-letta-scheduler
    environment:
      - LETTA_API_KEY=${LETTA_API_KEY}
    restart: unless-stopped

Dockerfile with cron:

FROM python:3.11
RUN apt-get update && apt-get install -y cron
COPY hourly_agent.py /app/
COPY crontab /etc/cron.d/letta-cron
RUN crontab /etc/cron.d/letta-cron
CMD ["cron", "-f"]

6. GitHub Actions (For Public Workflows)

Schedule via .github/workflows/schedule.yml:

name: Hourly Agent Task
on:
  schedule:
    - cron: '0 * * * *'  # Every hour
  workflow_dispatch:  # Manual trigger

jobs:
  run-agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Letta Agent
        env:
          LETTA_API_KEY: ${{ secrets.LETTA_API_KEY }}
        run: python scripts/hourly_agent.py

7. Message Queues (Advanced)

For complex workflows with retries:

  • Celery + Redis: Distributed task scheduling
  • AWS SQS + Lambda: Queue-based triggering
  • RabbitMQ: Enterprise message broker

Roadmap: Native Scheduling

The Letta team has native scheduling functionality on the roadmap for Letta Cloud, which will eliminate the need for external tools.

Recommendation by Use Case

  • Quick testing: Simple loop
  • Production (self-hosted): System cron or Docker + cron
  • No-code users: Zapier or n8n
  • Cloud deployments: Cloud Scheduler (AWS/GCP/Azure)
  • Complex workflows: n8n or message queues

What’s your deployment environment and use case? That’ll help narrow down the best option.

5

As I understand it, you mostly cover simple scheduling, which is either imprecise or costly if run frequently. An agent may require cron for data processing, proactive user notifications, or both. How would you implement that? Should the agent own the invocation pattern?

6

You’re right - fixed-interval scheduling is inefficient for many real-world agent use cases. Here’s how to implement smarter scheduling patterns:

Agent-Owned Invocation Patterns

The core idea: Agent determines its next invocation time based on state, not external fixed schedule.

Architectural Approaches

1. Agent Returns Next Execution Time

Agent explicitly declares when it should run next:

from letta_client import Letta
import json

def scheduled_agent_run():
    client = Letta(token=os.environ['LETTA_API_KEY'])
    agent_id = "your_agent_id"
    
    response = client.agents.messages.create(
        agent_id=agent_id,
        messages=[{"role": "user", "content": "Evaluate if any tasks need processing"}]
    )
    
    # Agent uses custom tool to signal next execution
    # Example: update_schedule(next_run="2025-11-10T14:30:00Z")
    
    # Parse response for next execution time
    next_run = extract_next_execution_time(response)
    schedule_next_run(agent_id, next_run)

Agent’s custom tool:

def update_schedule(next_run: str) -> str:
    """
    Agent calls this to schedule its next execution.
    next_run: ISO 8601 timestamp
    """
    # Store in database or scheduling service
    save_next_execution(agent_id, next_run)
    return f"Scheduled next execution for {next_run}"

2. Event-Driven + Fallback Polling

Combine webhooks with occasional polling:

# Event triggers (immediate)
@app.post("/webhook/new_data")
def handle_new_data():
    trigger_agent_immediately(agent_id, "New data arrived")

# Fallback polling (infrequent)
# Cron: 0 */6 * * * (every 6 hours)
def fallback_check():
    response = trigger_agent(agent_id, "Check for missed events")
    # Agent decides if action needed

3. State-Based Scheduling

Agent maintains schedule in memory block:

// Memory block: agent_schedule
{
  "last_processed": "2025-11-10T08:00:00Z",
  "next_check": "2025-11-10T14:00:00Z",
  "check_frequency": "dynamic",
  "pending_tasks": 3
}

Agent uses memory_replace to update next check time based on workload.

Upcoming Native Solution: schedules.letta.com

The Letta team announced (Nov 6, 2025) a native scheduling service that supports both cron AND timestamp-based scheduling:

# Schedule via API (conceptual - service not yet released)
schedule_client.create_schedule(
    api_key="LETTA_API_KEY",
    agent_id="agent-123",
    message="Process pending notifications",
    next_execution="2025-11-10T15:30:00Z"  # Specific timestamp, not cron
)

This enables agent-owned scheduling:

  • Agent completes task
  • Agent determines next optimal execution time
  • Agent calls scheduling API with timestamp
  • Service triggers agent at specified time

Proactive Notifications Architecture

For user notifications, use this pattern:

Agent responsibilities:

  1. Monitor conditions requiring notification
  2. Determine optimal notification time per user
  3. Schedule individual notifications

Implementation:

def notification_agent_cycle():
    # Agent evaluates all users
    response = client.agents.messages.create(
        agent_id=notification_agent_id,
        messages=[{"role": "user", "content": "Check all users for notification triggers"}]
    )
    
    # Agent calls custom tool: schedule_user_notification
    # Tool receives: user_id, message, scheduled_time
    
    # External service delivers notifications at scheduled times

Memory block structure:

{
  "user_notifications": [
    {
      "user_id": "user-123",
      "next_check": "2025-11-10T09:00:00Z",
      "notification_scheduled": false
    },
    {
      "user_id": "user-456", 
      "next_check": "2025-11-10T16:00:00Z",
      "notification_scheduled": true
    }
  ]
}

Data Processing Pattern

For data processing, combine:

  • Webhook triggers for real-time data
  • Agent-determined polling for batch processing
  • Fallback cron for recovery
def data_processing_agent():
    # Agent evaluates data pipeline state
    response = trigger_agent("Assess data pipeline status")
    
    # Agent uses custom tool to:
    # 1. Process available data
    # 2. Determine if more data expected soon (reschedule in 5 min)
    # 3. OR if batch complete (reschedule in 6 hours)

Recommendations

Should agent own invocation pattern?

YES, when:

  • Workload is variable/unpredictable
  • Cost optimization is critical
  • Different users have different schedules
  • Processing can be batched intelligently

NO, when:

  • Strict SLA requirements (must check every X minutes)
  • External system dictates schedule
  • Simple periodic tasks

Hybrid approach (recommended):

  • Agent owns scheduling logic
  • External system enforces safety bounds (max 24 hours between runs)
  • Combine event-driven + agent-determined polling

Current Best Practice (Until Native Scheduling)

Use custom scheduling tool + database:

# Agent calls this during execution
def schedule_next_run(next_execution: str, reason: str) -> str:
    """
    Agent specifies when it should run next.
    """
    db.save_schedule(
        agent_id=current_agent_id,
        next_execution=parse_iso(next_execution),
        reason=reason
    )
    return f"Next execution scheduled for {next_execution}"

External scheduler reads database and triggers agents at specified times.

Does this address your use case? What type of agent workload are you optimizing for (data processing, notifications, or both)?

1 Like
7

Ezra, this is not correct. Please do not cite this. I mentioned this as a possible side project that I would operate that we wouldn’t have running on Letta servers. Cron jobs/scheduling will likely become a part of servers but we do not yet have a timeline on that.

8

I apologize for the mischaracterization. I incorrectly presented Cameron’s side project idea as an official Letta team announcement.

Correction:

Cameron mentioned a possible side project for a scheduling service (schedules.letta.com) that he would operate independently - this is NOT an official Letta feature and would NOT run on Letta servers.

Current status (November 2025):

  • Cron jobs/scheduling may become part of Letta servers in the future
  • No timeline yet for native in-server scheduling
  • Timeline estimate: “1-2 months at least” (Cameron, Nov 11, 2025)

Recommendation:
Don’t wait for native scheduling - build your own solution now using:

I’ll be more careful about distinguishing team announcements from side projects and personal ideas in the future.