@letta-ai/letta-client 1.0.0 → 1.1.1

package/README.md

@@ -1,390 +1,404 @@
-# Letta TypeScript API Library
+# Letta TypeScript SDK
 
-[![NPM version](<https://img.shields.io/npm/v/@letta-ai/letta-client.svg?label=npm%20(stable)>)](https://npmjs.org/package/@letta-ai/letta-client) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@letta-ai/letta-client)
+[![npm shield](https://img.shields.io/npm/v/@letta-ai/letta-client)](https://www.npmjs.com/package/@letta-ai/letta-client)
 
-This library provides convenient access to the Letta REST API from server-side TypeScript or JavaScript.
+Letta is the platform for building stateful agents: open AI with advanced memory that can learn and self-improve over time.
 
-The full API of this library can be found in [api.md](api.md).
+### Quicklinks:
+* [**Developer Documentation**](https://docs.letta.com): Learn how to create agents using Python or TypeScript
+* [**TypeScript API Reference**](./reference.md): Complete TypeScript SDK documentation
+* [**Agent Development Environment (ADE)**](https://docs.letta.com/guides/ade/overview): A no-code UI for building stateful agents
+* [**Letta Cloud**](https://app.letta.com/): The fastest way to try Letta
 
-It is generated with [Stainless](https://www.stainless.com/).
+## Get started
 
-## Installation
+Install the Letta TypeScript SDK:
 
-```sh
+```bash
 npm install @letta-ai/letta-client
 ```
 
-## Usage
+## Simple Hello World example
 
-The full API of this library can be found in [api.md](api.md).
+In the example below, we'll create a stateful agent with two memory blocks. We'll initialize the `human` memory block with incorrect information, and correct the agent in our first message - which will trigger the agent to update its own memory with a tool call.
 
-<!-- prettier-ignore -->
-```js
-import Letta from '@letta-ai/letta-client';
+*To run the examples, you'll need to get a `LETTA_API_KEY` from [Letta Cloud](https://app.letta.com/api-keys), or run your own self-hosted server (see [our guide](https://docs.letta.com/guides/selfhosting))*
 
-const client = new Letta({
-  apiKey: process.env['LETTA_API_KEY'], // This is the default and can be omitted
-  environment: 'local', // defaults to 'cloud'
-});
-
-const archive = await client.archives.create({ name: 'name' });
-
-console.log(archive.id);
-```
+```typescript
+import { LettaClient } from '@letta-ai/letta-client';
 
-### Request & Response types
+const client = new LettaClient({ apiKey: "LETTA_API_KEY" });
+// const client = new LettaClient({ baseUrl: "http://localhost:8283" });  // if self-hosting
 
-This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
-
-<!-- prettier-ignore -->
-```ts
-import Letta from '@letta-ai/letta-client';
-
-const client = new Letta({
-  apiKey: process.env['LETTA_API_KEY'], // This is the default and can be omitted
-  environment: 'local', // defaults to 'cloud'
+const agentState = await client.agents.create({
+    model: "openai/gpt-4o-mini",
+    embedding: "openai/text-embedding-3-small",
+    memoryBlocks: [
+        {
+          label: "human",
+          value: "The human's name is Chad. They like vibe coding."
+        },
+        {
+          label: "persona",
+          value: "My name is Sam, a helpful assistant."
+        }
+    ],
+    tools: ["web_search", "run_code"]
 });
 
-const params: Letta.ArchiveCreateParams = { name: 'name' };
-const archive: Letta.Archive = await client.archives.create(params);
-```
-
-Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
+console.log(agentState.id);
+// agent-d9be...0846
 
-## File uploads
-
-Request parameters that correspond to file uploads can be passed in many different forms:
+const response = await client.agents.messages.create(agentState.id, {
+    messages: [
+        {
+            role: "user",
+            content: "Hey, nice to meet you, my name is Brad."
+        }
+    ]
+});
 
-- `File` (or an object with the same structure)
-- a `fetch` `Response` (or an object with the same structure)
-- an `fs.ReadStream`
-- the return value of our `toFile` helper
+// the agent will think, then edit its memory using a tool
+for (const message of response.messages) {
+    console.log(message);
+}
 
-```ts
-import fs from 'fs';
-import Letta, { toFile } from '@letta-ai/letta-client';
+// The content of this memory block will be something like
+// "The human's name is Brad. They like vibe coding."
+// Fetch this block's content with:
+const human_block = await client.agents.blocks.retrieve(agentState.id, "human");
+console.log(human_block.value);
+```
 
-const client = new Letta();
+## Core concepts in Letta:
 
-// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
-await client.agents.importFile({ file: fs.createReadStream('/path/to/file') });
+Letta is built on the [MemGPT](https://arxiv.org/abs/2310.08560) research paper, which introduced the concept of the "LLM Operating System" for memory management:
 
-// Or if you have the web `File` API you can pass a `File` instance:
-await client.agents.importFile({ file: new File(['my bytes'], 'file') });
+1. [**Memory Hierarchy**](https://docs.letta.com/guides/agents/memory): Agents have self-editing memory split between in-context and out-of-context memory
+2. [**Memory Blocks**](https://docs.letta.com/guides/agents/memory-blocks): In-context memory is composed of persistent editable blocks
+3. [**Agentic Context Engineering**](https://docs.letta.com/guides/agents/context-engineering): Agents control their context window using tools to edit, delete, or search memory
+4. [**Perpetual Self-Improving Agents**](https://docs.letta.com/guides/agents/overview): Every agent has a perpetual (infinite) message history
 
-// You can also pass a `fetch` `Response`:
-await client.agents.importFile({ file: await fetch('https://somesite/file') });
+## Local Development
 
-// Finally, if none of the above are convenient, you can use our `toFile` helper:
-await client.agents.importFile({ file: await toFile(Buffer.from('my bytes'), 'file') });
-await client.agents.importFile({ file: await toFile(new Uint8Array([0, 1, 2]), 'file') });
-```
+Connect to a local Letta server instead of the cloud:
 
-## Handling errors
-
-When the library is unable to connect to the API,
-or if the API returns a non-success status code (i.e., 4xx or 5xx response),
-a subclass of `APIError` will be thrown:
-
-<!-- prettier-ignore -->
-```ts
-const archive = await client.archives.create({ name: 'name' }).catch(async (err) => {
-  if (err instanceof Letta.APIError) {
-    console.log(err.status); // 400
-    console.log(err.name); // BadRequestError
-    console.log(err.headers); // {server: 'nginx', ...}
-  } else {
-    throw err;
-  }
+```typescript
+const client = new LettaClient({
+  baseUrl: "http://localhost:8283"
 });
 ```
 
-Error codes are as follows:
+Run Letta locally with Docker:
 
-| Status Code | Error Type                 |
-| ----------- | -------------------------- |
-| 400         | `BadRequestError`          |
-| 401         | `AuthenticationError`      |
-| 403         | `PermissionDeniedError`    |
-| 404         | `NotFoundError`            |
-| 422         | `UnprocessableEntityError` |
-| 429         | `RateLimitError`           |
-| >=500       | `InternalServerError`      |
-| N/A         | `APIConnectionError`       |
+```bash
+docker run \
+  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
+  -p 8283:8283 \
+  -e OPENAI_API_KEY="your_key" \
+  letta/letta:latest
+```
 
-### Retries
+See the [self-hosting guide](https://docs.letta.com/guides/selfhosting) for more options.
 
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
-429 Rate Limit, and >=500 Internal errors will all be retried by default.
+## Key Features
 
-You can use the `maxRetries` option to configure or disable this:
+### Memory Management ([full guide](https://docs.letta.com/guides/agents/memory-blocks))
 
-<!-- prettier-ignore -->
-```js
-// Configure the default for all requests:
-const client = new Letta({
-  maxRetries: 0, // default is 2
+Memory blocks are persistent, editable sections of an agent's context window:
+
+```typescript
+// Create agent with memory blocks
+const agent = await client.agents.create({
+  memoryBlocks: [
+    { label: "persona", value: "I'm a helpful assistant." },
+    { label: "human", value: "User preferences and info." }
+  ]
 });
 
-// Or, configure per-request:
-await client.archives.create({ name: 'name' }, {
-  maxRetries: 5,
+// Update blocks manually
+await client.agents.blocks.update(agent.id, "human", {
+  value: "Updated user information"
 });
+
+// Retrieve a block
+const block = await client.agents.blocks.retrieve(agent.id, "human");
 ```
 
-### Timeouts
+### Multi-agent Shared Memory ([full guide](https://docs.letta.com/guides/agents/multi-agent-shared-memory))
+
+Memory blocks can be attached to multiple agents. All agents will have an up-to-date view on the contents of the memory block -- if one agent modifies it, the other will see it immediately.
 
-Requests time out after 1 minute by default. You can configure this with a `timeout` option:
+Here is how to attach a single memory block to multiple agents:
 
-<!-- prettier-ignore -->
-```ts
-// Configure the default for all requests:
-const client = new Letta({
-  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
+```typescript
+// Create shared block
+const sharedBlock = await client.blocks.create({
+  label: "organization",
+  value: "Shared team context"
 });
 
-// Override per-request:
-await client.archives.create({ name: 'name' }, {
-  timeout: 5 * 1000,
+// Attach to multiple agents
+const agent1 = await client.agents.create({
+  memoryBlocks: [{ label: "persona", value: "I am a supervisor" }],
+  blockIds: [sharedBlock.id]
 });
-```
 
-On timeout, an `APIConnectionTimeoutError` is thrown.
+const agent2 = await client.agents.create({
+  memoryBlocks: [{ label: "persona", value: "I am a worker" }],
+  blockIds: [sharedBlock.id]
+});
+```
 
-Note that requests which time out will be [retried twice by default](#retries).
+### Sleep-time Agents ([full guide](https://docs.letta.com/guides/agents/architectures/sleeptime))
 
-## Advanced Usage
+Background agents that share memory with your primary agent:
 
-### Accessing raw Response data (e.g., headers)
+```typescript
+const agent = await client.agents.create({
+  model: "openai/gpt-4o-mini",
+  enableSleeptime: true  // creates a sleep-time agent
+});
+```
 
-The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
-This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
+### Agent File Import/Export ([full guide](https://docs.letta.com/guides/agents/agent-file))
 
-You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
-Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
+Save and share agents with the `.af` file format:
 
-<!-- prettier-ignore -->
-```ts
-const client = new Letta();
+```typescript
+import { readFileSync } from 'fs';
 
-const response = await client.archives.create({ name: 'name' }).asResponse();
-console.log(response.headers.get('X-My-Header'));
-console.log(response.statusText); // access the underlying Response object
+// Import agent
+const file = new Blob([readFileSync('/path/to/agent.af')]);
+const agent = await client.agents.importFile(file);
 
-const { data: archive, response: raw } = await client.archives.create({ name: 'name' }).withResponse();
-console.log(raw.headers.get('X-My-Header'));
-console.log(archive.id);
+// Export agent
+const schema = await client.agents.exportFile(agent.id);
 ```
 
-### Logging
-
-> [!IMPORTANT]
-> All log messages are intended for debugging only. The format and content of log messages
-> may change between releases.
+### MCP Tools ([full guide](https://docs.letta.com/guides/mcp/overview))
 
-#### Log levels
+Connect to Model Context Protocol servers:
 
-The log level can be configured in two ways:
-
-1. Via the `LETTA_LOG` environment variable
-2. Using the `logLevel` client option (overrides the environment variable if set)
+```typescript
+// First, create an MCP server (example: weather server)
+const weatherServer = await client.mcpServers.create({
+  server_name: "weather-server",
+  config: {
+    mcp_server_type: "streamable_http",
+    server_url: "https://weather-mcp.example.com/mcp",
+  },
+});
 
-```ts
-import Letta from '@letta-ai/letta-client';
+// List tools available from the MCP server
+const tools = await client.mcpServers.tools.list(weatherServer.id);
 
-const client = new Letta({
-  logLevel: 'debug', // Show all log messages
+// Create agent with MCP tool
+const agent = await client.agents.create({
+  model: "openai/gpt-4o-mini",
+  toolIds: [tool.id]
 });
 ```
 
-Available log levels, from most to least verbose:
-
-- `'debug'` - Show debug messages, info, warnings, and errors
-- `'info'` - Show info messages, warnings, and errors
-- `'warn'` - Show warnings and errors (default)
-- `'error'` - Show only errors
-- `'off'` - Disable all logging
-
-At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
-Some authentication-related headers are redacted, but sensitive data in request and response bodies
-may still be visible.
+### Filesystem ([full guide](https://docs.letta.com/guides/agents/filesystem))
 
-#### Custom logger
+Give agents access to files:
 
-By default, this library logs to `globalThis.console`. You can also provide a custom logger.
-Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+```typescript
+import { createReadStream } from 'fs';
 
-When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
-below the configured level will not be sent to your logger.
-
-```ts
-import Letta from '@letta-ai/letta-client';
-import pino from 'pino';
+// Create folder and upload file
+const folder = await client.folders.create({
+  name: "my_folder",
+});
 
-const logger = pino();
+await client.folders.files.upload(createReadStream("file.txt"), folder.id);
 
-const client = new Letta({
-  logger: logger.child({ name: 'Letta' }),
-  logLevel: 'debug', // Send all messages to pino, allowing it to filter
-});
+// Attach to agent
+await client.agents.folders.attach(agent.id, folder.id);
 ```
 
-### Making custom/undocumented requests
+### Long-running Agents ([full guide](https://docs.letta.com/guides/agents/long-running))
 
-This library is typed for convenient access to the documented API. If you need to access undocumented
-endpoints, params, or response properties, the library can still be used.
+Background execution with resumable streaming:
 
-#### Undocumented endpoints
+```typescript
+const stream = await client.agents.messages.create(agent.id, {
+  messages: [{ role: "user", content: "Analyze this dataset" }],
+  background: true
+});
 
-To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.
-Options on the client, such as retries, will be respected when making these requests.
+let runId, lastSeqId;
+for await (const chunk of stream) {
+  runId = chunk.runId;
+  lastSeqId = chunk.seqId;
+}
 
-```ts
-await client.post('/some/path', {
-  body: { some_prop: 'foo' },
-  query: { some_query_arg: 'bar' },
-});
+// Resume if disconnected
+for await (const chunk of client.runs.stream(runId, { startingAfter: lastSeqId })) {
+  console.log(chunk);
+}
 ```
 
-#### Undocumented request params
+### Streaming ([full guide](https://docs.letta.com/guides/agents/streaming))
 
-To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
-parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
-send will be sent as-is.
+Stream responses in real-time:
 
-```ts
-client.archives.create({
-  // ...
-  // @ts-expect-error baz is not yet public
-  baz: 'undocumented option',
+```typescript
+const stream = await client.agents.messages.stream(agent.id, {
+  messages: [{ role: "user", content: "Hello!" }]
 });
-```
 
-For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
-extra param in the body.
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
 
-If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
-options.
+### Message Types ([full guide](https://docs.letta.com/guides/agents/message-types))
+
+Agent responses contain different message types. Handle them with the `messageType` discriminator:
+
+```typescript
+const messages = await client.agents.messages.list(agent.id);
+
+for (const message of messages) {
+  switch (message.messageType) {
+    case "user_message":
+      console.log("User:", message.content);
+      break;
+    case "assistant_message":
+      console.log("Agent:", message.content);
+      break;
+    case "reasoning_message":
+      console.log("Reasoning:", message.reasoning);
+      break;
+    case "tool_call_message":
+      console.log("Tool:", message.toolCall.name);
+      break;
+    case "tool_return_message":
+      console.log("Result:", message.toolReturn);
+      break;
+  }
+}
+```
 
-#### Undocumented response properties
+## TypeScript Support
 
-To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
-the response object, or cast the response object to the requisite type. Like the request params, we do not
-validate or strip extra properties from the response from the API.
+Full TypeScript support with exported types:
 
-### Customizing the fetch client
+```typescript
+import { Letta } from "@letta-ai/letta-client";
 
-By default, this library expects a global `fetch` function is defined.
+const request: Letta.CreateAgentRequest = {
+  model: "openai/gpt-4o-mini",
+  memoryBlocks: [...]
+};
+```
 
-If you want to use a different `fetch` function, you can either polyfill the global:
+## Error Handling
 
-```ts
-import fetch from 'my-fetch';
+```typescript
+import { LettaError } from "@letta-ai/letta-client";
 
-globalThis.fetch = fetch;
+try {
+  await client.agents.messages.create(agentId, {...});
+} catch (err) {
+  if (err instanceof LettaError) {
+    console.log(err.statusCode);
+    console.log(err.message);
+    console.log(err.body);
+  }
+}
 ```
 
-Or pass it to the client:
+## Advanced Configuration
 
-```ts
-import Letta from '@letta-ai/letta-client';
-import fetch from 'my-fetch';
+### Retries
 
-const client = new Letta({ fetch });
+```typescript
+const response = await client.agents.create({...}, {
+  maxRetries: 3 // Default: 2
+});
 ```
 
-### Fetch options
-
-If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
-
-```ts
-import Letta from '@letta-ai/letta-client';
+### Timeouts
 
-const client = new Letta({
-  fetchOptions: {
-    // `RequestInit` options
-  },
+```typescript
+const response = await client.agents.create({...}, {
+  timeoutInSeconds: 30 // Default: 60
 });
 ```
 
-#### Configuring proxies
+### Custom Headers
 
-To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
-options to requests:
-
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
+```typescript
+const response = await client.agents.create({...}, {
+  headers: {
+    'X-Custom-Header': 'value'
+  }
+});
+```
 
-```ts
-import Letta from '@letta-ai/letta-client';
-import * as undici from 'undici';
+### Abort Requests
 
-const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
-const client = new Letta({
-  fetchOptions: {
-    dispatcher: proxyAgent,
-  },
+```typescript
+const controller = new AbortController();
+const response = await client.agents.create({...}, {
+  abortSignal: controller.signal
 });
+controller.abort();
 ```
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
+### Raw Response Access
 
-```ts
-import Letta from '@letta-ai/letta-client';
+```typescript
+const { data, rawResponse } = await client.agents
+  .create({...})
+  .withRawResponse();
 
-const client = new Letta({
-  fetchOptions: {
-    proxy: 'http://localhost:8888',
-  },
-});
+console.log(rawResponse.headers['X-My-Header']);
 ```
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+### Custom Fetch Client
 
-```ts
-import Letta from 'npm:@letta-ai/letta-client';
-
-const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
-const client = new Letta({
-  fetchOptions: {
-    client: httpClient,
-  },
+```typescript
+const client = new LettaClient({
+  fetcher: yourCustomFetchImplementation
 });
 ```
 
-## Frequently Asked Questions
+## Runtime Compatibility
 
-## Semantic versioning
+Works in:
+- Node.js 18+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
 
-This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
-
-1. Changes that only affect static types, without breaking runtime behavior.
-2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
-3. Changes that we do not expect to impact the vast majority of users in practice.
+## Contributing
 
-We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
+Letta is an open source project built by over a hundred contributors. There are many ways to get involved in the Letta OSS project!
 
-We are keen for your feedback; please open an [issue](https://www.github.com/letta-ai/letta-node/issues) with questions, bugs, or suggestions.
+* [**Join the Discord**](https://discord.gg/letta): Chat with the Letta devs and other AI developers.
+* [**Chat on our forum**](https://forum.letta.com/): If you're not into Discord, check out our developer forum.
+* **Follow our socials**: [Twitter/X](https://twitter.com/Letta_AI), [LinkedIn](https://www.linkedin.com/company/letta-ai/), [YouTube](https://www.youtube.com/@letta-ai)
 
-## Requirements
+This SDK is generated programmatically. For SDK changes, please [open an issue](https://github.com/letta-ai/letta-node/issues).
 
-TypeScript >= 4.9 is supported.
+README contributions are always welcome!
 
-The following runtimes are supported:
+## Resources
 
-- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
-- Deno v1.28.0 or higher.
-- Bun 1.0 or later.
-- Cloudflare Workers.
-- Vercel Edge Runtime.
-- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
-- Nitro v2.6 or greater.
+- [Documentation](https://docs.letta.com)
+- [TypeScript API Reference](./reference.md)
+- [Example Applications](https://github.com/letta-ai/letta-chatbot-example)
 
-Note that React Native is not supported at this time.
+## License
 
-If you are interested in other runtime environments, please open or upvote an issue on GitHub.
+MIT
 
-## Contributing
+---
 
-See [the contributing documentation](./CONTRIBUTING.md).
+***Legal notices**: By using Letta and related Letta services (such as the Letta endpoint or hosted service), you are agreeing to our [privacy policy](https://www.letta.com/privacy-policy) and [terms of service](https://www.letta.com/terms-of-service).*