Heartbeats (Legacy)

Danger

Heartbeats are only supported in legacy agent architectures (memgpt_agent, memgpt_v2_agent).

The current architecture (letta_v1_agent) does not use heartbeats. For multi-step execution, use explicit prompting or tool rules. See migration guide →

Heartbeats are a mechanism that enables legacy Letta agents to chain multiple tool calls together in a single execution loop. The term “heartbeat” was coined in the MemGPT paper, and since the Letta codebase evolved from the original MemGPT codebase (same authors), heartbeats were a core part of the early agent loop.

How heartbeats work

Every tool in legacy agents automatically receives an additional parameter called request_heartbeat, which defaults to false. When an agent sets this parameter to true, it signals to the Letta server that it wants to continue executing after the current tool call completes.

Technical implementation

When the Letta server detects that request_heartbeat=true, it:

1. Completes the current tool execution
2. Restarts the agent loop with a system message acknowledging the heartbeat request
3. Allows the agent to continue with an additional tool calls

stateDiagram-v2
    state "Agent Loop" as agent
    state "Tool Call" as tool

    [*] --> agent
    agent --> tool: Execute tool
    tool --> agent: request_heartbeat=true
    tool --> [*]: request_heartbeat=false

This enables agents to perform complex, multi-step operations without requiring explicit user intervention between steps.

Automatic heartbeats on failure

If a tool call fails at runtime, legacy agents automatically generate a heartbeat. This gives the agent an opportunity to handle the error and potentially retry the operation with different parameters or take alternative actions.

Viewing heartbeats in the ADE

In the Agent Development Environment (ADE), heartbeat requests are visible for all agent messages. When a tool is called with request_heartbeat=true, you’ll see a heartbeat indicator next to the tool call, making it easy to track when an agent is proactively chaining operations together.

Learn more

To read more about the concept of heartbeats and their origins, refer to the original MemGPT research paper.