技能是可重用的代理功能,提供专门的工作流程和领域知识。文档索引
在以下地址获取完整的文档索引:https://docs.langchain.org.cn/llms.txt
在进一步探索之前,请使用此文件发现所有可用页面。
技能需要
deepagents>=1.7.0。什么是技能
技能是一个文件夹目录,其中每个文件夹包含一个或多个文件,这些文件提供了代理可以使用的上下文- 包含有关该技能说明和元数据的
SKILL.md文件 - 附加脚本(可选)
- 附加参考信息,如文档(可选)
- 附加资产,如模板和其他资源(可选)
任何附加资产(脚本、文档、模板或其他资源)必须在
SKILL.md 文件中引用,并附带有关文件内容及其使用方法的信息,以便代理决定何时使用它们。技能的工作原理
当您创建 Deep Agent 时,可以传入包含技能的目录列表。当代理启动时,它会读取每个SKILL.md 文件的元数据(frontmatter)。 当代理收到提示词时,它会检查在满足该提示词的过程中是否可以使用任何技能。如果找到匹配的提示词,它会随后查看剩余的技能文件。这种仅在需要时才查阅技能信息的模式称为渐进式披露(progressive disclosure)。示例
您可能拥有一个包含“以特定方式使用文档网站”技能的技能文件夹,以及另一个用于搜索 arXiv 预印本研究论文库的技能SKILL.md 文件总是遵循相同的模式,以元数据(frontmatter)开头,后面紧跟该技能的说明。 以下示例展示了一个技能,该技能提供了有关在收到提示时如何提供相关 LangGraph 文档的说明:完整示例
以下示例展示了一个使用所有可用元数据字段的SKILL.md 文件
用法
在创建 Deep Agent 时传入技能目录- StateBackend
- StoreBackend
- FilesystemBackend
技能来源路径列表。路径必须使用正斜杠指定,并且是相对于后端根目录的。
- 如果省略,则不会加载任何技能。
- 使用
StateBackend(默认)时,请通过invoke(files={...})提供技能文件。 - 使用
FilesystemBackend时,技能将从相对于后端root_dir的磁盘路径中加载。
SDK 仅加载您在
skills 中传入的来源。它不会自动扫描 CLI 目录,例如 ~/.deepagents/... 或 ~/.agents/...。有关 CLI 存储惯例,请参阅 应用数据。在 SDK 中模拟 CLI 来源顺序
在 SDK 中模拟 CLI 来源顺序
如果您想在 SDK 代码中实现 CLI 风格的分层,请明确按照优先级从低到高的顺序传入所有所需的来源然后在创建代理时,将该有序列表作为
skills 传入。来源优先级
当多个技能来源包含同名技能时,在skills 数组中靠后列出的来源中的技能具有优先权(最后生效)。这允许您对来自不同来源的技能进行分层。
子代理的技能
当您使用 子代理 时,您可以配置每种类型可以访问哪些技能- 通用子代理:当您将
skills传递给create_deep_agent时,它会自动继承主代理的技能。无需额外配置。 - 自定义子代理:不会继承主代理的技能。请在每个子代理定义中添加一个
skills参数,并指定该子代理的技能来源路径。
代理所看到的内容
当配置了技能后,“技能系统”部分会被注入到代理的系统提示词中。代理利用此信息遵循三个步骤的过程- 匹配(Match)— 当用户提示到达时,代理会检查是否有技能的描述与任务相匹配。
- 读取(Read)— 如果某项技能适用,代理会使用其技能列表中显示的路径读取完整的
SKILL.md文件。 - 执行(Execute)— 代理遵循技能说明,并根据需要访问任何配套文件(脚本、模板、参考文档)。
在沙箱中执行技能脚本
技能可以在SKILL.md 文件旁边包含脚本,例如执行搜索或数据转换的 Python 文件。代理可以从任何后端读取这些脚本,但要执行它们,代理需要访问 shell —— 而这只有 沙箱后端 才能提供。 当您使用 CompositeBackend 将技能路由到 StoreBackend 进行持久化,同时以沙箱作为默认后端时,技能文件位于存储中,而不是代码运行的沙箱中。为了使沙箱能够使用这些脚本,您必须使用 自定义中间件 在代理启动前将技能脚本上传到沙箱中:beforeAgent 钩子在每次代理调用之前运行,从共享命名空间读取技能文件并将其上传到沙箱文件系统中。一旦同步,代理就可以像沙箱中的任何其他文件一样使用 execute 工具来执行脚本。 有关同步 记忆 的更完整双向同步示例,请参阅 通过自定义中间件同步技能和记忆。技能与记忆的区别
技能和 记忆 (AGENTS.md 文件) 的用途不同
| 技能 | 内存 | |
|---|---|---|
| 目的 | 通过渐进式披露发现的按需功能 | 启动时始终加载的持久化上下文 |
| 加载方式 | 仅在代理确定相关性时读取 | 始终注入系统提示词中 |
| 格式 | 命名目录中的 SKILL.md | AGENTS.md 文件 |
| 分层 | 用户 → 项目(最后生效) | 用户 → 项目(合并) |
| 使用场景 | 说明是任务特定的,且可能很大 | 上下文始终相关(项目惯例、偏好) |
何时使用技能与工具
以下是使用工具和技能的一些通用准则- 当上下文较多时,使用技能以减少系统提示词中的 Token 数量。
- 使用技能将功能捆绑成更大的操作,并提供超出单一工具描述的额外上下文。
- 如果代理无法访问文件系统,请使用工具。
将这些文档连接到 Claude、VSCode 等,以获得实时答案。

