Developer quickstart

This quickstart will get guide you through creating your first Letta agent. If you’re interested in learning about Letta and how it works, read more here.

Run the Letta Server

Letta agents live inside a Letta Server, which persists them to a database. You can interact with the Letta agents inside your Letta Server with the ADE (a visual interface), and connect your agents to external application via the REST API and Python & TypeScript SDKs.

The recommended way to run the Letta Server is with Docker (view official installation guide). You can also install and run the Letta Server using pip (guide here).

The Letta server can be connected to various LLM API backends (see our Docker guide for more details). In this example, we’ll use an OpenAI API key:

1
# replace `~/.letta/.persist/pgdata` with wherever you want to store your agent data
2
docker run \
3
  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
4
  -p 8283:8283 \
5
  -e OPENAI_API_KEY="your_openai_api_key" \
6
  letta/letta:latest

If you have many different LLM API keys, you can also set up a .env file instead and pass that to docker run:

1
# using a .env file instead of passing environment variables
2
docker run \
3
  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
4
  -p 8283:8283 \
5
  --env-file .env \
6
  letta/letta:latest

Once the Letta server is running, you can access it via port 8283 (e.g. sending REST API requests to http://localhost:8283/v1). You can also connect your server to the Letta ADE to access and manage your agents in a visual interface.

Access the Letta ADE (Agent Development Environment)

The ADE can connect to self-hosted Letta servers (e.g. a Letta server running on your laptop), as well as the Letta Cloud service. When connected to a self-hosted / private server, the ADE uses the Letta REST API to communicate with your server.

If you’re running a Letta server to power an end-user application (such as a customer support chatbot), you can use the ADE to test, debug, and observe the agents in your server. You can also use the ADE as a general chat interface to interacting with your Letta agents.

To connect the ADE with your local Letta server, simply navigate to https://app.letta.com and you will see “Local server” as an option in the left panel (if your server is running):

For information on how to configure the ADE with a Letta server running on a remote server, refer to our guide on remote servers.

Creating an agent with the Letta API

Let’s create an agent via the Letta API, which we can then view in the ADE (you can also use the ADE to create agents).

To create an agent we’ll send a POST request to the Letta Server (API docs). In this example, we’ll use the Claude API for the base LLM model, and the OpenAI API for the embedding model (this requires having configured both OPENAI_API_KEY and ANTHROPIC_API_KEY on our Letta Server):

1
curl --request POST \
2
  --url http://localhost:8283/v1/agents/ \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "memory_blocks": [
6
    {
7
      "label": "human",
8
      "value": "The human'\''s name is Bob the Builder"
9
    },
10
    {
11
      "label": "persona",
12
      "value": "My name is Sam, the all-knowing sentient AI."
13
    }
14
  ],
15
  "llm": "anthropic/claude-3-5-sonnet-20241022", 
16
  "context_window_limit": 16000,
17
  "embedding": "openai/text-embedding-ada-002",
18
}'

The response will include information about the agent:

1
{"description":null,"metadata_":null,"id":"agent-...

Send a message to the agent with the Letta API

Let’s try sending a message to the new agent! We’ll use the agent id (starting with agent-...) that we received in the response above in place of agent_id (route documentation):

1
curl --request POST \
2
  --url http://localhost:8283/v1/agents/agent-a6984b2f-9ad6-43a9-b447-6d32d19a248a/messages \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "messages": [
6
    {
7
      "role": "user",
8
      "text": "hows it going????"
9
    }
10
  ]
11
}'

The response contains the agent’s full response to the message, which includes inner thoughts / chain-of-thought, tool calls, tool responses, and agent messages (directed at the user):

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": "Feeling energized to chat! Ready to connect and share some positive vibes with Bob the Builder."
8
    },
9
    {
10
      "id": "message-29d8d17e-7c50-4289-8d0e-2bab988aa01e",
11
      "date": "2024-12-12T17:05:56+00:00",
12
      "message_type": "tool_call",
13
      "function_call": {
14
        "name": "send_message",
15
        "arguments": "{\n  \"message\": \"Hey! I'm feeling great, thanks for asking! How about you? What’s on your mind?\"\n}",
16
        "function_call_id": "call_Qk0JZjoVnL4fivzQlVmJv56E"
17
      }
18
    },
19
    {
20
      "id": "message-c4295e4c-56ae-4f77-93bf-6a8c3454205b",
21
      "date": "2024-12-12T17:05:56+00:00",
22
      "message_type": "tool_call_return",
23
      "tool_return": "None",
24
      "status": "success",
25
      "tool_call_id": "call_Qk0JZjoVnL4fivzQlVmJv56E",
26
    }
27
  ],
28
  "usage": {
29
    "completion_tokens": 56,
30
    "prompt_tokens": 2030,
31
    "total_tokens": 2086,
32
    "step_count": 1
33
  }
34
}

Viewing the agent in the ADE

We’ve created and messaged our first stateful agent. This agent exists in our Letta server, which means we can view it in the ADE (and continue the conversation there!).

If we open the ADE and click on “Agents”, we should see our agent, as well as the message that we sent to it:

Next steps

Congratulations! 🎉 You just created and messaged your first stateful agent with Letta, using both the Letta ADE, API, and Python/Typescript SDKs.

Now that you’ve succesfully created a basic agent with Letta, you’re ready to start building more complex agents and AI applications.