letta-node

@letta-ai/letta-client is the official server-side TypeScript library for the Letta API, the platform behind Letta’s stateful AI agents with persistent memory. Rather than hand-writing HTTP calls against Letta’s REST endpoints, developers import a single Letta client and get fully typed methods for creating and managing agents, sending and streaming messages, editing memory blocks and archives, registering custom tools, and running background jobs.

The library is generated directly from Letta’s OpenAPI spec using Stainless, which means every one of the 129 configured endpoints ships with matching TypeScript types for request params and response shapes, kept in lockstep with the API as it evolves. It targets both Node.js and browser/edge runtimes via a dual CJS/ESM build, and layers on conveniences a raw fetch client would otherwise leave to the caller: automatic retries with backoff, configurable timeouts, auto-pagination over list endpoints, Server-Sent-Events streaming for agent message responses, and typed APIError subclasses per HTTP status code.

Because it is a thin, generated wrapper around Letta’s public API rather than a hand-rolled abstraction, it has effectively zero runtime dependencies and mirrors the API surface directly — making it the natural starting point for any Node/TypeScript application that needs to talk to Letta Cloud or a self-hosted Letta server.

What You Get

• A single Letta client class exposing typed methods for all 129 endpoints of the Letta REST API, grouped into resources like agents, messages, blocks, archives, tools, and templates
• Full TypeScript definitions for every request parameter and response field, generated from Letta’s OpenAPI spec so they stay in sync with the live API
• Server-Sent-Events streaming support for agent message responses via async iterables, with stream.controller.abort() for cancellation
• Auto-pagination helpers (for await...of) plus manual page-by-page methods (hasNextPage(), getNextPage()) for list endpoints
• Built-in request handling: configurable retries with exponential backoff, per-request and client-wide timeouts, and typed APIError subclasses (BadRequestError, AuthenticationError, RateLimitError, etc.) mapped to HTTP status codes
• File upload helpers (toFile) accepting File, fetch Response, fs.ReadStream, Buffer, or Uint8Array inputs for endpoints like agent file import
• Configurable structured logging (logLevel, custom logger) and support for custom fetch implementations and proxy configuration via fetchOptions

Common Use Cases

• Building a Node.js or TypeScript backend that creates and drives Letta agents (chat assistants with persistent memory) from application code
• Streaming an agent’s message responses into a chat UI in real time using the SSE-based streaming API
• Managing an agent’s long-term memory programmatically — creating and updating memory blocks and archives as conversations evolve
• Registering custom tools (including Python/npm requirement-based tools) that a Letta agent can call during a run
• Automating agent template creation and deployment pipelines for multi-tenant or templated agent products

Under The Hood

Architecture The library is a generated Stainless SDK: src/client.ts defines a single Letta client class that composes per-resource classes (src/resources/*.ts — agents, messages, blocks, archives, tools, templates, runs, environments, access-tokens, and more), each of which builds typed requests against Letta’s REST API and delegates the actual HTTP mechanics to a shared core/ layer (api-promise.ts, resource.ts, pagination.ts). Pagination is abstracted via an AbstractPage<Item> base class implementing AsyncIterable, so every list endpoint gets consistent for await iteration and manual getNextPage() semantics for free. This is a thin, uniform client-generation pattern — changing the core abstraction (request building, error mapping, pagination) propagates to all 129 endpoints simultaneously, since resource classes only describe endpoint shape, not transport behavior.

Tech Stack Written in TypeScript (98%+ of the codebase) targeting both CommonJS and ESM output (dual dist/index.js/dist/index.mjs build via exports map), with a custom build pipeline (scripts/build, tsc-multi) rather than a bundler, since the package ships source-level type declarations. It has zero runtime dependencies — everything (query string serialization, SSE parsing, multipart form encoding, platform detection) is implemented internally under src/internal/. Devtooling includes ESLint 9 (flat config) with typescript-eslint, Prettier, Jest with @swc/jest for fast TypeScript test transforms, and publint/@arethetypeswrong to validate the published package’s module resolution correctness.

Code Quality Tests live under tests/, split between infrastructure tests (streaming.test.ts, uploads.test.ts, buildHeaders.test.ts, stringifyQuery.test.ts, base64 and querystring edge cases) and per-resource API tests (tests/api-resources/*.test.ts for agents, messages, tools, blocks, and others), run via Jest with SWC transforms for speed. Error handling is explicit and typed: APIError and its per-status subclasses (BadRequestError, NotFoundError, RateLimitError, InternalServerError, etc.) are thrown rather than swallowed, with retry logic reserved for a defined set of transient failures (connection errors, 408/409/429, 5xx). Naming and file layout are consistent and machine-generated across all resources, which trades hand-tuned idiom for uniformity — a deliberate tradeoff for a spec-generated client. GitHub Actions CI is configured under .github/.

API Design The public API favors ergonomics: a single new Letta({ apiKey, environment }) constructor, resource-scoped methods (client.agents.list(), client.archives.create(...)), and idiomatic JS patterns (async iterables for pagination and streaming) over exposing raw HTTP verbs. Escape hatches are provided for undocumented behavior (client.get/client.post for undocumented endpoints, @ts-expect-error for undocumented params) without requiring a fork or patch. Getting started requires only an API key and one import — the README’s quickstart is a five-line example — and per-request overrides (timeout, retries, headers) are supported without extra ceremony.