create_deep_agent

create_deep_agent

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: list[SubAgent | CompiledSubAgent] | None = None,
    skills: list[str] | None = None,
    memory: list[str] | None = None,
    response_format: ResponseFormat | None = None,
    context_schema: type[Any] | 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

Create a deep agent.

Deep agents require a LLM that supports tool calling!

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.

PARAMETER	DESCRIPTION
model	The model to use. Defaults to claude-sonnet-4-5-20250929. Use the provider:model format (e.g., openai:gpt-5) to quickly switch between models. TYPE: str | BaseChatModel | None DEFAULT: None
tools	The tools the agent should have access to. In addition to custom tools you provide, deep agents include built-in tools for planning, file management, and subagent spawning. TYPE: Sequence[BaseTool | Callable | dict[str, Any]] | None DEFAULT: None
system_prompt	Custom system instructions to prepend before the base deep agent prompt. If a string, it's concatenated with the base prompt. TYPE: str | SystemMessage | None DEFAULT: None
middleware	Additional middleware to apply after the standard middleware stack (TodoListMiddleware, FilesystemMiddleware, SubAgentMiddleware, SummarizationMiddleware, AnthropicPromptCachingMiddleware, PatchToolCallsMiddleware). TYPE: Sequence[AgentMiddleware] DEFAULT: ()
subagents	The subagents to use. Each subagent should be a dict with the following keys: name description (used by the main agent to decide whether to call the sub agent) prompt (used as the system prompt in the subagent) (optional) tools (optional) model (either a LanguageModelLike instance or dict settings) (optional) middleware (list of AgentMiddleware) TYPE: list[SubAgent | CompiledSubAgent] | None DEFAULT: None
skills	Optional 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). TYPE: list[str] | None DEFAULT: None
memory	Optional 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. TYPE: list[str] | None DEFAULT: None
response_format	A structured output response format to use for the agent. TYPE: ResponseFormat | None DEFAULT: None
context_schema	The schema of the deep agent. TYPE: type[Any] | None DEFAULT: None
checkpointer	Optional Checkpointer for persisting agent state between runs. TYPE: Checkpointer | None DEFAULT: None
store	Optional store for persistent storage (required if backend uses StoreBackend). TYPE: BaseStore | None DEFAULT: None
backend	Optional backend for file storage and execution. Pass either a Backend instance or a callable factory like lambda rt: StateBackend(rt). For execution support, use a backend that implements SandboxBackendProtocol. TYPE: BackendProtocol | BackendFactory | None DEFAULT: None
interrupt_on	Mapping of tool names to interrupt configs. Pass to pause agent execution at specified tool calls for human approval or modification. Example: interrupt_on={"edit_file": True} pauses before every edit. TYPE: dict[str, bool | InterruptOnConfig] | None DEFAULT: None
debug	Whether to enable debug mode. Passed through to create_agent. TYPE: bool DEFAULT: False
name	The name of the agent. Passed through to create_agent. TYPE: str | None DEFAULT: None
cache	The cache to use for the agent. Passed through to create_agent. TYPE: BaseCache | None DEFAULT: None

RETURNS	DESCRIPTION
CompiledStateGraph	A configured deep agent.