Function●Since v0.2

create_deep_agent

Create a Deep Agent.

By default, this agent has access to the following tools:

write_todos: manage a todo list
ls, read_file, write_file, edit_file, glob, grep: file operations
execute: run shell commands
task: call subagents

The execute tool allows running shell commands if the backend implements SandboxBackendProtocol. For non-sandbox backends, the execute tool will return an error message.

create_deep_agent(
  model: str | BaseChatModel | None = None,
  tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
  *,
  system_prompt: str | SystemMessage | None = None,
  middleware: Sequence[AgentMiddleware] = (),
  subagents: Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None,
  skills: list[str] | None = None,
  memory: list[str] | None = None,
  response_format: ResponseFormat[ResponseT] | type[ResponseT] | dict[str, Any] | None = None,
  context_schema: type[ContextT] | None = None,
  checkpointer: Checkpointer | None = None,
  store: BaseStore | None = None,
  backend: BackendProtocol | BackendFactory | None = None,
  interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
  debug: bool = False,
  name: str | None = None,
  cache: BaseCache | None = None
) -> CompiledStateGraph[AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]]

Parameters

Name	Type	Description
`model`	`str \| BaseChatModel \| None`	Default:`None` The model to use. Defaults to `claude-sonnet-4-6`. Accepts a `provider:model` string (e.g., `openai:gpt-5`); see `init_chat_model` for supported values. You can also pass a pre-initialized `BaseChatModel` instance directly. OpenAI Models and Data Retention If an `openai:` model is used, the agent will use the OpenAI Responses API by default. To use OpenAI chat completions instead, initialize the model with `init_chat_model("openai:...", use_responses_api=False)` and pass the initialized model instance here. To disable data retention with the Responses API, use `init_chat_model("openai:...", use_responses_api=True, store=False, include=["reasoning.encrypted_content"])` and pass the initialized model instance here.
`tools`	`Sequence[BaseTool \| Callable \| dict[str, Any]] \| None`	Default:`None` Additional tools the agent should have access to. These are merged with the built-in tool suite listed above (`write_todos`, filesystem tools, `execute`, and `task`).
`system_prompt`	`str \| SystemMessage \| None`	Default:`None` Custom system instructions to prepend before the base Deep Agent prompt. If a string, it's concatenated with the base prompt.
`middleware`	`Sequence[AgentMiddleware]`	Default:`()` Additional middleware to apply after the base stack but before the tail middleware. The full ordering is: Base stack: `TodoListMiddleware` `SkillsMiddleware` (if `skills` is provided) `FilesystemMiddleware` `SubAgentMiddleware` `SummarizationMiddleware` `PatchToolCallsMiddleware` `AsyncSubAgentMiddleware` (if async `subagents` are provided) User middleware is inserted here. Tail stack: `AnthropicPromptCachingMiddleware` `MemoryMiddleware` (if `memory` is provided) `HumanInTheLoopMiddleware` (if `interrupt_on` is provided)
`subagents`	`Sequence[SubAgent \| CompiledSubAgent \| AsyncSubAgent] \| None`	Default:`None` Subagent specs available to the main agent. This collection supports three forms: `SubAgent`: A declarative synchronous subagent spec. `CompiledSubAgent`: A pre-compiled runnable subagent. `AsyncSubAgent`: A remote/background subagent spec. `SubAgent` entries are invoked through the `task` tool. They should provide `name`, `description`, and `system_prompt`, and may also override `tools`, `model`, `middleware`, `interrupt_on`, and `skills`. See `interrupt_on` below for inheritance and override behavior. `CompiledSubAgent` entries are also exposed through the `task` tool, but provide a pre-built `runnable` instead of a declarative prompt and tool configuration. `AsyncSubAgent` entries are identified by their async-subagent fields (`graph_id`, and optionally `url`/`headers`) and are routed into `AsyncSubAgentMiddleware` instead of `SubAgentMiddleware`. They should provide `name`, `description`, and `graph_id`, and may optionally include `url` and `headers`. These subagents run as background tasks and expose the async subagent tools for launching, checking, updating, cancelling, and listing tasks. If no subagent named `general-purpose` is provided, a default general-purpose synchronous subagent is added automatically.
`skills`	`list[str] \| None`	Default:`None` List of skill source paths (e.g., `["/skills/user/", "/skills/project/"]`). Paths must be specified using POSIX conventions (forward slashes) and are relative to the backend's root. When using `StateBackend` (default), provide skill files via `invoke(files={...})`. With `FilesystemBackend`, skills are loaded from disk relative to the backend's `root_dir`. Later sources override earlier ones for skills with the same name (last one wins).
`memory`	`list[str] \| None`	Default:`None` List of memory file paths (`AGENTS.md` files) to load (e.g., `["/memory/AGENTS.md"]`). Display names are automatically derived from paths. Memory is loaded at agent startup and added into the system prompt.
`response_format`	`ResponseFormat[ResponseT] \| type[ResponseT] \| dict[str, Any] \| None`	Default:`None` A structured output response format to use for the agent.
`context_schema`	`type[ContextT] \| None`	Default:`None` Schema class that defines immutable run-scoped context. Passed through to `create_agent`.
`checkpointer`	`Checkpointer \| None`	Default:`None` Optional `Checkpointer` for persisting agent state between runs. Passed through to `create_agent`.
`store`	`BaseStore \| None`	Default:`None` Optional store for persistent storage (required if backend uses `StoreBackend`). Passed through to `create_agent`.
`backend`	`BackendProtocol \| BackendFactory \| None`	Default:`None` Optional backend for file storage and execution. Pass a `Backend` instance (e.g. `StateBackend()`). For execution support, use a backend that implements `SandboxBackendProtocol`.
`interrupt_on`	`dict[str, bool \| InterruptOnConfig] \| None`	Default:`None` Mapping of tool names to interrupt configs. Pass to pause agent execution at specified tool calls for human approval or modification. This config always applies to the main agent. For subagents: Declarative `SubAgent` specs inherit the top-level `interrupt_on` config by default. If a declarative `SubAgent` provides its own `interrupt_on`, that subagent-specific config overrides the inherited top-level config. `CompiledSubAgent` runnables do not inherit top-level `interrupt_on`; configure human-in-the-loop behavior inside the compiled runnable itself. Remote `AsyncSubAgent` specs do not inherit top-level `interrupt_on`; configure any approval behavior on the remote subagent itself. For example, `interrupt_on={"edit_file": True}` pauses before every edit.
`debug`	`bool`	Default:`False` Whether to enable debug mode. Passed through to `create_agent`.
`name`	`str \| None`	Default:`None` The name of the agent. Passed through to `create_agent`.
`cache`	`BaseCache \| None`	Default:`None` The cache to use for the agent. Passed through to `create_agent`.

View source on GitHub

create_deep_agent

Create a Deep Agent.

By default, this agent has access to the following tools:

write_todos: manage a todo list
ls, read_file, write_file, edit_file, glob, grep: file operations
execute: run shell commands
task: call subagents

The execute tool allows running shell commands if the backend implements SandboxBackendProtocol. For non-sandbox backends, the execute tool will return an error message.

Parameters

Name	Type	Description
`model`	`str \| BaseChatModel \| None`	Default:`None` The model to use. Defaults to `claude-sonnet-4-6`. Accepts a `provider:model` string (e.g., `openai:gpt-5`); see `init_chat_model` for supported values. You can also pass a pre-initialized `BaseChatModel` instance directly. OpenAI Models and Data Retention If an `openai:` model is used, the agent will use the OpenAI Responses API by default. To use OpenAI chat completions instead, initialize the model with `init_chat_model("openai:...", use_responses_api=False)` and pass the initialized model instance here. To disable data retention with the Responses API, use `init_chat_model("openai:...", use_responses_api=True, store=False, include=["reasoning.encrypted_content"])` and pass the initialized model instance here.
`tools`	`Sequence[BaseTool \| Callable \| dict[str, Any]] \| None`	Default:`None` Additional tools the agent should have access to. These are merged with the built-in tool suite listed above (`write_todos`, filesystem tools, `execute`, and `task`).
`system_prompt`	`str \| SystemMessage \| None`	Default:`None` Custom system instructions to prepend before the base Deep Agent prompt. If a string, it's concatenated with the base prompt.
`middleware`	`Sequence[AgentMiddleware]`	Default:`()` Additional middleware to apply after the base stack but before the tail middleware. The full ordering is: Base stack: `TodoListMiddleware` `SkillsMiddleware` (if `skills` is provided) `FilesystemMiddleware` `SubAgentMiddleware` `SummarizationMiddleware` `PatchToolCallsMiddleware` `AsyncSubAgentMiddleware` (if async `subagents` are provided) User middleware is inserted here. Tail stack: `AnthropicPromptCachingMiddleware` `MemoryMiddleware` (if `memory` is provided) `HumanInTheLoopMiddleware` (if `interrupt_on` is provided)
`subagents`	`Sequence[SubAgent \| CompiledSubAgent \| AsyncSubAgent] \| None`	Default:`None` Subagent specs available to the main agent. This collection supports three forms: `SubAgent`: A declarative synchronous subagent spec. `CompiledSubAgent`: A pre-compiled runnable subagent. `AsyncSubAgent`: A remote/background subagent spec. `SubAgent` entries are invoked through the `task` tool. They should provide `name`, `description`, and `system_prompt`, and may also override `tools`, `model`, `middleware`, `interrupt_on`, and `skills`. See `interrupt_on` below for inheritance and override behavior. `CompiledSubAgent` entries are also exposed through the `task` tool, but provide a pre-built `runnable` instead of a declarative prompt and tool configuration. `AsyncSubAgent` entries are identified by their async-subagent fields (`graph_id`, and optionally `url`/`headers`) and are routed into `AsyncSubAgentMiddleware` instead of `SubAgentMiddleware`. They should provide `name`, `description`, and `graph_id`, and may optionally include `url` and `headers`. These subagents run as background tasks and expose the async subagent tools for launching, checking, updating, cancelling, and listing tasks. If no subagent named `general-purpose` is provided, a default general-purpose synchronous subagent is added automatically.
`skills`	`list[str] \| None`	Default:`None` List of skill source paths (e.g., `["/skills/user/", "/skills/project/"]`). Paths must be specified using POSIX conventions (forward slashes) and are relative to the backend's root. When using `StateBackend` (default), provide skill files via `invoke(files={...})`. With `FilesystemBackend`, skills are loaded from disk relative to the backend's `root_dir`. Later sources override earlier ones for skills with the same name (last one wins).
`memory`	`list[str] \| None`	Default:`None` List of memory file paths (`AGENTS.md` files) to load (e.g., `["/memory/AGENTS.md"]`). Display names are automatically derived from paths. Memory is loaded at agent startup and added into the system prompt.
`response_format`	`ResponseFormat[ResponseT] \| type[ResponseT] \| dict[str, Any] \| None`	Default:`None` A structured output response format to use for the agent.
`context_schema`	`type[ContextT] \| None`	Default:`None` Schema class that defines immutable run-scoped context. Passed through to `create_agent`.
`checkpointer`	`Checkpointer \| None`	Default:`None` Optional `Checkpointer` for persisting agent state between runs. Passed through to `create_agent`.
`store`	`BaseStore \| None`	Default:`None` Optional store for persistent storage (required if backend uses `StoreBackend`). Passed through to `create_agent`.
`backend`	`BackendProtocol \| BackendFactory \| None`	Default:`None` Optional backend for file storage and execution. Pass a `Backend` instance (e.g. `StateBackend()`). For execution support, use a backend that implements `SandboxBackendProtocol`.
`interrupt_on`	`dict[str, bool \| InterruptOnConfig] \| None`	Default:`None` Mapping of tool names to interrupt configs. Pass to pause agent execution at specified tool calls for human approval or modification. This config always applies to the main agent. For subagents: Declarative `SubAgent` specs inherit the top-level `interrupt_on` config by default. If a declarative `SubAgent` provides its own `interrupt_on`, that subagent-specific config overrides the inherited top-level config. `CompiledSubAgent` runnables do not inherit top-level `interrupt_on`; configure human-in-the-loop behavior inside the compiled runnable itself. Remote `AsyncSubAgent` specs do not inherit top-level `interrupt_on`; configure any approval behavior on the remote subagent itself. For example, `interrupt_on={"edit_file": True}` pauses before every edit.
`debug`	`bool`	Default:`False` Whether to enable debug mode. Passed through to `create_agent`.
`name`	`str \| None`	Default:`None` The name of the agent. Passed through to `create_agent`.
`cache`	`BaseCache \| None`	Default:`None` The cache to use for the agent. Passed through to `create_agent`.

create_deep_agent

Parameters

LangChain Assistant

Menu

create_deep_agent

Parameters

create_deep_agent

Used in Docs

Parameters

Menu

create_deep_agent

Used in Docs

Parameters