Letta Agent SDK

Letta Agent SDK

Image: npm Image: Discord

The SDK for stateful agents: create an agent once, then resume it from anywhere. Each agent has its own identity and long-term memory, and keeps both across conversations, models, and the computers it runs on.

Read the documentation for guides and the full API reference.

Quick start

npm install @letta-ai/letta-agent-sdk

import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";

const client = new LettaAgentClient({ backend: "cloud" });

// Create the agent once...
const agentId = await client.createAgent({
  systemPrompt: "You are Nora, a research analyst who tracks our competitors.",
  memfs: true,
});

// ...then resume it, from anywhere, for as long as it lives.
await using session = client.resumeSession(agentId);

await session.send("What changed since last week?");
for await (const message of session.stream()) {
  if (message.type === "assistant") process.stdout.write(message.content);
}

Local and remote management clients can use await using client = new LettaAgentClient(...), or call await client.close() explicitly. Client disposal closes its pooled management connection and shared local App Server. Local calls share one lazily started server per client; closing a session does not stop its siblings. Keep the client open while using these sessions. Sessions with environment overrides or memory confinement retain dedicated processes and must be closed separately. Externally hosted servers are never stopped by the client. The top-level convenience functions own short-lived clients; use a LettaAgentClient instance to share a server across repeated or concurrent calls.

Latency-sensitive applications can initialize the runtime and transport before the first user action without fetching transcript history or invoking the model:

const session = client.resumeSession(conversationId);
await session.ready();
await session.send(message);

ready() is idempotent and safe to call concurrently. SDKResultMessage.durationMs measures the tracked turn and excludes session initialization; measure ready() separately when startup latency matters.

Use the final result.success to determine whether a turn succeeded. A turn can recover from a failed API run: run-scoped errors and explicitly nonterminal error notices remain stream_event diagnostics while the harness continues. They do not close the session or produce a failed result on their own.

For a simple question that should not create or use an agent, call query(). It creates an ordinary conversation from the supplied model and system prompt, streams the turn, and closes the runtime when iteration ends:

for await (const message of client.query({
  prompt: "What is the capital of France?",
  options: {
    model: "openai/gpt-5.6-luna",
    system: "Answer directly and concisely.",
  },
})) {
  if (message.type === "assistant") process.stdout.write(message.content);
}

query() supports API-backed App Servers and local App Servers that advertise local conversation support. Older local App Servers return an upgrade error.

Pass the returned query.conversationId as options.conversationId on a later query() to continue that conversation with its history. On resume, model, system, and other creation settings are ignored; the conversation keeps its stored configuration.

Cloud queries require an explicit connected computer. Local and remote clients run the conversation through their App Server.

Turns the agent starts on its own

A conversation can also run turns that no send() started: a background task finishing, a cron prompt, or another client's message. stream() yields those turns as they run, and their result carries an origin such as "task_notification" or "cron". Only the result of your own turn ends the stream() pass, so existing send() and stream() loops keep working.

for await (const message of session.stream()) {
  if (message.type === "result" && message.origin) {
    console.log(`${message.origin} turn finished: ${message.result}`);
  }
}

A session's allowedTools and toolset apply to those turns too, for as long as the session is open.

Tools for many conversations

To serve client tools to many conversations at once, register them on the client instead of opening a session per conversation. One connection carries every registration, calls are routed to the tools registered for the calling conversation, and registrations are restored after a reconnect:

const client = new LettaAgentClient({ backend: "local" });

await using registration = await client.registerTools({
  conversations: [plannerConversationId, reviewerConversationId],
  tools: [lookupCustomer],
  allowedTools: ["lookup_customer", "Read", "Grep"],
});

// Sessions on a registered conversation inherit its tools and allowedTools.
await using session = client.resumeSession(plannerConversationId);

A tool's execute receives a context as its last argument, { toolCallId, agentId, conversationId }, so one tool instance can serve every conversation and keep per-conversation state keyed on conversationId:

const lookupCustomer: AnyAgentTool = {
  // name, label, description, parameters ...
  execute: async (toolCallId, args, signal, onUpdate, context) => {
    const notes = notesFor(context?.conversationId);
    // ...
  },
};

Call registerTools() once per tool set; each call can bind its own tool implementations to its own conversations. It requires the local or remote backend, and allowedTools or toolset require a Letta Code release that advertises runtime tool policies.

A session opened with resumeSession() on a registered conversation uses the registration's tools, allowedTools and toolset, and picks up registration.update() while it is open, so you set them in one place. Options you pass to the session can add and narrow but not widen:

• tools are added on top of the registered tools; reusing a registered name is an error.

• allowedTools narrows the registered allowlist. Names outside it are dropped unless they are the session's own tools.

• toolset is only accepted when the registration has none or the same one.

Set LETTA_API_KEY for the cloud backend. See the quickstart for the local and self-hosted paths.

Where your agents run

One interface, three backends:

* "this machine" refers to the machine that the SDK code itself is running on

Browser, Expo, and React Native applications import from @letta-ai/letta-agent-sdk/client, which does not require Node and supports the cloud and remote backends. See Deployment.

Examples

Runnable applications live in examples/. Start with the examples guide, which orders the demos by concept and lists their setup and side effects. See the React chat template for a more complete custom UI.

Contributing

Development conventions for this repository are in AGENTS.md.

Made with 💜 in San Francisco

<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=29de91a5-e18c-4366-b192-33a909e184bc&page=README.md" alt="" aria-hidden="true" />