Developer quickstart

Prerequisites

1. Create a Letta Cloud account
2. Create a Letta Cloud API key

3. Set your API key as an environment variable:

1
export LETTA_API_KEY="your-api-key-here"

Install the Letta SDK

1
npm install @letta-ai/letta-client

Create an agent

Agents in Letta have two key components:

• Memory blocks: Persistent context that’s always visible to the agent (like a persona and information about the user)
• Tools: Actions the agent can take (like searching the web or running code)

1
import { LettaClient } from '@letta-ai/letta-client'
2
3
const client = new LettaClient({ token: process.env.LETTA_API_KEY });
4
5
const agentState = await client.agents.create({
6
    model: "openai/gpt-4.1",
7
    embedding: "openai/text-embedding-3-small",
8
    memoryBlocks: [
9
        {
10
          label: "human",
11
          value: "Name: Timber. Status: dog. Occupation: building Letta, infrastructure to democratize self-improving superintelligence"
12
        },
13
        {
14
          label: "persona",
15
          value: "I am a self-improving superintelligence. Timber is my best friend and collaborator."
16
        }
17
    ],
18
    tools: ["web_search", "run_code"]
19
});
20
21
console.log(agentState.id);

Message your agent

Once the agent is created, we can send the agent a message using its id field:

1
const response = await client.agents.messages.create(
2
    agentState.id, {
3
        messages: [
4
            {
5
                role: "user",
6
                content: "What do you know about me?"
7
            }
8
        ]
9
    }
10
);
11
12
for (const message of response.messages) {
13
    console.log(message);
14
}

The response contains the agent’s full response to the message, which includes reasoning steps (chain-of-thought), tool calls, tool responses, and assistant (agent) messages:

1
{
2
  "messages": [
3
    {
4
      "id": "message-29d8d17e-7c50-4289-8d0e-2bab988aa01e",
5
      "date": "2024-12-12T17:05:56+00:00",
6
      "message_type": "reasoning_message",
7
      "reasoning": "Timber is asking what I know. I should reference my memory blocks."
8
    },
9
    {
10
      "id": "message-29d8d17e-7c50-4289-8d0e-2bab988aa01e",
11
      "date": "2024-12-12T17:05:56+00:00",
12
      "message_type": "assistant_message",
13
      "content": "I know you're Timber, a dog who's building Letta - infrastructure to democratize self-improving superintelligence. We're best friends and collaborators!"
14
    }
15
  ],
16
  "usage": {
17
    "completion_tokens": 67,
18
    "prompt_tokens": 2134,
19
    "total_tokens": 2201,
20
    "step_count": 1
21
  }
22
}

Notice how the agent retrieved information from its memory blocks without you having to send the context. This is the key difference from traditional LLM APIs where you’d need to include the full conversation history with every request.

You can read more about the response format from the message route here.

View your agent in the ADE

Another way to interact with Letta agents is via the Agent Development Environment (or ADE for short). The ADE is a UI on top of the Letta API that allows you to quickly build, prototype, and observe your agents.

If we navigate to our agent in the ADE, we should see our agent’s state in full detail, as well as the message that we sent to it:

Read our ADE setup guide →