Scheduling messages

Schedule messages to be sent to your agent at a specific time or on a recurring basis. This enables autonomous agent behaviors like daily summaries, periodic check-ins, and scheduled maintenance tasks.

Scheduling is available on Letta API. Self-hosted deployments can use external schedulers (cron jobs, task queues) to trigger agent messages via the standard messages API.

Quick Start

One-time Message

Schedule a message to be sent at a specific time:

Python

import os
from letta_client import Letta
import time

client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Schedule a message for 1 hour from now
scheduled_time = int(time.time() * 1000) + (60 * 60 * 1000)

response = client.agents.schedule.create(
    agent_id=agent.id,
    schedule={"type": "one-time", "scheduled_at": scheduled_time},
    messages=[{"role": "user", "content": "Generate your daily summary report"}]
)

print(f"Scheduled message ID: {response.id}")
print(f"Will execute at: {response.next_scheduled_at}")

TypeScript

import Letta from "@letta-ai/letta-client";

const client = new Letta({ apiKey: process.env.LETTA_API_KEY });

// Schedule a message for 1 hour from now
const scheduledTime = Date.now() + 60 * 60 * 1000;

const response = await client.agents.schedule.create(agent.id, {
  schedule: { type: "one-time", scheduled_at: scheduledTime },
  messages: [{ role: "user", content: "Generate your daily summary report" }],
});

console.log(`Scheduled message ID: ${response.id}`);
console.log(`Will execute at: ${response.next_scheduled_at}`);

curl

# scheduled_at is Unix timestamp in milliseconds
curl -X POST https://api.letta.com/v1/agents/$AGENT_ID/schedule \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": { "type": "one-time", "scheduled_at": 1704110400000 },
    "messages": [{ "role": "user", "content": "Generate your daily summary report" }]
  }'

Recurring Message

Schedule a message to be sent on a recurring basis using a cron expression:

Python

# Schedule a message to run every day at 9 AM UTC
response = client.agents.schedule.create(
    agent_id=agent.id,
    schedule={"type": "recurring", "cron_expression": "0 9 * * *"},
    messages=[{"role": "user", "content": "Good morning! Review overnight alerts and summarize."}]
)

print(f"Recurring schedule ID: {response.id}")
print(f"Next execution: {response.next_scheduled_at}")

TypeScript

// Schedule a message to run every day at 9 AM UTC
const response = await client.agents.schedule.create(agent.id, {
  schedule: { type: "recurring", cron_expression: "0 9 * * *" },
  messages: [
    {
      role: "user",
      content: "Good morning! Review overnight alerts and summarize.",
    },
  ],
});

console.log(`Recurring schedule ID: ${response.id}`);
console.log(`Next execution: ${response.next_scheduled_at}`);

curl

curl -X POST https://api.letta.com/v1/agents/$AGENT_ID/schedule \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": { "type": "recurring", "cron_expression": "0 9 * * *" },
    "messages": [{ "role": "user", "content": "Good morning! Review overnight alerts and summarize." }]
  }'

Schedule Types

Aspect	One-time	Recurring
Use case	Single future event	Periodic tasks
Configuration	scheduled_at (Unix ms)	cron_expression
Executes	Once, then removed	Repeatedly until deleted
Example	Meeting reminder	Daily summary

One-time Messages

One-time messages execute at a specific timestamp and are automatically removed after execution.

Parameters

• scheduled_at: Unix timestamp in milliseconds (not seconds)
• Must be in the future - scheduling in the past returns a 400 error

Example: Meeting Reminder

Python

from datetime import datetime, timedelta

# Schedule for tomorrow at 2 PM UTC
tomorrow_2pm = datetime.utcnow().replace(
    hour=14, minute=0, second=0, microsecond=0
) + timedelta(days=1)
scheduled_at = int(tomorrow_2pm.timestamp() * 1000)

response = client.agents.schedule.create(
    agent_id=agent.id,
    schedule={"type": "one-time", "scheduled_at": scheduled_at},
    messages=[{
        "role": "user",
        "content": "Reminder: Team standup starts in 15 minutes. Prepare your update."
    }]
)

TypeScript

// Schedule for tomorrow at 2 PM UTC
const tomorrow = new Date();
tomorrow.setUTCDate(tomorrow.getUTCDate() + 1);
tomorrow.setUTCHours(14, 0, 0, 0);

const response = await client.agents.schedule.create(agent.id, {
  schedule: { type: "one-time", scheduled_at: tomorrow.getTime() },
  messages: [
    {
      role: "user",
      content:
        "Reminder: Team standup starts in 15 minutes. Prepare your update.",
    },
  ],
});

Recurring Messages

Recurring messages use cron expressions to define the schedule. They continue executing until explicitly deleted.

Cron Expression Format

Letta uses standard 5-field cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Seconds-precision cron expressions (6 fields) are not supported. Using a 6-field expression like */5 * * * * * returns a 400 error.

Common Cron Patterns

Pattern	Expression	Description
Every 5 minutes	*/5 * * * *	Frequent monitoring
Every hour	0 * * * *	Hourly tasks
Daily at 9 AM	0 9 * * *	Morning summaries
Daily at midnight	0 0 * * *	End-of-day processing
Weekdays at 9 AM	0 9 * * 1-5	Business day tasks
Weekly on Monday	0 9 * * 1	Weekly reports
First of month	0 0 1 * *	Monthly tasks

Example: Daily Memory Maintenance

Python

# Run daily at midnight UTC to clean up agent memory
response = client.agents.schedule.create(
    agent_id=agent.id,
    schedule={"type": "recurring", "cron_expression": "0 0 * * *"},
    messages=[{
        "role": "user",
        "content": "Review your memory blocks for outdated information. Archive completed tasks and consolidate redundant entries."
    }]
)

TypeScript

// Run daily at midnight UTC to clean up agent memory
const response = await client.agents.schedule.create(agent.id, {
  schedule: { type: "recurring", cron_expression: "0 0 * * *" },
  messages: [
    {
      role: "user",
      content:
        "Review your memory blocks for outdated information. Archive completed tasks and consolidate redundant entries.",
    },
  ],
});

Managing Scheduled Messages

List Scheduled Messages

Retrieve all active scheduled messages for an agent:

Python

response = client.agents.schedule.list(agent_id=agent.id)

for msg in response.scheduled_messages:
    print(f"ID: {msg.id}")
    print(f"Next run: {msg.next_scheduled_time}")
    if msg.schedule.type == "recurring":
        print(f"Cron: {msg.schedule.cron_expression}")
    print("---")

TypeScript

const response = await client.agents.schedule.list(agent.id);

for (const msg of response.scheduled_messages) {
  console.log(`ID: ${msg.id}`);
  console.log(`Next run: ${msg.next_scheduled_time}`);
  if (msg.schedule.type === "recurring") {
    console.log(`Cron: ${msg.schedule.cron_expression}`);
  }
  console.log("---");
}

curl

curl https://api.letta.com/v1/agents/$AGENT_ID/schedule \
  -H "Authorization: Bearer $LETTA_API_KEY"

Retrieve a Scheduled Message

Get details about a specific scheduled message:

Python

scheduled_msg = client.agents.schedule.retrieve(
    agent_id=agent.id,
    scheduled_message_id="sm-abc123"
)
print(f"Next execution: {scheduled_msg.next_scheduled_time}")

TypeScript

const scheduledMsg = await client.agents.schedule.retrieve(
  agent.id,
  "sm-abc123"
);
console.log(`Next execution: ${scheduledMsg.next_scheduled_time}`);

curl

curl https://api.letta.com/v1/agents/$AGENT_ID/schedule/$SCHEDULED_MESSAGE_ID \
  -H "Authorization: Bearer $LETTA_API_KEY"

Cancel a Scheduled Message

Delete a scheduled message to prevent future executions:

Python

client.agents.schedule.delete(
    agent_id=agent.id,
    scheduled_message_id="sm-abc123"
)
print("Schedule cancelled")

TypeScript

await client.agents.schedule.delete(agent.id, "sm-abc123");
console.log("Schedule cancelled");

curl

curl -X DELETE https://api.letta.com/v1/agents/$AGENT_ID/schedule/$SCHEDULED_MESSAGE_ID \
  -H "Authorization: Bearer $LETTA_API_KEY"

Use Cases

Daily summaries: Schedule morning briefings that review overnight activity and prepare the agent for the day.

Memory maintenance: Periodic cleanup of agent memory blocks to remove outdated information and consolidate entries.

Proactive check-ins: Regular prompts that ask the agent to review pending tasks or check on long-running processes.

System monitoring: Scheduled health checks where the agent reviews logs, metrics, or external systems.

Deadline reminders: One-time messages triggered before important events or deadlines.

Tips

1. All times are UTC: Cron expressions and timestamps are interpreted as UTC. Account for timezone differences when scheduling.

2. Timestamps are milliseconds: The scheduled_at field uses Unix timestamps in milliseconds, not seconds. Multiply seconds by 1000.

3. Validate cron expressions: Invalid cron expressions return a 400 error. Use a cron expression validator to test expressions before scheduling.

4. Handle errors gracefully: Scheduling in the past returns a 400 error. Always check that your scheduled time is in the future.

5. Clean up unused schedules: Recurring schedules continue until deleted. Periodically review and remove schedules that are no longer needed.