Developer quickstart (Cloud)

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.

Access Letta Cloud

Letta Cloud is accessible via https://app.letta.com. If you have access to Letta Cloud, you can use the web platform to create API keys, and create / deploy / monitor agents.

First, you need to create a Letta Cloud API key. For the rest of the quickstart, we’ll assume your API key is LETTA_API_KEY - you should replace this with your actual API key.

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 gpt-4o-mini as the base LLM model, and text-embedding-3-small as the embedding model (this requires having configured both OPENAI_API_KEY on our Letta Server).

We’ll also artificially set the context window limit to 16k, instead of the 128k default for gpt-4o-mini (this can improve stability and performance):

1
curl -X POST https://app.letta.com/v1/agents \
2
     -H "Authorization: Bearer LETTA_API_KEY" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "memory_blocks": [
6
    {
7
      "value": "The human'\''s name is Bob the Builder.",
8
      "label": "human"
9
    },
10
    {
11
      "value": "My name is Sam, the all-knowing sentient AI.",
12
      "label": "persona"
13
    }
14
  ],
15
  "model": "openai/gpt-4o-mini",
16
  "context_window_limit": 16000,
17
  "embedding": "openai/text-embedding-3-small"
18
}'

The response will include information about the agent, including its id:

1
{
2
  "id": "agent-43f8e098-1021-4545-9395-446f788d7389",
3
  "name": "damp-emerald-seahorse",
4
  ...
5
}

In Letta Cloud, your workspace is organized into projects. When you create agents directly (instead of via templates), your agents will get placed in the “Default Project”. If we go into our “Default Project”, we’ll see the new agent we just created:

Send a message to the agent with the Letta API

Let’s try sending a message to the new agent! Replace AGENT_ID with the actual agent ID we received in the agent state (route documentation):

1
curl --request POST \
2
  --url https://app.letta.com/v1/agents/$AGENT_ID/messages \
3
  --header 'Authorization: Bearer LETTA_API_KEY' \
4
  --header 'Content-Type: application/json' \
5
  --data '{
6
  "messages": [
7
    {
8
      "role": "user",
9
      "content": "hows it going????"
10
    }
11
  ]
12
}'

The response contains the agent’s full response to the message, which includes reasoning steps (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": "User seems curious and casual. Time to engage!"
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": "Hey there! I'm doing great, thanks for asking! How about you?"
14
    }
15
  ],
16
  "usage": {
17
    "completion_tokens": 56,
18
    "prompt_tokens": 2030,
19
    "total_tokens": 2086,
20
    "step_count": 1
21
  }
22
}

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

Viewing the agent in the ADE

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

If we click on “Open in ADE”, we should see our agent in full detail, 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.