create_deep_agent 提供 production-ready foundation:将它连接到你的 data、塑造其 behavior,并添加 use case 所需 capabilities。
createDeepAgent 默认随 pre-assembled harness 提供:filesystem、summarization、subagents 和 prompt caching。下方 parameters 可让你定义 agent persona、连接 data 和 tools,并用 additional middleware 扩展 stack。
| Parameter | 作用 |
|---|---|
model | 要使用的 model |
systemPrompt | Agent 的 custom instructions |
tools | Agent 可调用的 domain tools |
memory | Startup 时加载的 AGENTS.md files |
skills | 用于 on-demand knowledge 的 skills directory |
backend | Filesystem backend(默认 StateBackend) |
permissions | Filesystem 的 path-level access control |
subagents | 用于 delegated tasks 的 custom subagents |
middleware | 要添加到 stack 的 extra middleware |
interruptOn | 在 tool calls 前暂停以等待 human approval |
responseFormat | Structured output schema |
createDeepAgent API reference。若要从头组合 fully custom harness,请参阅 Configure the harness。
Model
传入provider:model 格式的 model string,或 initialized model instance。所有 providers 请参阅 supported models,经过测试的 recommendations 请参阅 suggested models。
- OpenAI
- Anthropic
- Azure
- Google Gemini
- Bedrock Converse
- Other
Tools
除用于 planning、file management 和 subagent spawning 的 built-in tools 外,你还可以提供 custom tools:MCP tools
安装@langchain/mcp-adapters 以连接 MCP servers:
System prompt
Deep Agents 附带 built-in system prompt。Deep agent 的价值来自 SDK 在 model 之上提供的 orchestration layer,包括 planning、virtual-filesystem tools 和 subagents,而 model 需要知道这些能力存在以及何时使用它们。Built-in prompt 会教 agent 如何使用这套 scaffolding,因此你无需为每个 project 重新推导;请通过 profile 或你自己的system_prompt= 调整它,而不是逐字复制。
当 middleware 添加 filesystem tools 等 special tools 时,它会将相关内容追加到 system prompt。
每个 deep agent 也应包含面向其 specific use case 的 custom system prompt:
Prompt assembly
Deep Agents 会从最多四个 named parts 构建 system prompt,让 caller-supplied instructions、SDK built-in agent guidance,以及任何 model-specific profile overrides 能以可预测 precedence 共存。如果没有这种 layering,针对 Claude 调优的 profile suffix 可能会根据 call order 覆盖你的system_prompt= argument,或被它覆盖;named slots 让 ordering 明确且稳定。
实践中,大多数 callers 只会遇到两个 slots:USER(你的 system_prompt=)和 BASE(SDK default)。选择带 built-in profile 的 model(目前为 Anthropic 或 OpenAI)会添加 SUFFIX。完整四段式 assembly 主要在你编写 custom HarnessProfile,或 debug profile text 为什么出现在某个位置时相关。
四个 named parts 如下(每个都可能不存在):
| Name | Source | Notes |
|---|---|---|
USER | system_prompt= argument to create_deep_agent | str or SystemMessage; omitted when unset. |
BASE | The SDK default (BASE_AGENT_PROMPT) | Always present unless replaced by a profile’s CUSTOM. |
CUSTOM | HarnessProfile.base_system_prompt | Replaces BASE outright when a matching profile sets it. |
SUFFIX | HarnessProfile.system_prompt_suffix | Appended last when a matching profile sets it. |
USER -> (BASE or CUSTOM) -> SUFFIX,并以空行(\n\n)连接。由此得到两个 invariants:
USER始终在最前面。 Caller text 位于任何 SDK 或 profile content 之前,因此无论选择哪个 model,persona/instructions 都优先。SUFFIX始终在最后。 Profile suffixes 最接近 conversation history,model-tuning guidance 在这里最可靠。
system_prompt= | profile base_system_prompt (CUSTOM) | profile system_prompt_suffix (SUFFIX) | Final assembled system prompt |
|---|---|---|---|
None | - | - | BASE |
None | - | ✓ | BASE + SUFFIX |
None | ✓ | - | CUSTOM |
None | ✓ | ✓ | CUSTOM + SUFFIX |
str | - | - | USER + BASE |
str | - | ✓ | USER + BASE + SUFFIX |
str | ✓ | - | USER + CUSTOM |
str | ✓ | ✓ | USER + CUSTOM + SUFFIX |
system_prompt_suffix,因此典型 call 会落在 str + - + ✓ 行:
传入
SystemMessage(而不是 string)会触发不同的 concatenation path:右侧 assembly(BASE-or-CUSTOM 加上任何 SUFFIX)会作为 additional text content block 追加到 message 现有的 content_blocks。相同 logical ordering 仍然适用(caller blocks 在前),并且 caller blocks 上的任何 cache_control markers 都会保留,这对于放置显式 Anthropic prompt-cache breakpoints 很有用。Subagent prompts
Subagent prompts
Prompt assembly overlay rules 也适用于 declarative subagents:每个 subagent 会针对自己的 model重新运行 profile resolution,然后将 resolved profile 的
Subagents 没有
base_system_prompt / system_prompt_suffix 应用于其 authored system_prompt。Subagent 的 system_prompt 扮演 BASE 角色;CUSTOM 和 SUFFIX 来自匹配 subagent model 的 profile(可能不同于 main agent profile)。spec["system_prompt"] | profile base_system_prompt (CUSTOM) | profile system_prompt_suffix (SUFFIX) | Final subagent system prompt |
|---|---|---|---|
| authored | - | - | authored |
| authored | - | ✓ | authored + SUFFIX |
| authored | ✓ | - | CUSTOM |
| authored | ✓ | ✓ | CUSTOM + SUFFIX |
USER segment。Spec 中 authored system_prompt 是最接近的 analog,并保留在 BASE slot 中。只附带 system_prompt_suffix 的 profile(built-in Anthropic / OpenAI profiles 的常见情况)只会追加到 subagent author 写入的内容后。设置 base_system_prompt 的 profile 会直接替换 authored prompt。General-purpose subagent prompt
General-purpose subagent prompt
Auto-added general-purpose subagent 遵循 prompt assembly overlay rules,但多一层:GP base prompt 会解析为
如果
general_purpose_subagent.system_prompt(如果设置)-> HarnessProfile.base_system_prompt(如果设置)-> SDK general-purpose default。无论哪种情况,profile suffix 都会叠加其上。这两个 override fields 都可以携带 base-prompt replacement,但它们不可互换。general_purpose_subagent.system_prompt 是 general-purpose-specific configuration;base_system_prompt 是主要面向 main agent 的 global override。当二者都设置时,general-purpose-specific intent 会在 general-purpose subagent 上胜出,因此同时调优两个 fields 的 user 不会看到 GP override 被静默丢弃:| Stack | Final system prompt |
|---|---|
| Main agent | "You are ACME's support orchestrator." + SUFFIX |
| GP subagent | "You are a research subagent. Cite sources." + SUFFIX |
general_purpose_subagent.system_prompt 未设置,GP subagent 会回退到 base_system_prompt(如果设置),最后回退到 SDK general-purpose default。Middleware
Deep Agents 支持任何 middleware,包括下方列出的 built-in middleware、来自 LangChain 的 prebuilt middleware、provider-specific middleware,以及你自己编写的 custom middleware。 将 middleware 传给createDeepAgent 的 middleware argument。
默认情况下,Deep Agents 可以访问以下 middleware:
Default stack (main agent)
从前到后:-
TodoListMiddleware: Tracks and manages todo lists for organizing agent tasks and work. -
SkillsMiddleware: Only when you passskills. Injected immediately after the todo middleware and before filesystem middleware so skill metadata is available before file tools run. -
FilesystemMiddleware: Handles file system operations such as reading, writing, and navigating directories. When you passpermissions, filesystem permissions enforcement is included here so it can evaluate every tool the agent might call. -
SubAgentMiddleware: Spawns and coordinates subagents for delegating tasks to specialized agents. -
SummarizationMiddleware: Condenses message history to stay within context limits when conversations grow long (via createSummarizationMiddleware). -
PatchToolCallsMiddleware: Automatic message history fixes when tool calls are interrupted or cancelled before receiving results. Runs before Anthropic prompt caching and the tail stack below. -
AsyncSubAgentMiddleware: Only when you configure async subagents. -
Your middleware argument: Optional middleware you pass as the
middlewareargument is appended here (after Patch, before the tail stack). - Harness profile extras: Provider-specific middleware from the resolved model profile, if any. tools from the agent.
-
AnthropicPromptCachingMiddleware: Automatically added when you are using an Anthropic mode. Runs after Patch and after your middleware so the cached prefix matches what is actually sent to the model. -
MemoryMiddleware: Only when you passmemory.MemoryMiddlewareis placed after profile extras and Anthropic prompt caching so updates to injected memory are less likely to invalidate the Anthropic cache prefix. The same ordering concern is called out in thecreateDeepAgentimplementation comments. -
HumanInTheLoopMiddleware: Only when you passinterruptOn. Pauses for human approval or input at configured tool calls. - Excluded-tool filtering: When the harness profile lists excluded tools, middleware removes those ```
Default stack (synchronous subagents)
The built-in general-purpose subagent and each declarative synchronousSubAgent graph use a stack that createDeepAgent builds in code. It matches the main agent in broad shape (todo list, filesystem, summarization, Patch, profile extras, Anthropic caching, optional permissions) but differs in two ways:
- Skills run after
PatchToolCallsMiddlewareon these inner agents (on the main agent, skills run before filesystem middleware whenskillsis set). - There is no
SubAgentMiddlewareinside a subagent graph (only the parent agent exposes thetasktool).
interruptOn, that value is forwarded to createAgent for the subagent, which wires up human-in-the-loop handling for the configured tool calls.
Prebuilt middleware
LangChain 暴露 additional prebuilt middleware,可让你添加 retries、fallbacks 或 PII detection 等各种 features。更多信息请参阅 Prebuilt middleware。deepagents package 也为同一 workflow 暴露 createSummarizationMiddleware。更多 details 请参阅 Summarization。
Provider-specific middleware
针对特定 LLM providers 优化的 provider-specific middleware,请参阅 Official integrations 和 Community integrations。Custom middleware
你可以提供 additional middleware 来扩展 functionality、添加 tools,或实现 custom hooks:Interpreters
使用 interpreters 添加在 scoped QuickJS runtime 中运行 JavaScript 的eval tool。当 agent 需要以编程方式组合 tools、batch work、在 code 中处理 errors,或在没有完整 shell environment 的情况下 transform structured data 时,Interpreters 很有用。
Subagents
若要隔离 detailed work 并避免 context bloat,请使用 subagents:Backends
Deep agent 的 tools 可以使用 virtual file systems 存储、访问和编辑 files。默认情况下,deep agents 使用StateBackend。
如果使用 skills 或 memory,必须先将预期的 skill 或 memory files 添加到 backend,然后再创建 agent。
- StateBackend
- FilesystemBackend
- LocalShellBackend
- StoreBackend
- ContextHubBackend
- CompositeBackend
存储在
langgraph state 中的 thread-scoped filesystem backend。Files 会在 thread 内跨 turns 持久存在(通过 checkpointer),但不会跨 threads 共享。Sandboxes
Sandboxes 是 specialized backends,会在带有独立 filesystem 和用于 shell commands 的execute tool 的 isolated environment 中运行 agent code。
当你希望 deep agent 写 files、安装 dependencies 并运行 commands,同时不更改 local machine 上任何内容时,请使用 sandbox backend。
创建 deep agent 时,将 sandbox backend 传给 backend 即可配置 sandboxes:
Human-in-the-loop
某些 tool operations 可能比较敏感,需要在执行前获得 human approval。 你可以为每个 tool 配置 approval:Skills
你可以使用 skills 为 deep agent 提供 new capabilities 和 expertise。 Tools 通常覆盖 native file system actions 或 planning 等 lower level functionality,而 skills 可以包含如何完成 tasks 的详细 instructions、reference info,以及 templates 等其他 assets。 这些 files 只有在 agent 判断 skill 对当前 prompt 有用时才会加载。 这种 progressive disclosure 会减少 agent 在 startup 时必须考虑的 tokens 和 context 数量。 示例 skills 请参阅 Deep Agents example skills。 若要向 deep agent 添加 skills,请将其作为 argument 传给create_deep_agent:
- StateBackend
- StoreBackend
- FilesystemBackend
Memory
使用AGENTS.md files 为 deep agent 提供 extra context。
创建 deep agent 时,可以向 memory parameter 传入一个或多个 file paths:
- StateBackend
- StoreBackend
- Filesystem
Structured output
Deep Agents 支持 structured output。 可以在调用createDeepAgent() 时通过 responseFormat argument 传入期望的 structured output schema。
当 model 生成 structured data 时,它会被 captured、validated,并在 agent state 的 structuredResponse key 中返回。
Advanced
createDeepAgent 会在 createAgent 之上预组装 middleware stack。若要构建 fully custom agent,并精确选择要包含哪些 capabilities,请参阅 Configure the harness。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

