AutoGineer
Generated banner for Letta Agent SDK
Generated logo for Letta Agent SDK

Letta Agent SDK

Memory frameworkOfficial Letta project

Created by Letta

Published in letta-ai/letta-agent-sdk. Publisher page

116 GitHub stars

What it is

SDK for programmatic control of Letta agents
— the description by Letta

AutoGineer overview, from the brain’s own files

The Letta Agent SDK provides a programmatic interface for creating and managing stateful AI agents. It enables agents to maintain their identity and long-term memory across different conversations, models, and host environments. The SDK supports three backends—cloud, local, and remote—allowing developers to choose between managed hosting or local execution. It includes features for tool registration, session management, and streaming message handling, ensuring that agents can resume their state and continue tasks independently of the client connection.

How it works

Memory model: Not stated

AutoGineer overview, from the brain’s own files

The SDK uses a client-based architecture to manage agent sessions. Developers initialize a LettaAgentClient to handle communication with the agent backend. Agents are created with specific system prompts and memory configurations. The SDK provides a session interface to send messages and stream responses. It supports tool execution by allowing developers to register tools that are routed to specific conversations, enabling agents to perform actions based on their persistent state.

Folders
FolderRoleFiles
.githubagent-config3
examplesexamples52
scriptsscripts1
srcsource-code92

Requirements

Runtimes: Node.js >=22.19.0

API keys (by name): LETTA_API_KEY

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. Not scanned by AutoGineerIts dependencies are installed by npm when you run it and were not scanned by AutoGineer (3 declared). https://www.npmjs.com/package/@letta-ai/letta-agent-sdk

  2. Created by Letta. Published in letta-ai/letta-agent-sdk. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

  • Creating and managing stateful agents with persistent memory.
  • Resuming agent sessions across different environments or restarts.
  • Streaming agent responses and handling background task notifications.
  • Registering tools to be shared across multiple agent conversations.
  • Executing one-off queries without creating persistent agents.
  • Configuring agent toolsets and access policies programmatically.
“Create a new research analyst agent named Nora.”
The SDK returns an agentId that can be used to resume the agent's session and memory later.
“Resume a previous conversation with an existing agent.”
The SDK restores the session context, allowing the agent to continue based on its stored history.
“Register a customer lookup tool for multiple conversations.”
The tool becomes available to all registered conversations, with state keyed by conversationId.
“Perform a one-off query without creating a persistent agent.”
The SDK runs a stateless conversation and closes the runtime automatically after the response.

Documentation by Letta

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:

BackendAgent stateTools execute
"cloud"Hosted by LettaA managed sandbox, or a computer you connect
"local"On this machine*On this machine*
"remote"Your App ServerOn your App Server machine

* "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" />

LICENSE

Shown as plain text.

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   Copyright 2025, Letta authors

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
158 files · 154 not served here

Advantages

  • Agents maintain identity and long-term memory across conversations and host machines. evidence: README.md
  • Supports multiple backends including cloud, local, and remote for flexible deployment. evidence: README.md

Limitations

  • Requires specific backend compatibility for certain features like local conversation support. evidence: README.md
  • Tool registration and policy enforcement require specific Letta Code release versions. evidence: README.md

Security

Risk level: No risk found

This brain runs

Agent instructions that run or fetch something (5)

  • AGENTS.md: `dist/` is generated by `bun run build`, ignored by Git, and published as a bundle.
  • AGENTS.md: `seqId` answers "have I already processed this stream position?" It is a per-run replay cursor: use it to suppress replayed events after a resume or reconnect, compare it only within the same `runId`, and reset the threshold when a new run starts.
  • AGENTS.md: After changing this boundary, run `bun run check`, `bun test`, and `bun run build`.
  • AGENTS.md: If path behavior changed, run the narrow live route test too;
  • AGENTS.md: Run `bun run check`, `bun test`, and `bun run build` before opening a PR.

Attribution and licence

Created by
Letta
Publisher
Letta (Official Letta project)
Source
letta-ai/letta-agent-sdk · commit eb7236b
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Letta.

Install from source

154 of its files are not served here, so there is no ZIP. letta-ai/letta-agent-sdk at eb7236b