letta-api-client

Letta API 客户端技能

基于 Letta API 构建应用——这是一个与模型无关、有状态的 API，可用于构建具备记忆和长期学习能力的持久化 Agent。Letta API 为 Letta Code 和 Learning SDK 提供支持。本技能涵盖创建 Agent、管理记忆、构建自定义工具以及处理多用户场景的核心模式。

何时使用此技能

• 构建需要持久化、有状态 AI Agent 的应用
• 创建具备记忆能力的聊天机器人、助手或自主 Agent
• 将 Letta 集成到现有的 Web/移动应用中
• 构建每位用户都有专属 Agent 的多用户应用
• 了解 Letta Code 和 Learning SDK 所基于的 API 层

快速入门

首次设置和常见入门问题，请参阅 getting-started.md。

已测试的 SDK 版本

示例最近一次测试使用的版本：

• Python SDK：letta-client==1.7.1
• TypeScript SDK：@letta-ai/[email protected]

核心概念

1. 客户端设置

初始化模式请参阅 client-setup.md：

• Letta Cloud 与可自托管连接
• 环境变量管理
• Web 框架的单例模式

2. 记忆架构

记忆模式请参阅 memory-architecture.md：

• 核心记忆块：始终位于上下文中（角色设定、人类信息、自定义块）
• 归档记忆：支持语义搜索的大型语料库
• 对话历史：可搜索的消息历史记录
• 共享块：多 Agent 协作

3. 自定义工具

工具创建请参阅 custom-tools.md：

• 使用自动生成架构的简单函数工具
• 带有环境变量密钥的工具
• 用于复杂架构的 BaseTool 类
• 沙盒执行要求

4. 客户端工具

本地工具执行请参阅 client-side-tools.md：

• 当 Agent 在 Letta API 上运行时，在你的机器上执行工具
• Letta Code 如何在本地运行 Bash/Read/Write
• 使用 type: "tool" 响应的审批流程
• 访问本地文件、数据库和私有 API

5. 客户端注入与密钥

服务端工具模式请参阅 client-injection.md：

• 在 Letta Cloud 上预先注入的 client 变量
• 构建可修改 Agent 状态的自定义记忆工具
• 通过 os.getenv() 获取 Agent 密钥
• 用于自引用工具的 LETTA_AGENT_ID

6. 多用户模式

扩展方案请参阅 multi-user.md：

• 每位用户一个 Agent（个性化）
• 使用 Conversations API 的共享 Agent
• 用于用户上下文的身份系统

7. 流式传输

实时响应请参阅 streaming.md：

• 基本 SSE 流式传输
• 使用 include_pings 处理长时间运行的操作
• 后台执行和可恢复流

8. 对话

对话支持共享记忆的并行会话：

• 线程安全的并发消息（agents.messages.create 不是线程安全的）
• 所有对话共享记忆块
• 每个对话使用独立的上下文窗口
• 适用场景：同一用户同时处理多项任务、多线程应用

9. 休眠 Agent

后台记忆处理请参阅 sleeptime.md：

• 使用 enable_sleeptime=True 启用
• 后台 Agent 会在对话之间完善记忆
• 适用于随时间不断学习的 Agent

10. Agent 文件与文件夹

可移植性和文件访问请参阅 agent-files.md：

• 使用 .af 文件导出/导入 Agent
• 附加文件夹，为 Agent 提供文档访问权限
• Agent 迁移检查清单

11. 工具规则

限制工具执行请参阅 tool-rules.md：

• InitToolRule - 强制首先运行某个工具
• ChildToolRule - 控制后续可以运行哪些工具
• TerminalToolRule - 在工具运行后结束 Agent 轮次
• 顺序流水线和审批工作流

快速参考

Python SDK

pip install letta-client

from letta_client import Letta

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

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

TypeScript SDK

npm install @letta-ai/letta-client

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/ 目录：

Python：

• 01_basic_client.py - 客户端初始化
• 02_create_agent.py - 使用记忆块创建 Agent
• 03_custom_tool_simple.py - 基本自定义工具
• 04_custom_tool_secrets.py - 使用环境变量的工具
• 05_send_message.py - 基本消息收发
• 06_send_message_stream.py - 流式响应
• 07_multi_user.py - 多用户模式
• 08_archival_memory.py - 归档记忆操作
• 09_shared_blocks.py - 多 Agent 共享记忆
• 10_conversations.py - 使用对话创建并行会话
• 11_client_injection.py - 使用注入的客户端创建自定义记忆工具
• 12_tool_rules.py - 限制工具执行顺序
• 13_client_side_tools.py - 在本地执行工具（类似 Letta Code）

TypeScript：

• 01_basic_client.ts - 客户端初始化
• 02_create_agent.ts - 创建 Agent
• 03_send_message.ts - 基本消息收发
• 04_send_message_stream.ts - 流式响应
• 05_nextjs_singleton.ts - Next.js 模式
• 06_multi_user.ts - 多用户模式
• 07_conversations.ts - 并行会话
• 08_custom_tool.ts - 带密钥的自定义工具
• 09_archival_memory.ts - 长期存储
• 10_shared_blocks.ts - 多 Agent 共享记忆
• 11_client_injection.ts - 自定义记忆工具
• 12_tool_rules.ts - 工具执行顺序
• 13_client_side_tools.ts - 在本地执行工具（类似 Letta Code）

故障排除

错误	原因	解决方法
401 未授权	API 密钥无效或缺失	检查 LETTA_API_KEY 环境变量
422 验证错误	缺少必填字段	添加 model、embedding 或 memory_blocks
未找到工具	工具未关联到 Agent	client.agents.tools.attach(agent_id, tool_id)
os.getenv() 返回 None	未配置密钥	通过 secrets 参数添加到 Agent
524 超时	长时间操作未发送 ping	为流式响应添加 include_pings=True
Agent 未响应	模型问题或响应为空	检查响应中是否包含 assistant_message 类型
记忆块未更新	查看了错误的 Agent	确认 agent_id 匹配
工具中的导入错误	顶层导入	将导入语句移入函数体内

关键注意事项

1. 工具中的导入必须放在函数内 - 工具在无法访问顶层导入的沙盒中运行
2. 使用 os.getenv() 获取密钥 - 不要将敏感数据作为函数参数传递
3. 在 Cloud 上使用注入的 client - 不要在工具内实例化 Letta()，应使用预先注入的客户端
4. 记忆块有字符数限制 - 大量数据请使用归档记忆
5. 长时间操作的流式响应需要 include_pings=True - 防止在 Cloud 上超时
6. SDK 1.0 使用 .update() 而非 .modify() - 方法已重命名
7. LETTA_AGENT_ID 始终可用 - 在工具中使用它来引用当前 Agent
8. 归档工具需要 include_base_tools=True - 默认不会关联
9. 使用 memory_insert 处理共享块 - 并发写入时最安全（仅追加）
10. 工具文档字符串必须包含 Args 部分 - 参数需要说明，否则架构生成会失败

TypeScript SDK 说明

// 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

快速参考

# 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": "..."})

资源

平台：

• Letta Cloud (ADE) - Agent 开发环境
• API Keys - 获取 API 密钥

文档：

• Letta Docs - 完整文档
• Agents Guide - Agent 概念
• Memory Blocks - 记忆架构
• Custom Tools - 工具创建
• Streaming - 实时响应
• Multi-User - 扩展模式

SDK：

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

示例：

• Chatbot Example - 完整应用示例