Letta API Client Skill

Build applications on top of the Letta API — a model-agnostic, stateful API for building persistent agents with memory and long-term learning. The Letta API powers Letta Code and the Learning SDK. This skill covers the core patterns for creating agents, managing memory, building custom tools, and handling multi-user scenarios.

When to Use This Skill

Building applications that need persistent, stateful AI agents
Creating chatbots, assistants, or autonomous agents with memory
Integrating Letta into existing web/mobile applications
Building multi-user applications where each user has their own agent
Understanding the API layer that Letta Code and Learning SDK are built on

Quick Start

See getting-started.md for first-time setup and common onboarding issues.

SDK Versions Tested

Examples last tested with:

Python SDK:
```
letta-client==1.7.1
```
TypeScript SDK:
```
@letta-ai/letta-client@1.7.1
```

Core Concepts

1. Client Setup

See client-setup.md for initialization patterns:

Letta Cloud vs self-hosted connections
Environment variable management
Singleton patterns for web frameworks

2. Memory Architecture

See memory-architecture.md for memory patterns:

Core Memory Blocks: Always in-context (persona, human, custom blocks)
Archival Memory: Large corpus with semantic search
Conversation History: Searchable message history
Shared Blocks: Multi-agent coordination

3. Custom Tools

See custom-tools.md for tool creation:

Simple function tools with auto-generated schemas
Tools with environment variable secrets
BaseTool class for complex schemas
Sandboxed execution requirements

4. Client-Side Tools

See client-side-tools.md for local tool execution:

Execute tools on your machine while agent runs on Letta API
How Letta Code runs Bash/Read/Write locally
Approval-based flow with
```
type: "tool"
```
responses
Access local files, databases, and private APIs

5. Client Injection & Secrets

See client-injection.md for server-side tool patterns:

Pre-injected
```
client
```
variable on Letta Cloud
Building custom memory tools that modify agent state
Agent secrets via
```
os.getenv()
```
```
LETTA_AGENT_ID
```
for self-referential tools

6. Multi-User Patterns

See multi-user.md for scaling:

One agent per user (personalization)
Shared agent with Conversations API
Identity system for user context

7. Streaming

See streaming.md for real-time responses:

Basic SSE streaming
Long-running operations with
```
include_pings
```
Background execution and resumable streams

8. Conversations

Conversations enable parallel sessions with shared memory:

Thread-safe concurrent messaging (agents.messages.create is NOT thread-safe)
Shared memory blocks across all conversations
Separate context windows per conversation
Use for: same user with multiple parallel tasks, multi-threaded applications

9. Sleeptime Agents

See sleeptime.md for background memory processing:

Enable with
```
enable_sleeptime=True
```
Background agent refines memory between conversations
Good for agents that learn over time

10. Agent Files & Folders

See agent-files.md for portability and file access:

Export/import agents with
```
.af
```
files
Attach folders to give agents document access
Migration checklist for moving agents

11. Tool Rules

See tool-rules.md for constraining tool execution:

```
InitToolRule
```
- Force a tool to run first
```
ChildToolRule
```
- Control which tools can follow
```
TerminalToolRule
```
- End agent turn after tool
Sequential pipelines and approval workflows

Quick Reference

Python SDK

bash

pip install letta-client

python

from letta_client import Letta

# Cloud
client = Letta(api_key="LETTA_API_KEY")

# Self-hosted
client = Letta(base_url="http://localhost:8283")

TypeScript SDK

bash

npm install @letta-ai/letta-client

typescript

import { Letta } from "@letta-ai/letta-client";

// Cloud
const client = new Letta({ apiKey: process.env.LETTA_API_KEY });

// Self-hosted
const client = new Letta({ baseUrl: "http://localhost:8283" });

Examples

See the

examples/

directory for runnable code:

Python:

```
01_basic_client.py
```
- Client initialization
```
02_create_agent.py
```
- Agent creation with memory blocks
```
03_custom_tool_simple.py
```
- Basic custom tool
```
04_custom_tool_secrets.py
```
- Tool with environment variables
```
05_send_message.py
```
- Basic messaging
```
06_send_message_stream.py
```
- Streaming responses
```
07_multi_user.py
```
- Multi-user patterns
```
08_archival_memory.py
```
- Archival memory operations
```
09_shared_blocks.py
```
- Multi-agent shared memory
```
10_conversations.py
```
- Parallel sessions with conversations
```
11_client_injection.py
```
- Custom memory tools with injected client
```
12_tool_rules.py
```
- Constraining tool execution order
```
13_client_side_tools.py
```
- Execute tools locally (like Letta Code)

TypeScript:

```
01_basic_client.ts
```
- Client initialization
```
02_create_agent.ts
```
- Agent creation
```
03_send_message.ts
```
- Basic messaging
```
04_send_message_stream.ts
```
- Streaming
```
05_nextjs_singleton.ts
```
- Next.js pattern
```
06_multi_user.ts
```
- Multi-user patterns
```
07_conversations.ts
```
- Parallel sessions
```
08_custom_tool.ts
```
- Custom tools with secrets
```
09_archival_memory.ts
```
- Long-term storage
```
10_shared_blocks.ts
```
- Multi-agent shared memory
```
11_client_injection.ts
```
- Custom memory tools
```
12_tool_rules.ts
```
- Tool execution order
```
13_client_side_tools.ts
```
- Execute tools locally (like Letta Code)

Troubleshooting

Error	Cause	Fix
401 Unauthorized	Invalid or missing API key	Check `LETTA_API_KEY` env var
422 Validation Error	Missing required field	Add `model` , `embedding` , or `memory_blocks`
Tool not found	Tool not attached to agent	`client.agents.tools.attach(agent_id, tool_id)`
`os.getenv()` returns None	Secret not configured	Add to agent via `secrets` parameter
524 Timeout	Long operation without pings	Add `include_pings=True` to streaming
Agent not responding	Model issue or empty response	Check for `assistant_message` type in response
Memory block not updating	Looking at wrong agent	Verify `agent_id` matches
Import error in tool	Top-level import	Move imports inside function body

Key Gotchas

Imports in tools must be inside the function - Tools run in a sandbox without access to top-level imports
Use
os.getenv()
for secrets - Don't pass sensitive data as function arguments
On Cloud, use injected
client
- Don't instantiate
```
Letta()
```
inside tools, use the pre-injected client
Memory blocks are character-limited - Use archival memory for large data
Streaming requires
include_pings=True
for long operations - Prevents timeout on Cloud
SDK 1.0 uses
.update()
not
.modify()
- Method was renamed
LETTA_AGENT_ID
is always available - Use it in tools to reference the current agent
Archival tools need
include_base_tools=True
- Not attached by default
Use
memory_insert
for shared blocks - Safest for concurrent writes (append-only)
Tool docstrings require Args section - Parameters need descriptions or schema generation fails

TypeScript SDK Notes

typescript

// Client initialization uses baseURL (not baseUrl)
const client = new Letta({ apiKey: "...", baseURL: "http://localhost:8283" });

// Block API: positional args changed
client.agents.blocks.attach(blockId, { agent_id });      // blockId is first
client.agents.blocks.retrieve(blockLabel, { agent_id }); // label is first

// Passages.create returns array
const passages = await client.agents.passages.create(agentId, { text: "..." });
const passage = passages[0];

// Content can be string | array - use type guard
const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);

// Conversations API returns streams by default
const stream = await client.conversations.messages.create(convId, { messages: [...] });
for await (const chunk of stream) { ... }

// Tool rule types
{ type: "run_first", tool_name: "..." }           // InitToolRule
{ type: "constrain_child_tools", tool_name: "...", children: [...] } // ChildToolRule  
{ type: "exit_loop", tool_name: "..." }           // TerminalToolRule

Quick Reference

python

# Client
client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Create agent
agent = client.agents.create(
    model="anthropic/claude-sonnet-4-5-20250929",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[{"label": "persona", "value": "..."}],
    include_base_tools=True,  # archival memory tools
    enable_sleeptime=True,    # background memory processing
)

# Send message
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Hello"}]
)

# Stream response
stream = client.agents.messages.stream(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Hello"}],
    stream_tokens=True,
    include_pings=True,  # prevent timeout
)

# Create tool
tool = client.tools.create(source_code="def my_tool(x: str) -> str: ...")
client.agents.tools.attach(agent_id=agent.id, tool_id=tool.id)

# Memory blocks
client.agents.blocks.retrieve(agent_id=agent.id, block_label="persona")
client.agents.blocks.update(agent_id=agent.id, block_label="persona", value="...")

# Folders
folder = client.folders.create(name="docs")
client.folders.files.upload(file=f, folder_id=folder.id)
client.agents.folders.attach(agent_id=agent.id, folder_id=folder.id)

# Conversations (parallel sessions)
conv = client.conversations.create(agent_id=agent.id)
stream = client.conversations.messages.create(conv.id, messages=[...])

# Agent secrets (for tools)
client.agents.update(agent_id=agent.id, secrets={"API_KEY": "..."})

Resources

Platform:

Letta Cloud (ADE) - Agent Development Environment
API Keys - Get your API key

Documentation:

Letta Docs - Full documentation
Agents Guide - Agent concepts
Memory Blocks - Memory architecture
Custom Tools - Tool creation
Streaming - Real-time responses
Multi-User - Scaling patterns

SDKs:

Python SDK -
```
pip install letta-client
```
TypeScript SDK -
```
npm install @letta-ai/letta-client
```

Examples:

Chatbot Example - Full app example

letta-api-client

NPX Install

Tags

SKILL.md Content

Letta API Client Skill

When to Use This Skill

Quick Start

SDK Versions Tested

Core Concepts

1. Client Setup

2. Memory Architecture

3. Custom Tools

4. Client-Side Tools

5. Client Injection & Secrets

6. Multi-User Patterns

7. Streaming

8. Conversations

9. Sleeptime Agents

10. Agent Files & Folders

11. Tool Rules

Quick Reference

Python SDK

TypeScript SDK

Examples

Troubleshooting

Key Gotchas

TypeScript SDK Notes

Quick Reference

Resources