createDeepAgent 具有以下配置选项:
createDeepAgent API 参考。
模型
传递一个provider:model 格式的 model 字符串,或一个已初始化的模型实例。有关所有提供商,请参阅支持的模型;有关经过测试的推荐模型,请参阅推荐模型。
- OpenAI
- Anthropic
- Azure
- Google Gemini
- Bedrock Converse
- 其他
连接弹性
LangChain 聊天模型会自动使用指数退避策略重试失败的 API 请求。默认情况下,模型会针对网络错误、速率限制 (429) 和服务器错误 (5xx) 重试最多 6 次。客户端错误(如 401 未授权或 404 未找到)不会重试。 您可以在创建模型时调整maxRetries 参数,以根据您的环境调整此行为:
工具
除了用于规划、文件管理和子代理生成的内置工具之外,您还可以提供自定义工具:系统提示
深度代理自带一个内置系统提示。深度代理的价值来自于 SDK 在模型之上提供的编排层——规划、虚拟文件系统工具和子代理——模型需要知道这些工具的存在以及何时使用它们。内置提示教会代理如何使用该脚手架,这样您就不必为每个项目重新推导它;通过配置文件或您自己的system_prompt= 来调整它,而不是逐字复制。
当中间件添加特殊工具(如文件系统工具)时,它会将它们附加到系统提示中。
每个深度代理还应包含一个针对其特定用例的自定义系统提示:
提示组装
深度代理从最多四个命名部分构建系统提示,以便调用者提供的指令、SDK 的内置代理指导以及任何特定于模型的配置文件覆盖可以共存,并具有可预测的优先级。如果没有这种分层,为 Claude(例如)调整的配置文件后缀可能会根据调用顺序覆盖或被您的system_prompt= 参数覆盖;命名槽使顺序明确且稳定。
在实践中,大多数调用者只遇到两个槽:USER(您的 system_prompt=)和 BASE(SDK 默认值)。选择具有内置配置文件的模型——目前是 Anthropic 或 OpenAI——会添加一个 SUFFIX。完整的四部分组装主要在您编写自定义 HarnessProfile 或调试配置文件文本出现位置时相关。
四个命名部分(每个都可能缺失):
顺序始终是
USER -> (BASE 或 CUSTOM) -> SUFFIX,由空行 (\n\n) 连接。由此得出两个不变式:
USER始终在最前面。 调用者的文本优先于任何 SDK 或配置文件内容,因此无论选择哪个模型,角色/指令都具有优先权。SUFFIX始终在最后。 配置文件后缀最接近对话历史,模型调整指导在此处最可靠地生效。
实际示例——内置配置文件(Anthropic、OpenAI)仅提供
system_prompt_suffix,因此典型调用落在 str + - + ✓ 行:
传递
SystemMessage(而不是字符串)会触发不同的连接路径:右侧组装(BASE 或
CUSTOM 加上任何 SUFFIX)作为额外的文本内容块附加到消息现有的
content_blocks 上。相同的逻辑顺序适用(调用者块在前),并且调用者块上的任何
cache_control 标记都会保留——这对于放置显式的 Anthropic 提示缓存断点很有用。子代理提示
子代理提示
相同的覆盖规则适用于声明式子代理——每个子代理根据其自身模型重新运行配置文件解析,然后将解析后的配置文件的
base_system_prompt / system_prompt_suffix 应用于其编写的 system_prompt。子代理的 system_prompt 扮演 BASE 角色;CUSTOM 和 SUFFIX 来自与子代理模型匹配的配置文件(可能与主代理的配置文件不同)。子代理没有
USER 部分——规范中编写的 system_prompt 是最接近的类比,并保留在 BASE 槽中。仅提供 system_prompt_suffix 的配置文件(内置 Anthropic / OpenAI 配置文件的常见情况)只是附加到子代理作者编写的任何内容;设置 base_system_prompt 的配置文件将完全替换编写的提示,因此请谨慎使用该字段。通用子代理提示
通用子代理提示
自动添加的通用子代理遵循相同的覆盖规则,但多了一层:GP 基础提示解析为
general_purpose_subagent.system_prompt(如果已设置)-> HarnessProfile.base_system_prompt(如果已设置)-> SDK GP 默认值。配置文件后缀无论如何都会叠加在上面。两个覆盖字段都可以携带基础提示替换,但它们不可互换。general_purpose_subagent.system_prompt 是 GP 特定的配置;base_system_prompt 是一个全局覆盖,主要针对主代理。当两者都设置时,GP 特定的意图对 GP 子代理生效,因此同时调整这两个字段的用户永远不会看到他们的 GP 覆盖被静默丢弃:如果
general_purpose_subagent.system_prompt 未设置,GP 子代理将回退到 base_system_prompt(如果已设置),最后回退到 SDK GP 默认值。中间件
默认情况下,深度代理可以访问以下中间件:TodoListMiddleware:跟踪和管理待办事项列表,用于组织代理任务和工作FilesystemMiddleware:处理文件系统操作,如读取、写入和导航目录SubAgentMiddleware:生成和协调子代理,将任务委派给专门的代理SummarizationMiddleware:当对话变长时,压缩消息历史记录以保持在上下文限制内AnthropicPromptCachingMiddleware:使用 Anthropic 模型时自动减少冗余的令牌处理PatchToolCallsMiddleware:当工具调用在接收结果之前被中断或取消时,自动修复消息历史记录
MemoryMiddleware:当提供memory参数时,跨会话持久化和检索对话上下文SkillsMiddleware:当提供skills参数时启用自定义技能HumanInTheLoopMiddleware:当提供interruptOn参数时,在指定点暂停以等待人类批准或输入
预构建中间件
LangChain 提供了额外的预构建中间件,允许您添加各种功能,例如重试、回退或 PII 检测。有关更多信息,请参阅预构建中间件。deepagents 包还为相同的工作流提供了 createSummarizationMiddleware。有关更多详细信息,请参阅摘要。
特定于提供商的中间件
有关针对特定 LLM 提供商优化的特定于提供商的中间件,请参阅官方集成和社区集成。自定义中间件
您可以提供额外的中间件来扩展功能、添加工具或实现自定义钩子:子代理
要隔离详细工作并避免上下文膨胀,请使用子代理:后端
深度代理的工具可以利用虚拟文件系统来存储、访问和编辑文件。默认情况下,深度代理使用StateBackend。
如果您使用技能或记忆,则必须在创建代理之前将预期的技能或记忆文件添加到后端。
- StateBackend
- FilesystemBackend
- LocalShellBackend
- StoreBackend
- CompositeBackend
存储在
langgraph 状态中的临时文件系统后端。此文件系统仅在_单个线程_内持久化。沙箱
沙箱是专门的后端,在隔离环境中运行代理代码,具有自己的文件系统和用于 shell 命令的execute 工具。
当您希望深度代理写入文件、安装依赖项和运行命令而不更改本地计算机上的任何内容时,请使用沙箱后端。
您可以通过在创建深度代理时将沙箱后端传递给 backend 来配置沙箱:
Human in the Loop
某些工具操作可能很敏感,需要在执行前获得人类批准。 您可以为每个工具配置批准:技能
您可以使用技能为您的深度代理提供新的能力和专业知识。 虽然工具往往涵盖较低级别的功能,如原生文件系统操作或规划,但技能可以包含有关如何完成任务的详细说明、参考信息和其他资产,例如模板。 这些文件仅在代理确定该技能对当前提示有用时才会被代理加载。 这种渐进式披露减少了代理在启动时必须考虑的令牌和上下文数量。 有关示例技能,请参阅深度代理示例技能。 要将技能添加到您的深度代理,请将它们作为参数传递给create_deep_agent:
- 状态后端
- 存储后端
- 文件系统后端
记忆
使用AGENTS.md 文件为您的深度代理提供额外的上下文。
您可以在创建深度代理时将一个或多个文件路径传递给 memory 参数:
- StateBackend
- StoreBackend
- Filesystem
配置文件
工具配置文件打包了每个提供商或每个模型的调整(系统提示后缀、工具描述覆盖、排除的工具或中间件、额外的中间件以及通用子代理编辑),以便create_deep_agent 在选择匹配的模型时自动应用它们。
结构化输出
深度代理支持结构化输出。 您可以通过将所需的结构化输出模式作为responseFormat 参数传递给 createDeepAgent() 调用来设置它。
当模型生成结构化数据时,它会被捕获、验证,并在代理状态的 ‘structuredResponse’ 键中返回。
将这些文档连接到 Claude、VSCode 等,通过 MCP
获取实时答案。

