mcpField
L
letta-development-guide

letta-development-guide

github.com/letta-aiAgent 工作流152212 次安装4 周前更新
代码仓库

关于 letta-development-guide

letta-development-guide 是面向 Letta Agent 开发者的设计与构建指南技能，涵盖架构、记忆、模型选择和工具配置，并提供测试与迭代建议。

主要功能

  1. 01选择 Letta 架构
  2. 02设计记忆块
  3. 03模型选择指导
  4. 04工具配置模式
  5. 05记忆容量与并发管理

适用场景

  1. 01规划新的 Letta Agent
  2. 02选择 Agent 架构
  3. 03设计共享 Agent 记忆
  4. 04排查记忆相关问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/letta-ai/skills --skill letta-development-guide

安装后在 Claude Code 中输入/letta-development-guide确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

LICENSE
references/
architectures.md
concurrency.md
description-patterns.md
memory-architecture.md
memory-patterns.md
model-recommendations.md
size-management.md
tool-patterns.md

详细介绍

Letta 开发指南

全面介绍如何通过合适的架构、记忆配置、模型选择和工具设置，设计并构建有效的 Letta Agent。

何时使用此技能

在以下情况下使用此技能：

  • 启动新的 Letta Agent 项目
  • 在不同 Agent 架构（letta_v1_agent 与 memgpt_v2_agent）之间进行选择
  • 设计记忆块结构和架构
  • 为用例选择合适的模型
  • 规划工具配置
  • 优化记忆管理和性能
  • 实现 Agent 之间的共享记忆
  • 调试记忆相关问题

快速入门指南

最小可运行示例
from letta_client import Letta

client = Letta()
agent = client.agents.create(
    name="my-assistant",
    model="openai/gpt-4o",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "You are a helpful assistant."},
        {"label": "human", "value": "The user's name and preferences."},
    ],
)

# Send a message
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.messages[-1].content)
1. 架构选择

以下情况使用 letta_v1_agent：

  • 构建新的 Agent（推荐默认选择）
  • 需要兼容推理模型（GPT-4o、Claude Sonnet 4）
  • 希望使用更简单的系统提示词和直接消息生成

以下情况使用 memgpt_v2_agent：

  • 维护旧版 Agent
  • 需要 v1 尚不支持的特定工具模式

详细比较请参阅 references/architectures.md。

2. 记忆架构设计

记忆是有效 Agent 的基础。Letta 提供三种记忆类型：

核心记忆（上下文内）：

  • 始终可在 Agent 的上下文窗口中访问
  • 用途：当前状态、活动上下文、频繁引用的信息
  • 限制：核心记忆总量应保持在上下文窗口的 80% 以下

归档记忆（上下文外）：

  • 在向量数据库中进行语义搜索
  • 用途：历史记录、大型知识库、过往交互
  • 访问方式：Agent 必须显式调用 archival_memory_search
  • 注意：不会根据上下文溢出自动填充

对话历史：

  • 当前对话中的过往消息
  • 通过 conversation_search 工具检索
  • 用途：引用先前讨论、跟踪对话流程

详细指南请参阅 references/memory-architecture.md。

3. 记忆块设计

核心原则： 每个独立功能单元使用一个记忆块。

必备记忆块：

  • persona：Agent 身份、行为准则、能力
  • human：用户信息、偏好、上下文

根据用例添加特定领域的记忆块：

  • 客户支持：company_policies、product_knowledge、customer
  • 编码助手：project_context、coding_standards、current_task
  • 个人助手：schedule、preferences、contacts

记忆块指南：

  • 保持记忆块聚焦于特定目的
  • 使用清晰、具有指导性的描述
  • 监控大小限制（通常每个记忆块为 2000–5000 个字符）
  • 在 Agent 之间共享记忆时，针对追加操作进行设计

领域示例请参阅 references/memory-patterns.md，撰写有效描述的指南请参阅 references/description-patterns.md。

4. 模型选择

根据 Agent 的需求匹配模型能力：

用于生产环境的 Agent：

  • 复杂推理：GPT-4o 或 Claude Sonnet 4
  • 高性价比的通用任务：GPT-4o-mini
  • 快速、轻量级操作：Claude Haiku 3.5
  • 速度与能力均衡：Gemini 2.0 Flash

避免用于生产环境：

  • 小型 Ollama 模型（<7B 参数）——工具调用能力较差
  • 不支持可靠函数调用的模型

详细指南请参阅 references/model-recommendations.md。

5. 工具配置

从精简配置开始： 仅附加 Agent 会主动使用的工具。

常见的起始配置：

  • 记忆工具（memory_insert、memory_replace、memory_rethink）：大多数 Agent 的核心工具
  • 文件系统工具：连接文件夹后自动附加
  • 自定义工具：用于特定领域的操作（数据库、API 等）

工具规则： 在需要时用于强制执行调用顺序（例如，“回答前始终先调用搜索”）

常见配置请参阅 references/tool-patterns.md。

高级主题

内存大小管理

接近字符数限制时：

  1. 按主题拆分： customer_profile → customer_business、customer_preferences
  2. 按时间拆分： interaction_history → recent_interactions，将更早的内容归档到归档内存
  3. 归档历史数据： 将旧信息移至归档内存
  4. 使用 memory_rethink 进行整合： 总结并重写区块

请参阅 references/size-management.md，了解相关策略。

并发模式

当多个 Agent 共享内存区块，或一个 Agent 处理并发请求时：

最安全的操作：

  • memory_insert：仅追加，竞争条件极少
  • 数据库使用 PostgreSQL 行级锁

竞争条件风险：

  • memory_replace：写入前目标字符串可能已发生变化
  • memory_rethink：以最后写入者为准，不进行合并

最佳实践：

  • 尽可能采用追加操作的设计
  • 并发写入时使用 memory_insert
  • 将 memory_rethink 留给单个 Agent 独占访问的情况

请参阅 references/concurrency.md，了解详细模式。

验证清单

完成 Agent 设计前：

架构：

  • 架构是否与模型的能力相匹配？
  • 模型是否适合预期的工作负载和延迟要求？

内存：

  • 核心内存总量是否低于上下文窗口的 80%？
  • 每个区块是否专注于一个功能领域？
  • 描述是否清晰说明何时读取或写入？
  • 是否已规划容量增长和溢出处理？
  • 如果是多 Agent，是否已考虑并发模式？

工具：

  • 工具是否必要且配置正确？
  • 内存区块是否足够细化，便于有效更新？

常见反模式

内存区块太少：

# Bad: Everything in one block
agent_memory: "Agent is helpful. User is John..."

请改为拆分成职责明确的区块。

内存区块太多： 创建了 10 个以上的区块，而 3-4 个就足够。先从最少的区块开始，并根据需要扩展。

描述欠佳：

# Bad
data: "Contains data"

请改为提供可执行的指导。请参阅 references/description-patterns.md。

忽视大小限制： 放任区块无限增长，直到达到限制。应主动监控和管理。

实施步骤

1. 设计阶段
  • 根据需求选择架构
  • 设计内存区块结构
  • 选择合适的模型
  • 规划工具配置
2. 创建阶段（SDK）

Python：

from letta_client import Letta

client = Letta()  # Uses LETTA_API_KEY env var

# Create agent with custom memory blocks
agent = client.agents.create(
    name="my-agent",
    model="openai/gpt-4o",  # or "anthropic/claude-sonnet-4-20250514"
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "You are a helpful assistant..."},
        {"label": "human", "value": "User preferences and context..."},
        {"label": "project", "value": "Current project details..."},
    ],
    description="Agent for helping with X",
)
print(f"Created agent: {agent.id}")

TypeScript：

import Letta from "letta-client";

const client = new Letta();

const agent = await client.agents.create({
  name: "my-agent",
  model: "openai/gpt-4o",
  embedding: "openai/text-embedding-3-small",
  memoryBlocks: [
    { label: "persona", value: "You are a helpful assistant..." },
    { label: "human", value: "User preferences and context..." },
    { label: "project", value: "Current project details..." },
  ],
  description: "Agent for helping with X",
});
console.log(`Created agent: ${agent.id}`);

注意： Letta Code CLI（letta 命令）可交互式创建 Agent。使用 letta --new-agent 重新开始，然后使用 /rename 和 /description 进行配置。

3. 测试阶段
  • 使用有代表性的查询进行测试
  • 监控内存工具的使用模式
  • 验证工具调用行为
4. 迭代阶段
  • 根据实际使用情况完善内存区块结构
  • 优化系统指令
  • 调整工具配置

参考资料

有关特定主题的详细信息，请参阅以下参考资料：

  • references/architectures.md - 架构比较与选择
  • references/memory-architecture.md - 内存类型及其适用场景
  • references/memory-patterns.md - 特定领域的内存区块示例
  • references/description-patterns.md - 如何编写有效的区块描述
  • references/size-management.md - 管理内存区块大小限制
  • references/concurrency.md - 多 Agent 内存共享模式
  • references/model-recommendations.md - 模型选择指南
  • references/tool-patterns.md - 常见工具配置

评论

支持 Markdown