Build with Letta

Get started with the Letta API

Create your first stateful agent and send it a message

Prerequisites

Requires a Letta API key (agents you create can be viewed on the Letta Platform via the ADE)

Call the API

Set your API key

Get your Letta API key and set it as an environment variable:
Terminal window
```
export LETTA_API_KEY='your-api-key-here'
```
Install the SDK
Terminal window
```
npm install @letta-ai/letta-client
```

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);

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!" }

Set your API key

Get your Letta API key and set it as an environment variable:
Terminal window
```
export LETTA_API_KEY='your-api-key-here'
```
Install the SDK
Terminal window
```
pip install letta-client
```

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)

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!")

Set your API key

Get your Letta API key and set it as an environment variable:
Terminal window
```
export LETTA_API_KEY='your-api-key-here'
```

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..."}
  ]
}

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!"
    }
  ]
}

Next steps

Core concepts Understand agents, memory blocks, and tools.

API reference Full API documentation.