create_cli_agent(
model: str | BaseChatModel,
assistant_id| Name | Type | Description |
|---|---|---|
model* | str | BaseChatModel | LLM model to use (e.g., |
assistant_id* | str | Agent identifier for memory/state storage |
tools | Sequence[BaseTool | Callable | dict[str, Any]] | None | Default: None |
mcp_tools | Sequence[BaseTool] | None | Default: None |
sandbox | SandboxBackendProtocol | None | Default: None |
sandbox_type | str | None | Default: None |
system_prompt | str | None | Default: None |
interactive | bool | Default: True |
auto_approve | bool | Default: False |
auto_mode_enabled | bool | Default: False |
interrupt_shell_only | bool | Default: False |
shell_allow_list | list[str] | None | Default: None |
fs_tools | list[FsToolName] | None | Default: None |
enable_ask_user | bool | Default: True |
enable_memory | bool | Default: True |
memory_auto_save | bool | Default: True |
enable_skills | bool | Default: True |
enable_shell | bool | Default: True |
enable_interpreter | bool | Default: False |
rubric_model | str | BaseChatModel | None | Default: None |
rubric_max_iterations | int | None | Default: None |
auto_classifier_model | str | BaseChatModel | None | Default: None |
recursion_limit | int | None | Default: None |
checkpointer | BaseCheckpointSaver | None | Default: None |
mcp_server_info | list[MCPServerInfo] | None | Default: None |
cwd | str | Path | None | Default: None |
project_context | ProjectContext | None | Default: None |
async_subagents | list[AsyncSubAgent] | None | Default: None |
goal_criteria_tools | Sequence[BaseTool | Callable[..., Any]] | None | Default: None |
rubric_grader_tools | Sequence[BaseTool | Callable[..., Any]] | None | Default: None |
Create a CLI-configured agent with flexible options.
This is the main entry point for creating a Deep Agents Code agent, usable both internally and from external code (e.g., benchmarking frameworks).
Additional tools to provide to agent.
Exact MCP tools within tools, used to extend approval policy
from their protocol annotations.
Optional sandbox backend for remote execution
(e.g., ModalSandbox).
If None, uses local filesystem + shell.
Type of sandbox provider
('agentcore', 'daytona', 'langsmith', 'modal', 'runloop').
Used for system prompt generation.
Override the default system prompt.
If None, a system prompt is auto-generated with dynamic context
interpolated in (model identity, working directory, sandbox vs.
local execution mode, skills path, and interactive-vs-headless
guidance).
Passing a value here replaces that auto-generated prompt
entirely — none of the dynamic context above is added, and
sandbox_type and interactive no longer influence the
prompt. Only pass an explicit prompt when you intend to take
full ownership of the system prompt's content.
When False, the auto-generated system prompt is
tailored for headless non-interactive execution, and every stack
gains terminal-stall recovery middleware (a runtime no-op unless the
resolved model is Fireworks GLM-5.2). Only the system-prompt
tailoring is ignored when system_prompt is provided explicitly;
the recovery wiring still applies.
If True, no tools trigger human-in-the-loop
interrupts — all calls (shell execution, file writes/edits,
web search, URL fetch) run automatically.
If False, tools pause for user confirmation via the approval menu.
See _add_interrupt_on for the full list of gated tools.
Install classifier-backed Auto for the local Textual runtime. Callers must leave this disabled for headless, remote, and sandbox-backed graphs.
If True, all HITL interrupts are disabled;
shell commands are validated inline by ShellAllowListMiddleware
against the configured allow-list instead.
Used in non-interactive mode with a restrictive shell allow-list to avoid splitting traces into multiple LangSmith runs.
Has no effect when auto_approve is True (interrupts are already
disabled) or when shell_allow_list is SHELL_ALLOW_ALL.
Explicit restrictive shell allow-list forwarded from
the CLI process. When provided (and interrupt_shell_only is
True), used directly instead of reading settings.shell_allow_list
(which may not be set in the server subprocess environment).
Allowlist of filesystem tools to expose to the agent, from
--allow-fs-tools. None (default; also what --allow-fs-tools all parses to) leaves FilesystemMiddleware at its SDK default
(all tools). An explicit list (which must include "read_file")
installs a FilesystemMiddleware restricted to those tool names,
replacing the SDK's default for the main agent and every synchronous
subagent (including general-purpose) as well as the nested
goal-criteria agent, so delegation cannot bypass the restriction.
Async subagents are unaffected (they run on their own remote
backend, not the local filesystem).
Enable AskUserMiddleware so the agent can ask
clarifying questions.
Non-interactive callers without a resume loop must explicitly pass
enable_ask_user=False.
Enable MemoryMiddleware for persistent memory
When True (default), the memory prompt tells the
agent to proactively persist learnings to the AGENTS.md sources.
When False, memory is still loaded into context but the read-only
prompt is used instead, so the agent does not auto-save; explicit
saves (e.g. the remember skill) still work.
No effect when
enable_memory is False.
Enable SkillsMiddleware for custom agent skills
Enable shell execution via LocalShellBackend
(only in local mode). When enabled, the execute tool is available.
Wire CodeInterpreterMiddleware from
langchain-quickjs into the main agent.
Local-mode only — passing a non-None sandbox while
enable_interpreter=True raises ValueError. Subagents do not
receive the interpreter in v1.
PTC (tools.* host bridge) calls bypass interrupt_on/HITL
approval, so settings.interpreter_ptc is the only effective
control over which host tools can be invoked from inside the
REPL. js_eval itself is intentionally not gated by HITL —
per-call approval would be unusably noisy and would not block
PTC fan-out anyway. The "safe" preset is therefore restricted
to tools that are already non-HITL outside the REPL (read-only
file inspection); exposing HITL-gated tools — network fetch,
subagent dispatch, shell, file writes — requires an explicit
list or interpreter_ptc="all" with
interpreter_ptc_acknowledge_unsafe=True.
Requires the core langchain-quickjs dependency.
Grader model for RubricMiddleware.
A 'provider:model' string or BaseChatModel.
When None, the main model is reused.
Explicit grader iterations per rubric attempt
before the agent terminates with 'max_iterations_reached'; None
uses the SDK default.
Model the Auto approval classifier reviews with.
A 'provider:model' string or BaseChatModel.
When None, DEEPAGENTS_CODE_AUTO_CLASSIFIER_MODEL is consulted,
then [models].auto_classifier, and the main model is reused when
both are unset. A blank string is not the same as None: it means
"inherit the main model" directly and, unlike None, does not
consult the env var or config.toml. Only meaningful when
auto_mode_enabled is True.
Explicit LangGraph recursion_limit (graph step budget)
for the main agent. When None, it is resolved from the
DEEPAGENTS_CODE_RECURSION_LIMIT env var, [runtime].recursion_limit
in config.toml, then the default via resolve_recursion_limit.
Optional checkpointer for session persistence.
When None, the graph is compiled without a checkpointer.
MCP server metadata to surface in the system prompt.
Override the working directory for the agent's filesystem backend and system prompt.
Explicit project path context for project-sensitive
behavior such as project AGENTS.md files, skills, subagents, and
MCP trust.
Remote LangGraph deployments to expose as async subagent tools.
Loaded from [async_subagents] in config.toml or passed directly.
External read-only context tools available to server-side
goal criteria generation. None disables goal criteria requests.
External read-only context tools available to rubric grading for verifying work completed in MCP-backed or web-accessible systems.