The official Python library for the letta API
Project description
Letta Python SDK
Letta is the platform for building stateful agents: open AI with advanced memory that can learn and self-improve over time.
- Letta Code: run agents locally in your terminal
- Letta API: build agents into your applications
Get started
Install the Letta Python SDK:
pip install letta-client
Simple Hello World example
Below is a quick example of creating a stateful agent and sending it a message (requires a Letta API key, or setting base_url=... to point at a Docker server).
See the full quickstart guide for complete documentation.
from letta_client import Letta
client = Letta(api_key="LETTA_API_KEY")
agent_state = client.agents.create(
model="openai/gpt-4o-mini",
embedding="openai/text-embedding-3-small",
memory_blocks=[
{
"label": "human",
"value": "The human's name is Chad. They like vibe coding."
},
{
"label": "persona",
"value": "My name is Sam, a helpful assistant."
}
],
tools=["web_search", "run_code"]
)
print(agent_state.id)
# agent-d9be...0846
response = client.agents.messages.create(
agent_id=agent_state.id,
messages=[
{
"role": "user",
"content": "Hey, nice to meet you, my name is Brad."
}
]
)
# the agent will think, then edit its memory using a tool
for message in response.messages:
print(message)
# The content of this memory block will be something like
# "The human's name is Brad. They like vibe coding."
# Fetch this block's content with:
human_block = client.agents.blocks.retrieve(agent_id=agent_state.id, block_label="human")
print(human_block.value)
Core concepts in Letta:
Letta is built on the MemGPT research paper, which introduced the concept of the "LLM Operating System" for memory management:
- Memory Hierarchy: Agents have self-editing memory split between in-context and out-of-context memory
- Memory Blocks: In-context memory is composed of persistent editable blocks
- Agentic Context Engineering: Agents control their context window using tools to edit, delete, or search memory
- Perpetual Self-Improving Agents: Every agent has a perpetual (infinite) message history
Key Features
Memory Management (full guide)
Memory blocks are persistent, editable sections of an agent's context window:
# Create agent with memory blocks
agent = client.agents.create(
memory_blocks=[
{"label": "persona", "value": "I'm a helpful assistant."},
{"label": "human", "value": "User preferences and info."}
]
)
# Update blocks manually
client.agents.blocks.update(
agent_id=agent.id,
block_label="human",
value="Updated user information"
)
# Retrieve a block
block = client.agents.blocks.retrieve(agent_id=agent.id, block_label="human")
Multi-agent Shared Memory (full guide)
Memory blocks can be attached to multiple agents. All agents will have an up-to-date view on the contents of the memory block -- if one agent modifies it, the other will see it immediately.
Here is how to attach a single memory block to multiple agents:
# Create shared block
shared_block = client.blocks.create(
label="organization",
value="Shared team context"
)
# Attach to multiple agents
agent1 = client.agents.create(
memory_blocks=[{"label": "persona", "value": "I am a supervisor"}],
block_ids=[shared_block.id]
)
agent2 = client.agents.create(
memory_blocks=[{"label": "persona", "value": "I am a worker"}],
block_ids=[shared_block.id]
)
Sleep-time Agents (full guide)
Background agents that share memory with your primary agent:
agent = client.agents.create(
model="openai/gpt-4o-mini",
enable_sleeptime=True # creates a sleep-time agent
)
Agent File Import/Export (full guide)
Save and share agents with the .af file format:
# Import agent
with open('/path/to/agent.af', 'rb') as f:
agent = client.agents.import_file(file=f)
# Export agent
schema = client.agents.export_file(agent_id=agent.id)
MCP Tools (full guide)
Connect to Model Context Protocol servers:
# First, create an MCP server (example: weather server)
weather_server = client.mcp_servers.create(
server_name="weather-server",
config={
"mcp_server_type": "streamable_http",
"server_url": "https://weather-mcp.example.com/mcp",
}
)
# List tools available from the MCP server
tools = client.mcp_servers.tools.list(weather_server.id)
# Create agent with MCP tool
agent = client.agents.create(
model="openai/gpt-4o-mini",
tool_ids=[tool.id]
)
Filesystem (full guide)
Give agents access to files:
# Create folder and upload file
folder = client.folders.create(
name="my_folder",
)
with open("file.txt", "rb") as f:
client.folders.files.upload(file=f, folder_id=folder.id)
# Attach to agent
client.agents.folders.attach(agent_id=agent.id, folder_id=folder.id)
Long-running Agents (full guide)
Background execution with resumable streaming:
stream = client.agents.messages.create(
agent_id=agent.id,
messages=[{"role": "user", "content": "Analyze this dataset"}],
background=True
)
run_id = None
last_seq_id = None
for chunk in stream:
run_id = chunk.run_id
last_seq_id = chunk.seq_id
# Resume if disconnected
for chunk in client.runs.stream(run_id=run_id, starting_after=last_seq_id):
print(chunk)
Streaming (full guide)
Stream responses in real-time:
stream = client.agents.messages.stream(
agent_id=agent.id,
messages=[{"role": "user", "content": "Hello!"}]
)
for chunk in stream:
print(chunk)
These methods return an APIResponse object.
The async client returns an AsyncAPIResponse with the same structure, the only difference being awaitable methods for reading the response content.
Message Types (full guide)
Agent responses contain different message types. Handle them with the message_type discriminator:
messages = client.agents.messages.list(agent_id=agent.id)
for message in messages:
if message.message_type == "user_message":
print(f"User: {message.content}")
elif message.message_type == "assistant_message":
print(f"Agent: {message.content}")
elif message.message_type == "reasoning_message":
print(f"Reasoning: {message.reasoning}")
elif message.message_type == "tool_call_message":
print(f"Tool: {message.tool_call.name}")
elif message.message_type == "tool_return_message":
print(f"Result: {message.tool_return}")
Python Support
Full type hints and async support:
from letta_client import Letta
from letta_client.types import CreateAgentRequest
# Sync client
client = Letta(api_key="LETTA_API_KEY")
# Async client
from letta_client import AsyncLetta
async_client = AsyncLetta(api_key="LETTA_API_KEY")
agent = await async_client.agents.create(
model="openai/gpt-4o-mini",
memory_blocks=[...]
)
Error Handling
from letta_client.core.api_error import ApiError
try:
client.agents.messages.create(agent_id=agent_id, messages=[...])
except ApiError as e:
print(e.status_code)
print(e.message)
print(e.body)
Advanced Configuration
Retries
response = client.agents.create(
{...},
request_options={"max_retries": 3} # Default: 2
)
Timeouts
response = client.agents.create(
{...},
request_options={"timeout_in_seconds": 30} # Default: 60
)
Custom Headers
response = client.agents.create(
{...},
request_options={
"additional_headers": {
"X-Custom-Header": "value"
}
}
)
Raw Response Access
response = client.agents.with_raw_response.create({...})
print(response.headers["X-My-Header"])
print(response.data) # access the underlying object
Custom HTTP Client
import httpx
from letta_client import Letta
client = Letta(
httpx_client=httpx.Client(
proxies="http://my.test.proxy.example.com",
transport=httpx.HTTPTransport(local_address="0.0.0.0"),
)
)
Runtime Compatibility
Works with:
- Python 3.8+
- Supports async/await
- Compatible with type checkers (mypy, pyright)
Contributing
Letta is an open source project built by over a hundred contributors. There are many ways to get involved in the Letta OSS project!
- Join the Discord: Chat with the Letta devs and other AI developers.
- Chat on our forum: If you're not into Discord, check out our developer forum.
- Follow our socials: Twitter/X, LinkedIn, YouTube
This SDK is generated programmatically. For SDK changes, please open an issue.
README contributions are always welcome!
Resources
License
MIT
Legal notices: By using Letta and related Letta services (such as the Letta endpoint or hosted service), you are agreeing to our privacy policy and terms of service.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file letta_client-1.7.9.tar.gz.
File metadata
- Download URL: letta_client-1.7.9.tar.gz
- Upload date:
- Size: 267.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d6fbc9fc16c254df3b21620009e743d45b54f48fd054c70792d3c8d6d6e0bd59
|
|
| MD5 |
61c2f0d22871b1f532d9c14cd1f11fad
|
|
| BLAKE2b-256 |
8c136af905840455940e49b8bd6121897ff2ba9b9042be86d79663986461e5e1
|
File details
Details for the file letta_client-1.7.9-py3-none-any.whl.
File metadata
- Download URL: letta_client-1.7.9-py3-none-any.whl
- Upload date:
- Size: 388.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c83b2e99c3ace7d7bcde1f5dbded2643d79f373869a57bcfcb32534889be3345
|
|
| MD5 |
9ec862c73ae5e77d001994db72ec5a1e
|
|
| BLAKE2b-256 |
aa6af15dd165bd6631b3cf245f01989c67829f8a6a7380087fb53096f40da55f
|
