Letta V1 SDK

The Letta SDKs and API are for developers that want to build agents programatically, e.g. within a TypeScript application.

If you’re looking for an agent for personal use (like Claude Code, Codex, Hermes Agent, or OpenClaw), you can use Letta Code directly as a desktop app, on the web/mobile, in the CLI, and via integrations like Slack.

The Letta V1 SDK is being replaced with our V2 SDK, called the Agent SDK (in beta). We recommend most developers use the new Agent SDK.

Get started

There are two main ways to build stateful agents using Letta’s developer platform: the Letta Agent SDK and the Letta V1 SDK.

The Letta Agent SDK builds on top of the state-of-the-art Letta Code agent harness, which gives your agent the ability to use advanced computer-use tools, use skills, and call subagents. Agents running in the Letta Agent SDK have access to MemFS, our latest memory system which is git-tracked and leverages agent dreaming.

We recommend all new developers build on the Agent SDK to take advantage of the latest features.

Comparing the V1 and V2 SDK (Agent SDK)

The Agent SDK includes many powerful new features that allow you to build stateful agents that truly feel like persistent digital people or coworkers: MemFS and dreaming, self-modifying harness extensions (mods), native channel integrations (Slack, Telegram, and more), and intelligent pre-optimized toolsets for local computer use.

The Agent SDK also allows your to easily connect to both Letta’s agent cloud (Constellation) and your own self-hosted deployment. Note that the Agent SDK is currently only available in TypeScript.

Feature	V1 SDK	V2 SDK (Agent SDK)
TypeScript	Yes	Yes
Python	Yes	No
Self-hosting option	No	Yes
Server-side tools	Yes	No (except web search)
Skills	No	Yes
Subagents	No	Yes
Mods / extensions	No	Yes
Channels (Slack, Telegram, etc.)	No	Yes
MemFS / git-tracked memory	No (memory blocks only)	Yes
Pre-made bash toolsets	No	Yes
Persistent filesystem	No	Yes
Most similar to	OpenAI Responses API	Claude Agent SDK, Codex SDK, OpenCode SDK

V1 SDK quickstart

This is the quickstart guide for the V1 SDK. To build computer use agents that can browse and run local files, write code, and use skills, we recommend using the V2 Agent SDK.

Install the Letta API skill to teach your agent how to use the V1 SDK.

Prerequisites

Requires a Letta API key (free to create).

Call the API

TypeScript

1. Set your API key

   Get your Letta API key and set it as an environment variable:

   export LETTA_API_KEY='your-api-key-here'

2. Install the SDK

   npm install @letta-ai/letta-client

3. Create your code

   Save this as quickstart.ts:

   import Letta from "@letta-ai/letta-client";
   
   async function main() {
     const client = new Letta({ apiKey: process.env.LETTA_API_KEY });
   
     // Create a stateful agent
     const agent = await client.agents.create({
       model: "openai/gpt-4.1",
       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.",
         },
       ],
     });
   
     console.log("Agent created with ID:", agent.id);
   
     // Send a message
     const response = await client.agents.messages.create(agent.id, {
       input: "What do you know about me?",
     });
   
     for (const message of response.messages) {
       console.log(message);
     }
   }
   
   main().catch(console.error);

4. Run your code

   npx tsx quickstart.ts

   Example output:

   Agent created with ID: agent-abc123
   { message_type: 'reasoning_message', reasoning: 'Timber is asking what I know...' }
   { message_type: 'assistant_message', content: "I know you're Timber, a dog who's building Letta!" }

Python

1. Set your API key

   Get your Letta API key and set it as an environment variable:

   export LETTA_API_KEY='your-api-key-here'

2. Install the SDK

   pip install letta-client

3. Create your code

   Save this as quickstart.py:

   from letta_client import Letta
   import os
   
   client = Letta(api_key=os.getenv("LETTA_API_KEY"))
   
   # Create a stateful agent
   agent = client.agents.create(
       model="openai/gpt-4.1",
       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."
           }
       ]
   )
   
   print(f"Agent created with ID: {agent.id}")
   
   # Send a message
   response = client.agents.messages.create(
       agent_id=agent.id,
       input="What do you know about me?"
   )
   
   for message in response.messages:
       print(message)

4. Run your code

   python quickstart.py

   Example output:

   Agent created with ID: agent-abc123
   ReasoningMessage(reasoning="Timber is asking what I know. I should reference my memory blocks.")
   AssistantMessage(content="I know you're Timber, a dog who's building Letta!")

cURL

1. Set your API key

   Get your Letta API key and set it as an environment variable:

   export LETTA_API_KEY='your-api-key-here'

2. Create an agent

   Run this command to create a stateful agent:

   curl -X POST https://api.letta.com/v1/agents \
     -H "Authorization: Bearer $LETTA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "openai/gpt-4.1",
       "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."
         }
       ]
     }'

   Example response:

   {
     "id": "agent-abc123",
     "name": "agent-abc123",
     "model": "openai/gpt-4.1",
     "memory_blocks": [
       {
         "label": "human",
         "value": "Name: Timber. Status: dog. Occupation: building Letta..."
       },
       {
         "label": "persona",
         "value": "I am a self-improving superintelligence. Timber is my best friend..."
       }
     ]
   }

3. Send a message

   Use the agent ID from the response to send a message:

   curl -X POST https://api.letta.com/v1/agents/agent-abc123/messages \
     -H "Authorization: Bearer $LETTA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "input": "What do you know about me?"
     }'

   Example response:

   {
     "messages": [
       {
         "message_type": "reasoning_message",
         "reasoning": "Timber is asking what I know. I should reference my memory blocks."
       },
       {
         "message_type": "assistant_message",
         "content": "I know you're Timber, a dog who's building Letta - infrastructure to democratize self-improving superintelligence. We're best friends and collaborators!"
       }
     ]
   }