Today, we are launching the Letta Agents SDK, a TypeScript library for building with stateful agents.
The Letta Agents SDK is designed for stateful, persistent agents. Each agent has its own sense of identity, long-term experience, and memory — and can work across computers without losing memory or state, just like a human.
You can use the Agents SDK to create multi-agent and multi-user applications, for dynamic orchestration of agents, or to build custom interfaces on top of Letta agents.
An SDK for stateful agents #
The Letta Agents SDK is designed for working with long-running, stateful agents. Agents can be created on different state backends (in the cloud or locally), and can run across different machines while retaining the same memory and state.
The same SDK interface to interact with stateful agents works against Letta Cloud, a self-hosted App Server, or entirely on your machine:
import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
const client = new LettaAgentClient({
backend: "cloud",
apiKey: process.env.LETTA_API_KEY,
});
const agentId = await client.createAgent({
model: "letta/auto",
persona: "I am Nora, a research analyst who tracks our competitors.",
});
js
import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
const client = new LettaAgentClient({
backend: "remote",
url: process.env.LETTA_APP_SERVER_URL!,
authToken: process.env.LETTA_APP_SERVER_TOKEN,
});
const agentId = await client.createAgent({
model: "letta/auto",
persona: "I am Nora, a research analyst who tracks our competitors.",
});
js
import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
const client = new LettaAgentClient({ backend: "local" });
const agentId = await client.createAgent({
model: "letta/auto",
persona: "I am Nora, a research analyst who tracks our competitors.",
});
Registering and working across computers
Agents are not tied to the machine they were created on. A Cloud agent can work in a managed sandbox or on any computer registered with Letta — a laptop, workstation, VM, or container. The computer supplies the files, shell, credentials, and installed software; the agent keeps the same identity, memory, and conversations.
// List the computers registered with your account
const { computers } = await client.computers.list();
// Select one for a session
await using session = client.resumeSession(agentId, {
computer: { name: "work-laptop" },
cwd: "/workspace/project",
});
Creating custom interfaces for stateful agents #
The Agents SDK is built on top of the same WebSockets interface that we build Letta Desktop with. You can create your own custom interfaces — a web app, a mobile app, a kanban board — that connect to either Letta Cloud or your own self-deployed App Server.
The Expo demo app shows how to browse agents, stream reasoning and tool activity, and handle approvals from a mobile client. Fork it to build your own interface with custom themes, branding, or features.
See examples of custom interfaces and applications built with the Agents SDK:
Web chatstreams an agent's work into a browser interface.Dungeon masteruses a persistent persona and Git-backed memory to run campaigns over time.Letta ACPmakes the same stateful agent available in ACP-compatible editors likeZed, test harnesses, and command-line clients while preserving its memory across clients and adapter restarts.
Dynamic workflows across models and machines #
The Agents SDK can power dynamic workflows executed by agents. An agent running locally can spawn new conversations with itself in the cloud to work on concurrent tasks — and because agents can write TypeScript, they can use the SDK to turn repeated work into programs: one-off helpers, reusable commands, scheduled automations, event handlers, or longer-running services that start a new conversation when work arrives. The program handles fixed control flow and external events, while the agent handles interpretation and tool use with its existing memory.
See examples of dynamic workflows with the Agents SDK:
Research teamcoordinates persistent agents in a collaborative research workflow.Release noteslearns formatting preferences as it writes from git history.Dynamic workflowsinvokes agents programmatically to compare plans across models, cross-check research, and migrate files in isolated Cloud sandboxes.
Model-agnostic, managed agents #
The Letta Agents SDK supports both running the agent execution loop fully locally (similar to other agent SDKs) and interfacing with stateful agents managed by remote servers that multiple clients connect to. Unlike other managed agent providers, the Agents SDK unifies the concept of a local SDK and a managed agent SDK.
With Letta Cloud, the agent loop is managed server-side, and clients can execute tools locally, in a cloud sandbox, or on any registered computer. This achieves the best of both worlds of "agent in a sandbox" and "agent with a sandbox": the same agent you use to code locally can be run as a managed agent, while clients remain isolated from the secrets required for LLM inference or server-side MCP execution.
For example, you might give your agent read-only API keys for a less-sensitive service so it can create custom tools or skills to use the service effectively, while more sensitive keys stay server-side as registered MCP tools — which the agent can call but cannot modify.
Start building #
Install the SDK:
npm install @letta-ai/letta-agent-sdk
Additional resources:
- Explore the Agent SDKoverview. - Follow the quickstartfor Cloud, local, and remote examples. - Read the documentationfor memory, sessions, permissions, deployment, client tools, and shared repositories. - Browse the source.