Skip to content

armgit / letta

Public Imported from GitHub
0

Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.

docs: update README to Letta Agent SDK, add AGENTS.md deprecation notice (#3393)

Charles Packerb76da9092518
diff --git a/.gitignore b/.gitignore
index d0d9c45a1..ea3603746 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,6 @@ openapi_letta.json
openapi_openai.json
CLAUDE.md
-AGENTS.md
### Eclipse ###
.metadata
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..a8ce42d47
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## This repository is deprecated
+
+This repository contains the **legacy Letta server**: the self-hosted API server (`letta/letta` image) that powers the Letta V1 API and V1 SDKs (`@letta-ai/letta-client` for TypeScript, `letta-client` for Python). It is in maintenance mode and is no longer where active development happens.
+
+If you are an agent working here, you most likely want one of these instead:
+
+| You want to... | Go to |
+| --- | --- |
+| Use or modify the current Letta agent (harness, CLI, channel integrations, etc.) | [letta-ai/letta-code](https://github.com/letta-ai/letta-code) |
+| Build agents into an application programmatically | [Letta Agent SDK](https://docs.letta.com/letta-agent-sdk/overview) (`@letta-ai/letta-agent-sdk`) |
+| Self-host a server for Letta agents | [App Server](https://docs.letta.com/letta-agent/app-server), which replaces the API server in this repo |
+| Reference the legacy V1 SDK / API | [V1 SDK docs](https://docs.letta.com/guides/get-started/intro) |
+
+## Notes for agents working in this repo
+
+- New features and integrations should target [letta-ai/letta-code](https://github.com/letta-ai/letta-code) and the [Letta Agent SDK](https://docs.letta.com/letta-agent-sdk/overview), not this codebase.
+- All contributions (issues, PRs, discussions) must comply with the [AI usage policy](AI_POLICY.md): AI assistance must be disclosed, and a human must fully understand and review everything submitted.
diff --git a/README.md b/README.md
index 5af303fd7..131f06a3c 100644
--- a/README.md
+++ b/README.md
@@ -2,113 +2,77 @@
Build AI with advanced memory that can learn and self-improve over time.
-* [Letta Code](https://docs.letta.com/letta-code): run agents locally in your terminal
-* [Letta API](https://docs.letta.com/quickstart/): build agents into your applications
+* [Letta Agent](https://docs.letta.com/letta-agent): run agents locally in your terminal, via the desktop app, or via channels like Slack
+* [Letta Agent SDK](https://docs.letta.com/letta-agent-sdk/overview): build agents into your applications
+
+> [!NOTE]
+> This repository contains the legacy Letta server (the API server behind the Letta V1 API and SDKs). Active development has moved to the [Letta Agent repo](https://github.com/letta-ai/letta-code), and self-hosting an API server is now done via the [App Server](https://docs.letta.com/letta-agent/app-server). See [AGENTS.md](AGENTS.md) for details.
## Get started in the CLI
-Requires [Node.js 18+](https://nodejs.org/en/download)
+Requires [Node.js 22.19+](https://nodejs.org/en/download)
1. Install the [Letta Code](https://github.com/letta-ai/letta-code) CLI tool: `npm install -g @letta-ai/letta-code`
2. Run `letta` in your terminal to launch an agent with memory running on your local computer
-When running the CLI tool, your agent help you code and do any task you can do on your computer.
+When running the CLI tool, your agent can help you code and do any task you can do on your computer.
-Letta Code supports [skills](https://docs.letta.com/letta-code/skills) and [subagents](https://docs.letta.com/letta-code/subagents), and bundles pre-built skills/subagents for advanced memory and continual learning. Letta is fully model-agnostic, though we recommend Opus 4.5 and GPT-5.2 for best performance (see our [model leaderboard](https://leaderboard.letta.com/) for our rankings).
+Letta Code supports [skills](https://docs.letta.com/letta-agent/skills) and [subagents](https://docs.letta.com/letta-agent/subagents), and bundles pre-built skills/subagents for advanced memory and continual learning. Letta is fully model-agnostic, though we recommend the latest Anthropic, OpenAI, and zAI models for best performance (see our [model leaderboard](https://leaderboard.letta.com/) for our rankings).
-## Get started with the Letta API
+## Get started with the Letta Agent SDK
-Use the Letta API to integrate stateful agents into your own applications.
-Letta has a full-featured agents API, and a Python and Typescript SDK (view our [API reference](https://docs.letta.com/api)).
+Use the [Letta Agent SDK](https://docs.letta.com/letta-agent-sdk/overview) (TypeScript) to build stateful agents into your own applications.
+The SDK can run agents on [Constellation](https://docs.letta.com/letta-agent/constellation) (Letta's agent cloud), fully locally on your machine, or against a self-hosted [App Server](https://docs.letta.com/letta-agent/app-server).
### Installation
-TypeScript / Node.js:
```bash
-npm install @letta-ai/letta-client
-```
-
-Python:
-```bash
-pip install letta-client
+npm install @letta-ai/letta-agent-sdk
```
### Hello World example
-Below is a quick example of creating a stateful agent and sending it a message (requires a [Letta API key](https://app.letta.com)).
-See the full [quickstart guide](https://docs.letta.com/quickstart) for complete documentation.
+Below is a quick example of creating a stateful agent and streaming a conversation with it (requires a [Letta API key](https://app.letta.com/api-keys)).
+See the full [quickstart guide](https://docs.letta.com/letta-agent-sdk/quickstart) for complete documentation.
-TypeScript:
```typescript
-import Letta from "@letta-ai/letta-client";
+import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
-const client = new Letta({ apiKey: process.env.LETTA_API_KEY });
+const client = new LettaAgentClient({
+ backend: "cloud",
+ apiKey: process.env.LETTA_API_KEY,
+});
// Create your agent
-const agentState = await client.agents.create({
- model: "openai/gpt-5.2",
- memory_blocks: [
- {
- label: "human",
- value:
- "Name: Timber. Status: dog. Occupation: building Letta, infrastructure to democratize self-improving superintelligence",
- },
- {
- label: "persona",
- value:
- "I am a self-improving superintelligence. Timber is my best friend and collaborator.",
- },
- ],
- tools: ["web_search", "fetch_webpage"],
+const agentId = await client.createAgent({
+ model: "anthropic/claude-opus-4-8",
+ human:
+ "Name: Timber. Status: dog. Occupation: building Letta, infrastructure to democratize self-improving superintelligence",
+ persona:
+ "I am a self-improving superintelligence. Timber is my best friend and collaborator.",
});
-console.log("Agent created with ID:", agentState.id);
+console.log("Agent created with ID:", agentId);
-// Send your agent a message
-const response = await client.agents.messages.create(agentState.id, {
- input: "What do you know about me?",
-});
+// Send your agent a message and stream the response
+await using session = client.resumeSession(agentId);
-for (const message of response.messages) {
- console.log(message);
+await session.send("What do you know about me?");
+for await (const message of session.stream()) {
+ if (message.type === "assistant") console.log(message.content);
}
```
-Python:
-```python
-from letta_client import Letta
-import os
-
-client = Letta(api_key=os.getenv("LETTA_API_KEY"))
-
-# Create your agent
-agent_state = client.agents.create(
- model="openai/gpt-5.2",
- memory_blocks=[
- {
- "label": "human",
- "value": "Name: Timber. Status: dog. Occupation: building Letta, infrastructure to democratize self-improving superintelligence"
- },
- {
- "label": "persona",
- "value": "I am a self-improving superintelligence. Timber is my best friend and collaborator."
- }
- ],
- tools=["web_search", "fetch_webpage"]
-)
-
-print(f"Agent created with ID: {agent_state.id}")
-
-# Send your agent a message
-response = client.agents.messages.create(
- agent_id=agent_state.id,
- input="What do you know about me?"
-)
-
-for message in response.messages:
- print(message)
+To run the same agent fully locally (the SDK spawns [Letta Code](https://github.com/letta-ai/letta-code) on your machine as a subprocess), swap out the client:
+
+```typescript
+const client = new LettaAgentClient({ backend: "local" });
```
+### Letta V1 SDK
+
+The previous-generation [V1 SDKs](https://docs.letta.com/guides/get-started/intro) (`@letta-ai/letta-client` for TypeScript, `letta-client` for Python) target the Letta API directly and are still available (see the [client SDKs](https://docs.letta.com/api-overview/client-sdks)). We recommend the Agent SDK for new projects.
+
## Contributing
Letta is an open source project built by over a hundred contributors from around the world. There are many ways to get involved in the Letta OSS project!