子代理

用于任务分解和并行执行的无状态代理

子代理是您的代理将任务委托给的工作者。要将知识加载到代理的记忆中，请参阅技能。

子代理是专门的、无状态的代理，您的主代理可以生成它们来自主处理复杂任务。您的代理可以在单个对话中做所有事情，而是将工作委托给专注的子代理，它们独立运行并返回结果。

Letta Code 支持五种子代理类型：

explore — 快速代码库搜索（只读）
general-purpose — 完整实现（可以编辑文件）
memory — 清理和重组记忆块
plan — 分解复杂任务（只读）
recall — 搜索对话历史（只读）

工作原理

当您的主代理遇到复杂任务时，它可以使用 Task 工具启动子代理：

Task(
    subagent_type="explore",
    description="Find auth code",
    prompt="Search for all authentication-related files in src/. List paths and summarize the approach."
)

子代理使用自己的系统提示、工具和模型自主运行。完成时返回单个最终报告。您的主代理接收结果并继续。

关键特性：

无状态：每次调用都是独立的——调用之间没有记忆持久化
自主：子代理不能在执行过程中提问；所有上下文必须预先提供
上下文感知：子代理看到完整的对话历史，所以它们理解之前发生的事情
并行：可以同时启动多个子代理处理独立任务
后台：任务可以使用 run_in_background 在后台运行，完成时通知您

内置子代理

Letta Code 包含五个为常见工作流程优化的内置子代理。

explore

一个快速、轻量级的代理，用于搜索和理解代码库。它可以查找文件、搜索模式并探索项目结构——但不能进行更改。

使用快速模型（Haiku）保持搜索快速且便宜。当您的代理需要在处理代码之前定位代码时，通常会生成 explore 子代理。

示例提示：

> Use an explore agent to find all database models
> Spawn an explore subagent to locate error handling code
> Have an explore agent map out the authentication flow

general-purpose

一个全功能代理，可以研究、规划和实现。它可以访问所有工具，包括文件编辑，因此它可以实际更改您的代码库。

使用平衡的模型（Sonnet）以合理的成本获得良好的推理能力。当您的代理需要实现实质性内容时，会委托到这里。

示例提示：

> Use a general-purpose agent to implement the password reset feature
> Spawn a general-purpose subagent to refactor the logging system
> Have a general-purpose agent add tests for the user module

memory

一个记忆管理代理，清理和重组您代理的记忆块。它移除冗余、添加结构、解决矛盾并提高可扫描性。与 defragmenting-memory 技能配合使用进行备份/恢复工作流程。

使用高推理模型（Opus），因为记忆重组需要仔细判断保留、合并或删除什么。以提升的权限运行以直接编辑记忆文件。

示例提示：

> Use a memory agent to clean up and reorganize my memory blocks
> Spawn a memory subagent to remove redundancy from the project block
> Have a memory agent restructure and consolidate my persona block

plan

一个规划代理，将复杂任务分解为可操作的步骤。它探索代码库并创建详细的实施路线图——但自己不进行更改。

使用高推理模型（Opus）彻底思考复杂问题。期望得到详细的、结构化的输出和逐步指导。

示例提示：

> Use a plan agent to design the user authentication system
> Have a plan subagent break down the migration to TypeScript
> Spawn a plan agent to architect the new notification system

recall

一个搜索代理，用于在对话历史中查找信息。它使用 searching-messages 技能定位可能已超出主代理上下文窗口的过去讨论、决策和上下文。

使用高推理模型（Opus）进行对话历史的彻底分析。当您的代理需要记住之前讨论的内容时，会生成 recall 子代理。

示例提示：

> Use a recall agent to find what we discussed about the database schema
> Have a recall subagent search for any decisions made about authentication
> Spawn a recall agent to find when we last talked about deployment

使用子代理

您的代理通过 Task 工具自动访问子代理。您不需要配置任何东西——只需描述您的任务，您的代理会决定何时委托。

您也可以通过提示明确请求使用子代理：

> Use the explore subagent to find all database connection code

覆盖模型

每种子代理类型都有默认模型，但您可以请求使用不同的模型：

> Use a plan agent with Sonnet to design the migration
> Spawn an explore agent with Opus for a thorough codebase analysis
> Use a general-purpose agent with Haiku for this quick fix

限制轮次

您可以使用 max_turns 参数限制子代理进行多少轮。这可以防止开放性任务上的失控代理：

Task(
    subagent_type="general-purpose",
    description="Quick fix",
    prompt="Fix the typo in README.md",
    max_turns=5
)

并行执行

您可以请求多个子代理同时工作：

> Spawn two explore agents: one to search the frontend for React components,
and another to find all API routes in the backend

后台任务

在后台启动子代理，以便在它运行时继续工作。代理在后台任务完成时收到通知。

Task(
    subagent_type="explore",
    description="Find all API routes",
    prompt="Search the entire codebase for API route definitions.",
    run_in_background=True
)

后台任务将其输出写入文件。使用 TaskOutput 检查任务的进度或检索其结果，使用 TaskStop 取消正在运行的任务。

Bash 工具也支持 run_in_background 用于长时间运行的 shell 命令。

查看可用子代理

使用 /subagents 命令查看所有可用的子代理（内置和自定义）：

> /subagents

刷新子代理列表

如果您或代理在会话期间修改了 .letta/agents/ 中的自定义子代理，代理可以刷新其子代理列表：

> Refresh your subagents list

这会重新发现内置类型和 .letta/agents/ 目录中的自定义定义中的所有子代理。重新启动 Letta Code 也会刷新子代理列表。

创建自定义子代理

通过将带有 YAML 前置内容的 Markdown 文件添加到 .letta/agents/ 目录来创建自定义子代理。

文件结构

.letta/
└── agents/
    └── my-subagent.md

您也可以在 ~/.letta/agents/ 创建跨所有项目可用的全局子代理。

子代理文件格式

---
name: security-reviewer
description: Reviews code for security vulnerabilities and suggests fixes
tools: Glob, Grep, Read
model: sonnet-4.5
memoryBlocks: human, persona
---

You are a security code reviewer.

## Instructions
- Search for common vulnerability patterns (SQL injection, XSS, etc.)
- Check authentication and authorization code
- Review input validation
- Identify hardcoded secrets or credentials

## Output Format
1. List of findings with severity (critical/high/medium/low)
2. File paths and line numbers for each issue
3. Recommended fixes

前置内容字段

字段	必需	描述
`name`	是	唯一标识符（小写，允许连字符）。必须以字母开头。
`description`	是	何时使用此子代理（显示在 Task 工具和 /subagents 中）
`tools`	否	允许的工具列表（逗号分隔），或 `all`。默认为 `all`。
`model`	否	使用的模型（例如 `haiku`、`sonnet-4.5`、`opus`）。默认从主代理继承。
`memoryBlocks`	否	子代理可以访问哪些记忆块：特定列表、`all` 或 `none`。默认为 `all`。
`skills`	否	自动加载的技能列表（逗号分隔）

系统提示

Markdown 文件的正文（前置内容之后）成为子代理的系统提示。为子代理应该做什么以及如何格式化输出编写清晰的指令。

覆盖优先级

自定义子代理覆盖同名的内置代理。项目级子代理（.letta/agents/）覆盖全局代理（~/.letta/agents/）。

使用自定义子代理

定义后，用自然语言请求您的自定义子代理：

> Use the security-reviewer agent to review the authentication module
> Run security-reviewer on the entire src/api directory

何时使用子代理

好的用例：

大型代码库搜索："查找我们处理用户认证的所有地方"
实现前规划："设计迁移到新数据库的方法"
并行调查："同时检查前端和后端的 API 端点"
独立实现："为支付处理模块添加日志"

何时不要使用子代理：

需要澄清：如果您不确定想要什么，先与主代理交互
简单、快速的任务："读取配置文件"不需要子代理
需要逐步指导：如果您想审查每个更改，让主代理保持控制

技巧

预先具体化：子代理不能提出后续问题。不要说"探索认证代码"，尝试"查找所有认证相关的文件并总结认证流程"
请求特定输出：告诉子代理您想要什么返回。"列出所有 API 端点及其 HTTP 方法和路径"比"查找 API 端点"更清晰
为您的工作流程创建自定义子代理：如果您经常进行安全审查、迁移或其他专门任务，创建一个自定义子代理