Configuration

Scheduling

Scheduling is a technique for triggering Letta agents at regular intervals. Many real-world applications require proactive behavior, such as checking emails every few hours or scraping news sites. Scheduling can support autonomous agents with the capability to manage ongoing processes.

Native scheduling functionality is on the Letta Cloud roadmap. The approaches described in this guide are temporary solutions that work with both self-hosted and cloud deployments.

Common Use Cases

When building autonomous agents with Letta, you often need to trigger them at regular intervals for tasks like:

  • System Monitoring: Health checks that adapt based on historical patterns
  • Data Processing: Intelligent ETL processes that handle edge cases contextually
  • Memory Maintenance: Agents that optimize their own knowledge base over time
  • Proactive Notifications: Context-aware alerts that consider user preferences and timing
  • Continuous Learning: Agents that regularly ingest new information and update their understanding

This guide covers simple approaches to implement scheduled agent interactions.

Option 1: Simple Loop

The most straightforward approach for development and testing:

1import { LettaClient } from '@letta-ai/letta-client';
2
3const client = new LettaClient({ baseUrl: "http://localhost:8283" });
4const agentId = "your_agent_id";
5
6while (true) {
7    const response = await client.agents.messages.create(agentId, {
8        messages: [{
9            role: "user",
10            content: `Scheduled check at ${new Date()}`
11        }]
12    });
13    console.log(`[${new Date()}] Agent responded`);
14    await new Promise(resolve => setTimeout(resolve, 300000)); // 5 minutes
15}

Pros: Simple, easy to debug Cons: Blocks terminal, stops if process dies

Option 2: System Cron Jobs

For production deployments, use cron for reliability:

1#!/usr/bin/env node
2import { LettaClient } from '@letta-ai/letta-client';
3
4async function sendMessage() {
5    try {
6        const client = new LettaClient({ baseUrl: "http://localhost:8283" });
7        const response = await client.agents.messages.create("your_agent_id", {
8            messages: [{
9                role: "user",
10                content: "Scheduled maintenance check"
11            }]
12        });
13        console.log(`[${new Date()}] Success`);
14    } catch (error) {
15        console.error(`[${new Date()}] Error:`, error);
16    }
17}
18
19sendMessage();

Add to crontab with crontab -e:

$*/5 * * * * /usr/bin/python3 /path/to/send_message.py >> /var/log/letta_cron.log 2>&1
># or for Node.js:
>*/5 * * * * /usr/bin/node /path/to/send_message.js >> /var/log/letta_cron.log 2>&1

Pros: System-managed, survives reboots Cons: Requires cron access

Best Practices

  1. Error Handling: Always wrap API calls in try-catch blocks
  2. Logging: Log both successes and failures for debugging
  3. Environment Variables: Store credentials securely
  4. Rate Limiting: Respect API limits and add backoff for failures

Example: Memory Maintenance Bot

Complete example that performs periodic memory cleanup:

1#!/usr/bin/env node
2import { LettaClient } from '@letta-ai/letta-client';
3
4async function runMaintenance() {
5    try {
6        const client = new LettaClient({ baseUrl: "http://localhost:8283" });
7        const agentId = "your_agent_id";
8
9        const response = await client.agents.messages.create(agentId, {
10            messages: [{
11                role: "user",
12                content: "Please review your memory blocks for outdated information and clean up as needed."
13            }]
14        });
15
16        // Print any assistant messages
17        for (const message of response.messages) {
18            if (message.messageType === "assistant_message") {
19                console.log(`Agent response: ${message.content?.substring(0, 100)}...`);
20            }
21        }
22
23    } catch (error) {
24        console.error("Maintenance failed:", error);
25    }
26}
27
28// Run if called directly
29if (import.meta.url === `file://${process.argv[1]}`) {
30    runMaintenance();
31}

Choose the scheduling method that best fits your deployment environment. For production systems, cron offers the best reliability, while simple loops are perfect for development and testing.