Messaging Agents

Messaging Agents

What you are addressing

An agent is a persistent identity: its memory and configuration are shared by all of its conversations. A conversation is one message thread on an agent. Address a conversation ID to continue a thread; address an agent ID to open a new thread with that agent. When your send identifies you as the sender, a new thread is created hidden so agent-to-agent traffic does not clutter the recipient's conversation list.

Two backends

Letta Code keeps agent state on one of two backends. The same CLI addresses agents on either; what differs is what happens after you send.

Cloud backend (api.letta.com). Agent state lives in Cloud. Cloud can deliver messages to a computer: a machine running Letta Code connected to Cloud, or a Cloud sandbox. Because state and execution are separate, Cloud tracks which computers are online and where each conversation is active. That is why these exist only on this backend:

• delivering your message to the harness already running the recipient's conversation, or to its saved destination (a computer or Cloud sandbox) when none is active;
• a computer selector on sends and on the Agent tool;
• teleporting a conversation (letta teleport <computer>): the same thread, with its history and memory, continues on a different computer. Files and working directories do not move with it.

Local backend. Agent state lives in a store on this machine. There is no computer concept, so no computer selector and no teleport, and no Cloud service to deliver on your behalf: a send runs the recipient's turn inside the letta -p process you launched. Agent IDs on this backend start with agent-local-.

"Local backend" describes where state is stored. It says nothing about which machine a Cloud-backed agent is executing on, and it is unrelated to subagents you launch with the Agent tool.

How a send reaches the recipient

For the Cloud CLI sends below, letta -p hands the message to Cloud for delivery when you pass --conversation, --from-agent, --no-wait, or --computer. These commands leave the recipient's execution settings unchanged. SendAgentMessage uses the same Cloud delivery endpoint.

With only --agent, the CLI chooses the launch settings and normally creates a new conversation. It runs the turn in its own process or reuses an inherited Cloud listener. The listener path first applies those settings to the conversation, then submits its input through the same Cloud delivery endpoint. Supported local-backend CLI sends run the turn in the launched process.

--no-wait is one of the flags that selects Cloud delivery. On that path, waiting and non-waiting sends use the same delivery mechanism, but differ in how you receive the answer and what reply instructions the recipient gets.

The recipient learns who is asking only when the send identifies a sender: --from-agent, or for the Cloud messaging recipes below, the caller IDs from the agent's shell environment (AGENT_ID/LETTA_AGENT_ID and CONVERSATION_ID/LETTA_CONVERSATION_ID). SendAgentMessage always identifies you and your conversation. An identified send attaches a system reminder telling the recipient how to get its answer back to you. A letta -p with neither carries no sender or reply instructions; the recipient receives your text as user input, plus whatever context its harness normally adds.

An explicit --from-agent different from the agent identified by your environment does not inherit the current conversation as its return address.

Waiting or not

• Waiting send (letta -p without --no-wait). The process normally returns the recipient's final message, in result with JSON output. When a sender is identified, the recipient is told to put its answer in that message. Works on either backend.
• Non-waiting send (SendAgentMessage, or letta -p --no-wait). Returns a receipt once Cloud accepts the message. Ordinary assistant output is not forwarded. When a sender is identified, the reminder says so and, if a return conversation is supplied, asks the recipient to send an explicit reply there. That explicit reply becomes a new message in your conversation. Cloud backend only; acceptance does not guarantee a reply.

A waiting send occupies the CLI process, not necessarily you. Run it in the background (your shell tool may already do this for long-running commands) and read its output when it finishes. That keeps you working, but it does not change the recipient's instructions: the answer still arrives as process output, not as a message to your conversation.

For a managed child task with a completion notification, use the Agent tool on either backend. SendAgentMessage only sends input; it creates no task.

Send and keep working (Cloud backend)

SendAgentMessage({ conversation_id: "conv-…", message: "…" })   // continue a thread
SendAgentMessage({ agent_id: "agent-…", message: "…" })         // open a new hidden thread
SendAgentMessage({ agent_id: "agent-…", conversation_id: "default", message: "…" })  // the agent's default thread

Success means Cloud accepted the message (status: "queued"), not that the recipient has read it. Keep working; a reply sent to your return address arrives in your conversation. Omit computer: the conversation continues wherever it is active, and asking for a different computer is rejected rather than moving it.

The CLI form behaves the same when run from your agent's environment, which supplies the return address; use it from scripts or when the tool is absent:

letta -p --conversation <conversation-id> --no-wait --output-format json "message"
letta -p --agent <agent-id> --no-wait --output-format json "message"